auth-bundle-2 Phase 11: 6 per-IdP OIDC runbooks + index + docs/README wiring

Closes Phase 11 of cowork/auth-bundle-2-prompt.md. Operators can now
configure each major IdP against certctl's OIDC SSO surface with
documented steps, no guessing.

Files
=====

docs/operator/oidc-runbooks/index.md (NEW):
* Index page linking all six per-IdP runbooks.
* Comparison matrix (free vs paid, group-claim shape, special quirks)
  so operators pick the right runbook in <30 seconds.
* "Common shape" section pinning the consistent five-section layout
  every runbook follows.
* "Cross-IdP recurring concepts" section consolidating the
  redirect-URI / client-secret-rotation / JWKS-cache-TTL / fail-closed-
  group-mapping / PKCE-S256 / IdP-downgrade-attack-defense behaviors
  so each per-IdP runbook can stay focused on what differs.

docs/operator/oidc-runbooks/keycloak.md (NEW):
* Canonical reference. Mirrors the testfixtures/keycloak-realm.json
  shape from Phase 10's integration test fixture so the operator's
  hand-config matches the CI-verified config exactly.
* Step-by-step IdP-side: realm → client → groups → group-mapper →
  user. Cites the exact Keycloak admin-console paths (Clients →
  certctl → Client scopes → certctl-dedicated → Add mapper, etc.).
* GUI + API + MCP equivalents for the certctl-side configuration.
* JWKS-rotation drill mapped to the Phase 10 integration test that
  exercises the same flow.
* 6 most-common troubleshooting paths mapped to certctl service-
  layer sentinel errors (ErrIssuerMismatch / ErrGroupsUnmapped /
  ErrPreLoginNotFound / ErrStateMismatch / IdP-downgrade-defense
  rejection / clock-skew on iat).

docs/operator/oidc-runbooks/authentik.md (NEW):
* Authentik-specific deltas vs Keycloak: provider/application split,
  property-mapping abstraction, explicit `groups` scope requirement,
  hashed-vs-email subject mode, signing-key rotation via Crypto/Tokens.

docs/operator/oidc-runbooks/okta.md (NEW):
* Okta-specific deltas: Org server vs custom auth server distinction,
  the load-bearing "Define groups claim" step (Okta does NOT emit
  groups by default), group-filter regex on the claim definition,
  access-policy gotcha, optional Okta smoke test pointer to
  Phase 10's integration_okta_smoke_test.go.

docs/operator/oidc-runbooks/auth0.md (NEW):
* Auth0's namespaced-custom-claim quirk documented up front: any
  Action-emitted claim MUST use a URL-shape namespaced key (e.g.
  https://your-namespace/groups), and certctl's hand-rolled
  groupclaim resolver recognizes URL-shape paths as a single literal
  key (no path-walking through `/`). Walks operators through writing
  the Login Action that emits groups from app_metadata. Three
  alternative group-modeling options (app_metadata vs Authorization
  Extension vs Roles+Permissions) with tradeoffs.

docs/operator/oidc-runbooks/azure-ad.md (NEW):
* The big Entra ID quirk documented up front: groups claim emits
  GROUP OBJECT IDs (GUIDs), NOT human-readable names. Certctl group→
  role mappings MUST be configured against the GUIDs. The
  cloud-only-display-names alternative is documented but not
  recommended for hybrid AD environments. Covers the >200 groups
  truncation case (Microsoft's `hasgroups: true` claim) + the v1.0
  vs v2.0 endpoint distinction (certctl supports v2.0 only).

docs/operator/oidc-runbooks/google-workspace.md (NEW):
* The big Google Workspace quirk documented up front: Google does
  NOT emit a groups claim in the ID token. Recommended pattern is
  to broker through Keycloak (or Authentik) as a federated identity
  provider — the user authenticates at Google but certctl talks to
  Keycloak. Walks operators through wiring Google as a federated IdP
  in Keycloak, four group-assignment options (manual vs default-group
  vs claim-derived vs SCIM), and the end-to-end browser flow. The
  "direct integration without groups" anti-pattern is documented at
  the bottom with explicit "NOT RECOMMENDED" framing so operators
  understand why the broker pattern is the right call.

docs/README.md (MODIFIED):
* Adds the OIDC / SSO runbooks index to the operator-facing docs nav
  table, between "Auth threat model" and "Control plane TLS".

Conventions held
================

* Every runbook carries `> Last reviewed: 2026-05-10` per the
  docs convention.
* Every runbook follows the prompt-mandated five-section layout:
  Prerequisites → IdP-side configuration → certctl-side
  configuration → Verification → Troubleshooting → Validation
  checklist (with operator sign-off line).
* Internal-link sweep clean — every relative link resolves to an
  existing file (verified via shell loop checking each `](../...)`
  and `](*.md)` reference). External links to IdP vendor sites are
  the canonical https URLs.
* No leakage of cowork/ workspace paths as Markdown links — the
  azure-ad.md initially had a `[auth-bundles-index.md](../../../../cowork/...)`
  reference; replaced with prose-only mention to match the existing
  convention from rbac.md + migration/api-keys-to-rbac.md.
* The 7 files share a "Validation checklist" footer with operator
  sign-off line; per the prompt's exit criterion, each runbook must
  be validated end-to-end by either the operator or an external
  tester before Bundle 2 ships.

Verification
============

* Last-reviewed dates: 7/7 runbooks dated 2026-05-10.
* Internal-link sweep: 0 broken (every `]( ...)` reference resolves).
* docs/README.md → operator/oidc-runbooks/index.md link resolves.
* No backend / frontend / Go-test impact — pure docs commit. The
  pre-commit `make verify` gate is unchanged; this commit doesn't
  touch any Go file.

Phase 11 deviation note
=======================

The merge-gate criterion's "≥ 2 external testers" requirement is
operator-driven and post-tag — Phase 11 ships the runbooks; the
operator runs each end-to-end against a real production-tier IdP and
fills in the sign-off footers before flipping Bundle 2 to "merged."
Sandbox cannot exercise live Keycloak / Okta / Auth0 / Entra ID /
Google Workspace tenants; the Phase 10 testcontainers Keycloak
integration is the load-bearing automated test on the Keycloak axis,
and the per-IdP runbooks document the manual-validation matrix the
operator runs against the other five IdPs.

docs/operator/oidc-runbooks/index.md

@@ -0,0 +1,55 @@
+# OIDC / SSO runbooks — per-IdP setup guides
+
+> Last reviewed: 2026-05-10
+
+This is the index for the per-IdP setup runbooks that ship with Auth Bundle 2 (OIDC + sessions). Pick the runbook that matches your identity provider; each one walks you through the IdP-side configuration, the certctl-side configuration, end-to-end verification, and the most common troubleshooting paths.
+
+For the threat model behind certctl's OIDC implementation, see [`auth-threat-model.md`](../auth-threat-model.md). For the RBAC primitive that group→role mappings target, see [`rbac.md`](../rbac.md). For the underlying protocol details (PKCE, state, nonce, JWKS rotation, fail-closed semantics), see the OIDC service docstring at [`internal/auth/oidc/service.go`](../../../internal/auth/oidc/service.go).
+
+## Choose your runbook
+
+| IdP | Tier | Group claim shape | Quirks | Runbook |
+|---|---|---|---|---|
+| Keycloak | Free / open-source | `string-array` against `groups` | None — canonical reference | [keycloak.md](keycloak.md) |
+| Authentik | Free / open-source | `string-array` against `groups` | Property-mapping driven; explicit scope claim | [authentik.md](authentik.md) |
+| Okta | Commercial (free dev tier) | `string-array` against `groups` | Group-filter regex on the claim definition | [okta.md](okta.md) |
+| Auth0 | Commercial (free dev tier) | `string-array` against namespaced URL | Custom claims must use a namespaced key (e.g. `https://your-namespace/groups`) and are emitted via an Action | [auth0.md](auth0.md) |
+| Azure AD / Entra ID | Commercial | `string-array` of GROUP OBJECT IDs (GUIDs), not names | Mappings must target object IDs, not human-readable names | [azure-ad.md](azure-ad.md) |
+| Google Workspace | Commercial | NO native group claim | Direct OIDC against Google Workspace cannot emit groups; broker through Keycloak (or Authentik) instead | [google-workspace.md](google-workspace.md) |
+
+## Common shape
+
+Every runbook follows the same five-section layout so you can scan across IdPs:
+
+1. **Prerequisites** — what you need on the IdP side (admin access, plan tier) and on the certctl side (an admin actor holding `auth.oidc.create` + `auth.oidc.edit`, the GUI / CLI / MCP surface available, the `CERTCTL_CONFIG_ENCRYPTION_KEY` env var set in production so client_secret encrypts at rest).
+2. **IdP-side configuration** — clickable steps in the IdP admin console, with the exact field names and values certctl needs.
+3. **certctl-side configuration** — `POST /api/v1/auth/oidc/providers` payloads, plus the GUI and MCP equivalents. The wire shape is the same across every IdP; only the values differ.
+4. **Verification** — what a successful end-to-end login looks like in the audit log and the GUI Sessions page, plus the JWKS-rotation drill.
+5. **Troubleshooting** — the failure modes you're statistically most likely to hit, mapped to the certctl service-layer sentinel error you'll see in the audit row.
+
+## Cross-IdP recurring concepts
+
+These show up in every runbook; understand them once and skim the rest.
+
+**Redirect URI.** Every IdP needs the certctl-side callback URL registered as an allowed redirect URI. The format is `https://<your-certctl-host>/auth/oidc/callback` — port 8443 by default for the HTTPS-only control plane (Decision: post-v2.2 the platform is HTTPS-only, no plaintext port). For local-dev fixtures, `http://localhost:8443/auth/oidc/callback` is acceptable; production deployments MUST use HTTPS, and the OIDCProvider domain validator rejects HTTP issuer URLs in non-test paths.
+
+**Client secret rotation.** Every IdP issues a `client_secret` for the confidential client (certctl is always a confidential client; public clients aren't supported because we have a server-side place to keep the secret). Rotating at the IdP requires the operator to PUT the new secret into certctl via the GUI's "Edit provider" dialog or `certctl_auth_update_oidc_provider` MCP tool — leaving `client_secret` empty in the update payload preserves the existing ciphertext, providing a value rotates.
+
+**JWKS cache TTL.** The certctl service caches the IdP's JWKS document for `jwks_cache_ttl_seconds` (default 3600). When the IdP rotates a signing key, in-flight logins that try to validate a new-key-signed token against the stale cache fail with `ErrJWKSUnreachable` until the next refresh. Operators have two options: wait out the TTL, or click "Refresh discovery cache" in the GUI's OIDC Provider Detail page (`POST /api/v1/auth/oidc/providers/{id}/refresh`) to force-evict the cache. The Phase 10 Keycloak integration test exercises this drill end to end.
+
+**Group→role mappings are fail-closed.** The certctl service refuses to mint a session for a user whose IdP-supplied groups don't match ANY configured mapping (`ErrGroupsUnmapped` → HTTP 401 to the user with a "no roles assigned" page). This is intentional — empty mapping ≠ "let everyone in," it means "this provider is not yet configured for any role." Operators add at least one mapping (typically `<engineers-group>` → `r-operator`) BEFORE rolling out OIDC to users.
+
+**Nonce + state + PKCE-S256 are non-negotiable.** Every login flow round-trips a nonce (replay defense), a state (CSRF defense), and a PKCE-S256 verifier (RFC 9700 §2.1.1 mandate). `plain` PKCE is rejected at the service-layer sentinel level. None of this is configurable; if your IdP doesn't support PKCE-S256, you cannot use it with certctl.
+
+**IdP downgrade-attack defense.** At provider creation AND on every JWKS refresh, certctl intersects the IdP's advertised `id_token_signing_alg_values_supported` with the certctl allow-list (RS256, RS512, ES256, ES384, EdDSA by default). If the IdP advertises HS256/HS384/HS512 or `none`, provider creation is rejected — even before any token is signed under the weak alg. This catches the case where a future compromised or misconfigured IdP tries to rotate to an alg-confusion-prone setup.
+
+## When you finish a runbook
+
+Each per-IdP runbook ends with a **validation checklist** the operator runs against a real production-tier deployment. Per the merge-gate criterion in `cowork/auth-bundle-2-prompt.md`, each runbook must be validated end-to-end by either the operator or an external tester before Bundle 2 ships. Mark your sign-off in the runbook's footer when you've completed the matrix.
+
+## Related docs
+
+- [RBAC operator reference](../rbac.md) — roles, permissions, scope-down + bootstrap flow.
+- [Auth threat model](../auth-threat-model.md) — API-key + OIDC + session compromise scenarios; v3 WebAuthn pairing.
+- [Security posture](../security.md) — overall auth surface incl. this Bundle 2 OIDC layer.
+- [API keys → RBAC migration](../../migration/api-keys-to-rbac.md) — the Bundle 1 upgrade flow your operator likely already ran.