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/auth0.md

@@ -0,0 +1,198 @@
+# Auth0 OIDC runbook
+
+> Last reviewed: 2026-05-10
+
+This runbook wires certctl's OIDC SSO surface against [Auth0](https://auth0.com/), a commercial cloud IdP (now part of Okta but operationally distinct). Auth0 has a free developer tier suitable for evaluation; production runs on a paid B2B / B2C plan.
+
+For the canonical reference + mental model, read [keycloak.md](keycloak.md) first; this runbook only documents the Auth0-specific deltas.
+
+## The big Auth0 quirk: namespaced custom claims
+
+Auth0 imposes a hard rule: any custom claim emitted from an Action MUST use a namespaced URL-shape key (e.g. `https://your-namespace/groups`). Auth0 silently strips claims that look like standard OIDC claims (`groups`, `roles`, `permissions`, etc.) when emitted from an Action — this is a security feature to prevent claim-spoofing.
+
+certctl handles this via the `groups_claim_path` config. If your Action emits `https://your-namespace/groups`, set `OIDCProvider.groups_claim_path` to that exact URL. The hand-rolled groupclaim resolver at `internal/auth/oidc/groupclaim/resolver.go` recognizes URL-shape paths (anything starting with `http://` or `https://`) and treats the entire string as a single literal key — it does NOT split on `/`.
+
+Set `groups_claim_format` to `string-array`; the underlying claim shape is still a JSON array of group-name strings, just stored under a URL-shape key.
+
+## Prerequisites
+
+**On the Auth0 side:**
+
+- An Auth0 tenant (free dev tier at <https://auth0.com/signup> works). Tenant URL looks like `https://<tenant-name>.<region>.auth0.com`.
+- Owner or Auth0 Administrator role.
+- Network reachability from certctl-server to `https://<tenant>.auth0.com/.well-known/openid-configuration`.
+
+**On the certctl side:** same as Keycloak.
+
+## IdP-side configuration
+
+### 1. Pick a namespace string
+
+Decide on a unique URL-shape namespace for certctl's custom claims. It does NOT have to resolve to a real domain; Auth0 just requires it to be URL-shape and unique within your tenant. A reasonable choice:
+
+```
+https://certctl.example.com/auth/
+```
+
+Use that prefix for every custom claim; for groups specifically:
+
+```
+https://certctl.example.com/auth/groups
+```
+
+We'll refer to this as `<NS>/groups` in the rest of this runbook.
+
+### 2. Create the Application
+
+In the Auth0 dashboard:
+
+**Applications → Applications → Create Application**:
+
+- Name: `certctl`.
+- Application Type: **Regular Web Applications**.
+- Click **Create**.
+
+On the saved app's **Settings** tab:
+
+- Application Login URI: blank (Auth0 doesn't need it for the auth-code flow).
+- Allowed Callback URLs: `https://<your-certctl-host>:8443/auth/oidc/callback` (one entry, exact match).
+- Allowed Logout URLs: optional.
+- Allowed Web Origins: `https://<your-certctl-host>:8443`.
+- Token Endpoint Authentication Method: **Post** (default; matches the certctl service's expectation of `client_secret_post`).
+- Save Changes.
+
+Copy the **Domain** (this is the issuer base — `https://<tenant>.auth0.com`), **Client ID**, and **Client Secret** from the same Settings page.
+
+### 3. Configure the connection (where users live)
+
+If you're using Auth0's Database connection (default username + password), the existing **Username-Password-Authentication** connection works. For SSO to Google / Microsoft / SAML, configure those connections under **Authentication → Enterprise** or **Authentication → Social** and ensure the connection is enabled on the certctl Application (App → Connections tab).
+
+### 4. Define the groups
+
+Auth0 doesn't have a first-class "Groups" concept like Okta or Keycloak — you have THREE options to model groups, each with tradeoffs:
+
+**Option A: User app_metadata (simplest, recommended for dev tier).**
+
+Each user has a `app_metadata` JSON blob you can set via the Management API, the dashboard, or a post-registration script. Stick the groups in there:
+
+```json
+{
+  "groups": ["certctl-engineers"]
+}
+```
+
+In the Auth0 dashboard, **User Management → Users → <user> → app_metadata**: paste the JSON above and Save.
+
+**Option B: Auth0 Authorization Extension (paid plans, recommended for production).**
+
+Install the Authorization Extension from **Marketplace → Extensions → Authorization**. It adds a first-class "Groups" concept with UI for assignment + nested groups. Read the extension's docs; it emits groups under `<NS>/groups` automatically once enabled.
+
+**Option C: Roles + Permissions (Auth0's RBAC primitive).**
+
+Use **User Management → Roles** to define roles like `certctl-engineer` + `certctl-viewer`. Assign roles to users. Have your Action emit role names as a `groups` claim. This is what Auth0 documents as the canonical pattern; it's slightly heavier than Option A but more discoverable in the dashboard.
+
+This runbook uses **Option A** for clarity; the Action below reads from `app_metadata.groups`.
+
+### 5. Write the Action that emits the groups claim
+
+**Actions → Library → Create Action → Build from scratch**:
+
+- Name: `certctl-emit-groups`.
+- Trigger: **Login / Post Login**.
+- Runtime: Node 18.
+- Click **Create**.
+
+Paste this code:
+
+```javascript
+exports.onExecutePostLogin = async (event, api) => {
+  const namespace = "https://certctl.example.com/auth/";
+  const groups = (event.user.app_metadata && event.user.app_metadata.groups) || [];
+  if (groups.length > 0) {
+    api.idToken.setCustomClaim(namespace + "groups", groups);
+    api.accessToken.setCustomClaim(namespace + "groups", groups);
+  }
+};
+```
+
+Replace `https://certctl.example.com/auth/` with your namespace from step 1. Click **Deploy**.
+
+Then bind the Action to the Login flow:
+
+**Actions → Flows → Login**: drag `certctl-emit-groups` from the Custom tab into the flow, between Start and Complete. Click **Apply**.
+
+### 6. Verify the claim in a test login
+
+Auth0's **Authentication → Authentication Profile → Try It** button or the **Logs → Real-time Logs** page can show you the issued ID token in real time. Decode at jwt.io to confirm `<NS>/groups` is present + populated.
+
+## certctl-side configuration
+
+```bash
+curl -X POST https://<your-certctl-host>:8443/api/v1/auth/oidc/providers \
+  -H "Authorization: Bearer ${CERTCTL_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Auth0",
+    "issuer_url": "https://<tenant>.auth0.com/",
+    "client_id": "<paste-from-step-2>",
+    "client_secret": "<paste-from-step-2>",
+    "redirect_uri": "https://certctl.example.com:8443/auth/oidc/callback",
+    "groups_claim_path": "https://certctl.example.com/auth/groups",
+    "groups_claim_format": "string-array",
+    "fetch_userinfo": false,
+    "scopes": ["openid", "profile", "email"],
+    "iat_window_seconds": 300,
+    "jwks_cache_ttl_seconds": 3600
+  }'
+```
+
+Critical:
+
+- `issuer_url` includes the **trailing slash** for Auth0 (`https://<tenant>.auth0.com/`). Auth0's `iss` claim emits with the trailing slash; mismatching trips `ErrIssuerMismatch`.
+- `groups_claim_path` is the **full namespaced URL**, not the bare `groups` key. The certctl resolver treats this as a single literal lookup key against the ID token claims map (no path-walking through `/`).
+
+Add the group→role mappings: `certctl-engineers` → `r-operator`, etc. The mapping table maps the group VALUES (the strings inside the claim's array), not the claim path.
+
+## Verification
+
+End-to-end login + audit + Sessions checks are identical to Keycloak. The audit row's `details.subject` will be Auth0's user_id (e.g. `auth0|abc123…` for database users, `google-oauth2|...` for federated), stable across email changes.
+
+## Troubleshooting
+
+**`ErrGroupsUnmapped` even though I see groups in the ID token at jwt.io.**
+
+Check `groups_claim_path` exactly matches the namespaced key in the token. A common mistake: setting `groups_claim_path` to `groups` (the bare key) when the actual claim key is `https://certctl.example.com/auth/groups` (the namespaced version). The resolver's URL-shape detection is what makes the namespaced path work; if the claim path doesn't start with `http://` or `https://`, the resolver tries to walk it as a dot-separated path and fails.
+
+**The `<NS>/groups` claim is missing from the ID token.**
+
+- Action not bound to the Login flow: revisit step 5's "Apply" step.
+- Action returns early because `event.user.app_metadata.groups` is undefined: confirm the user has the metadata set.
+- Trying to set the claim under a non-namespaced key (e.g. `api.idToken.setCustomClaim("groups", groups)`): Auth0 silently drops it. Always use the namespace prefix.
+
+**Auth0 returns "Service not found" or "Invalid audience".**
+
+This usually means the certctl client wasn't authorized to access the userinfo endpoint or the application's `audience` setting conflicts with the OIDC discovery doc. The certctl service uses the Application's `client_id` as the `audience` claim — confirm Auth0 is emitting tokens with `aud = <client_id>` (decode at jwt.io).
+
+**Login redirects loop between Auth0 and certctl.**
+
+Most often a callback-URL mismatch — Auth0's "Allowed Callback URLs" must contain the EXACT certctl callback URL including port + scheme. Wildcards aren't allowed in production.
+
+**`email_verified` is `false` and certctl rejects the user.**
+
+certctl doesn't currently gate on `email_verified` — the User row stores email regardless. If your operator policy requires verified-only, add an Action that throws on `event.user.email_verified === false`:
+
+```javascript
+if (!event.user.email_verified) {
+  api.access.deny("email-not-verified");
+}
+```
+
+## Validation checklist
+
+Same as [keycloak.md](keycloak.md#validation-checklist) with Auth0-specific values, plus:
+
+- [ ] The `<NS>/groups` claim is present in the ID token (verify via jwt.io decode).
+- [ ] Removing a user's group from `app_metadata.groups` causes the next login to land on "no roles assigned".
+- [ ] The Auth0 dashboard's **Logs → Real-time Logs** shows the certctl callback completing with HTTP 302 to the dashboard.
+
+Sign-off: _______________ (operator) on _______________ (date).

docs/operator/oidc-runbooks/authentik.md

@@ -0,0 +1,144 @@
+# Authentik OIDC runbook
+
+> Last reviewed: 2026-05-10
+
+This runbook wires certctl's OIDC SSO surface against [Authentik](https://goauthentik.io/), a free / open-source IdP that runs on-prem or self-hosted. Authentik shares the canonical "string-array groups claim under the `groups` key" pattern with Keycloak — the differences are in the admin console UX and the explicit "property mapping" abstraction.
+
+For the canonical reference + mental model, read [keycloak.md](keycloak.md) first; this runbook only documents the Authentik-specific deltas.
+
+## Prerequisites
+
+**On the Authentik side:**
+
+- Authentik ≥ 2024.10 (stable channel).
+- Admin access to the Authentik admin console at `https://<authentik-host>/if/admin/`.
+- Network reachability from certctl-server to `https://<authentik-host>/application/o/<application-slug>/.well-known/openid-configuration`.
+
+**On the certctl side:** same as Keycloak — `CERTCTL_CONFIG_ENCRYPTION_KEY` set, an admin actor holding `auth.oidc.create` + `auth.oidc.edit`, Bundle 2 server build.
+
+## IdP-side configuration
+
+### 1. Create the OAuth2 / OpenID Provider
+
+In the Authentik admin console:
+
+**Applications → Providers → Create**:
+
+- Type: **OAuth2/OpenID Provider**.
+- Name: `certctl`.
+- Authorization flow: `default-provider-authorization-explicit-consent` (or `default-provider-authorization-implicit-consent` if you don't want a consent screen on every login).
+- Click **Next**.
+
+Protocol settings:
+
+- Client type: **Confidential**.
+- Client ID: leave the auto-generated value OR set to `certctl` for clarity.
+- Client Secret: copy the auto-generated value to a secure scratchpad — you'll paste it into certctl.
+- Redirect URIs/Origins: `https://<your-certctl-host>:8443/auth/oidc/callback` (one entry, exact match).
+- Signing Key: pick an **RSA-2048 or larger** key. Authentik defaults to ECDSA-P256 in newer versions; either is fine — both are in certctl's allow-list.
+- Subject mode: **Based on the User's hashed ID** (default; emits a stable opaque `sub`).
+- Include claims in id_token: **on**.
+- Click **Finish**.
+
+### 2. Create the Application
+
+Applications are how Authentik attaches a Provider to users + groups + policies.
+
+**Applications → Applications → Create**:
+
+- Name: `certctl`.
+- Slug: `certctl` (becomes part of the issuer URL: `https://<authentik-host>/application/o/certctl/`).
+- Provider: pick the `certctl` provider you just created.
+- Policy engine mode: **any** (default).
+- Click **Create**.
+
+### 3. Configure the groups property mapping
+
+Authentik emits group claims via "property mappings" — explicit objects rather than Keycloak's mapper-on-the-client model.
+
+By default, the **Authentik default-OAuth Mapping: Proxy outpost** scope already includes the user's groups under a `groups` claim (string-array, matches what certctl expects). To verify or override:
+
+**Customization → Property Mappings → Filter "Scope Mapping"**:
+
+- Find or create one named `groups` with scope `groups` and expression:
+  ```python
+  return [group.name for group in user.ak_groups.all()]
+  ```
+- Description: `Emits the user's group names as a string-array claim`.
+
+Then on the **Provider → certctl → Edit → Advanced protocol settings**, ensure **Scopes** includes `groups` (and `profile` and `email` if you want richer User records on the certctl side).
+
+### 4. Create the groups + assign users
+
+**Directory → Groups → Create**:
+
+- Name: `certctl-engineers`. Repeat for `certctl-viewers` (and optionally `certctl-admins`).
+
+**Directory → Users → <user> → Edit → Groups**: pick the appropriate `certctl-*` group(s) for each user.
+
+### 5. (Optional) Bind the application to specific groups
+
+If you want certctl to reject login attempts from users outside the `certctl-*` groups at the IdP layer (defense-in-depth on top of certctl's fail-closed `ErrGroupsUnmapped`):
+
+**Applications → certctl → Policy / Group / User Bindings → Create binding**:
+
+- Type: **Group**.
+- Group: pick the union of `certctl-*` groups you want to allow.
+- Enabled: on.
+
+## certctl-side configuration
+
+Identical to Keycloak — only the issuer URL differs:
+
+```bash
+curl -X POST https://<your-certctl-host>:8443/api/v1/auth/oidc/providers \
+  -H "Authorization: Bearer ${CERTCTL_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Authentik",
+    "issuer_url": "https://authentik.example.com/application/o/certctl/",
+    "client_id": "<paste-the-client-id>",
+    "client_secret": "<paste-the-client-secret>",
+    "redirect_uri": "https://certctl.example.com:8443/auth/oidc/callback",
+    "groups_claim_path": "groups",
+    "groups_claim_format": "string-array",
+    "fetch_userinfo": false,
+    "scopes": ["openid", "profile", "email", "groups"],
+    "iat_window_seconds": 300,
+    "jwks_cache_ttl_seconds": 3600
+  }'
+```
+
+Authentik emits `groups` in the ID token by default once the property mapping is configured. The `scopes` array MUST include `groups` to trigger the claim emission — Authentik is stricter than Keycloak about scope-gating claims.
+
+Add the group→role mappings the same way as Keycloak: `certctl-engineers` → `r-operator`, `certctl-viewers` → `r-viewer`.
+
+## Verification
+
+End-to-end login + audit + Sessions checks are identical to Keycloak.
+
+**Authentik-specific check:** the audit row's `details.subject` will be Authentik's hashed user ID (a 64-char hex), not the username. This is intentional and correct — the `sub` claim must be opaque + stable across user-attribute changes.
+
+**JWKS-rotation drill:** Authentik rotates signing keys via **System → Tokens & App Passwords → Certificates** (rename of "Crypto" in newer versions). Add a new RSA-2048 cert, switch the Provider's Signing Key to the new one, then click "Refresh discovery cache" in certctl's GUI to evict the cache.
+
+## Troubleshooting
+
+**Provider creation fails with "could not load discovery document".**
+The issuer URL needs the trailing slash for some Authentik versions: `https://authentik.example.com/application/o/certctl/` (slash after the slug). Without the slash, Authentik returns a 301 redirect that Go's HTTP client follows but discovery parsing chokes on the redirect target.
+
+**Login completes but user lands on "no roles assigned".**
+Decode the ID token at jwt.io against Authentik's JWKS. Check whether the `groups` claim is present + non-empty. If empty, the property mapping isn't wired — go back to step 3.
+
+**`groups` claim missing entirely.**
+Authentik gates the `groups` claim behind the `groups` scope. Verify:
+- The certctl OIDCProvider config has `"scopes": ["openid", "profile", "email", "groups"]`.
+- The Authentik provider's "Scopes" list includes `groups`.
+
+**Authentik emits the user's full DN as the `sub` claim.**
+Some Authentik configurations use **Subject mode: Based on the User's email** which surfaces the email as `sub`. This works but tightly couples certctl's User table to email mutability; recommend switching to "hashed ID" mode for new deployments. Existing User rows in certctl's `users` table will have email-shaped `oidc_subject` columns; that's fine and stable as long as the user's email never changes.
+
+## Validation checklist
+
+Same as [keycloak.md](keycloak.md#validation-checklist), with Authentik-specific values for issuer URL + group names + signing-key rotation steps.
+
+Sign-off: _______________ (operator) on _______________ (date).

docs/operator/oidc-runbooks/azure-ad.md

@@ -0,0 +1,207 @@
+# Microsoft Entra ID (Azure AD) OIDC runbook
+
+> Last reviewed: 2026-05-10
+
+This runbook wires certctl's OIDC SSO surface against [Microsoft Entra ID](https://learn.microsoft.com/entra/), formerly Azure AD. Entra ID is Microsoft's commercial cloud IdP; it's the default IdP for any organization on Microsoft 365 / Azure.
+
+For the canonical reference + mental model, read [keycloak.md](keycloak.md) first; this runbook only documents the Entra-ID-specific deltas.
+
+## The big Entra ID quirk: groups claim emits OBJECT IDs, not names
+
+Entra ID's `groups` claim emits a JSON array of **group object IDs (GUIDs)**, not human-readable names. A user in `Engineering Group` and `Cert Operators` will see something like:
+
+```json
+{
+  "groups": [
+    "8b9b1faa-4e83-471e-8b00-7d99c3e2a5f1",
+    "f00cf1e2-2db1-4cdf-a1ba-1234567890ab"
+  ]
+}
+```
+
+**You must configure your certctl group→role mappings against these GUIDs**, not against `Engineering Group` or `Cert Operators`. There are workarounds (cloud-only group display names + the optional claims path; see the alternative below) but the GUID-based approach is the only one that works reliably across all Entra ID configurations.
+
+This is by design at Microsoft — group names are mutable and not globally unique within a tenant; object IDs are immutable and globally unique. Operators on Microsoft 365 / Azure deployments are accustomed to managing access by GUID.
+
+## Prerequisites
+
+**On the Entra ID side:**
+
+- A Microsoft 365 tenant or standalone Azure AD tenant. Free Azure AD tier is sufficient; paid tiers (P1/P2) unlock conditional access + SCIM provisioning + risk-based auth, none of which are required for the basic OIDC integration.
+- Application Administrator or Global Administrator role.
+- Network reachability from certctl-server to `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`.
+
+**On the certctl side:** same as Keycloak.
+
+## IdP-side configuration
+
+### 1. Register the application
+
+In the [Entra ID admin center](https://entra.microsoft.com/):
+
+**Applications → App registrations → New registration**:
+
+- Name: `certctl`.
+- Supported account types: **Accounts in this organizational directory only** (single-tenant; matches the typical operator use case).
+- Redirect URI: **Web** + `https://<your-certctl-host>:8443/auth/oidc/callback`.
+- Click **Register**.
+
+On the saved app's **Overview** page, copy:
+
+- **Application (client) ID** → certctl's `client_id`.
+- **Directory (tenant) ID** → goes into the issuer URL.
+
+### 2. Create a client secret
+
+**App → Certificates & secrets → Client secrets → New client secret**:
+
+- Description: `certctl-server`.
+- Expires: 6 months / 12 months / 24 months — your choice. Set a calendar reminder; Entra ID does NOT auto-rotate secrets.
+- Click **Add**.
+
+Copy the **Value** column immediately — it's shown ONCE on creation. The certctl provider's `client_secret` field gets this value.
+
+(Production hardening: prefer **Certificates** over secrets for client authentication; certctl currently supports `client_secret_post` only, but a follow-on bundle can add `private_key_jwt` for cert-based client auth. Track this if you have a hard requirement against shared secrets.)
+
+### 3. Add the `groups` claim to the token
+
+**App → Token configuration → Add groups claim**:
+
+- Pick **Security groups** (covers most operators) OR **Groups assigned to the application** (more granular but requires Premium).
+- Token type: **ID token** + **Access token** (both, so userinfo fallback works).
+- Customize emit format for ID/access: leave as **Group ID** (default; this is the GUID-based path the runbook is structured around).
+- Click **Save**.
+
+If you instead want display names in the claim (only works for cloud-only groups; on-prem-synced groups continue to emit GUIDs regardless):
+
+- Customize emit format → **Cloud-only group display names**.
+- BUT — note this works only for groups created in Entra ID itself, not groups synced from on-prem AD. Hybrid environments will have inconsistent claims.
+
+### 4. Add the optional `email` and `profile` claims
+
+By default Entra ID's ID token does NOT include `email` — Microsoft considers email part of the "OIDC profile" but only emits it under specific conditions. To force emission:
+
+**App → Token configuration → Add optional claim → ID token → email**.
+
+You may also want `family_name`, `given_name`, `preferred_username` for richer User records on the certctl side.
+
+### 5. Grant the API permissions
+
+**App → API permissions**:
+
+- Microsoft Graph → Delegated permissions → ensure these are granted (most are default):
+  - `openid`
+  - `profile`
+  - `email`
+  - `offline_access` (optional; for refresh tokens — certctl doesn't use them currently).
+- Click **Grant admin consent** if your tenant requires it.
+
+### 6. (Optional) Restrict who can sign in
+
+By default any user in your tenant can attempt to sign in to the app. To restrict to specific users / groups:
+
+**Enterprise applications → certctl → Properties → Assignment required: Yes**.
+Then **Users and groups → Add user/group** and pick the `cert-engineers` / `cert-viewers` Entra ID groups.
+
+## certctl-side configuration
+
+```bash
+curl -X POST https://<your-certctl-host>:8443/api/v1/auth/oidc/providers \
+  -H "Authorization: Bearer ${CERTCTL_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Entra ID",
+    "issuer_url": "https://login.microsoftonline.com/<tenant-id>/v2.0",
+    "client_id": "<application-id>",
+    "client_secret": "<client-secret-value>",
+    "redirect_uri": "https://certctl.example.com:8443/auth/oidc/callback",
+    "groups_claim_path": "groups",
+    "groups_claim_format": "string-array",
+    "fetch_userinfo": false,
+    "scopes": ["openid", "profile", "email"],
+    "iat_window_seconds": 300,
+    "jwks_cache_ttl_seconds": 3600
+  }'
+```
+
+Notes:
+
+- `issuer_url` MUST include `/v2.0` at the end for the v2.0 endpoint. The v1.0 endpoint emits tokens with a different `iss` shape and is NOT supported by certctl. The discovery doc at `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration` confirms the right path.
+- `<tenant-id>` is the Directory (tenant) ID GUID from step 1.
+
+### Add the group→role mappings (GUID-keyed)
+
+Get the GUIDs of your engineering / viewer groups:
+
+**Entra ID → Groups → All groups → <group> → Overview → Object ID**.
+
+Then in certctl:
+
+```bash
+# Engineering group → r-operator
+curl -X POST https://<your-certctl-host>:8443/api/v1/auth/oidc/group-mappings \
+  -H "Authorization: Bearer ${CERTCTL_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "provider_id": "<provider-id>",
+    "group_name": "8b9b1faa-4e83-471e-8b00-7d99c3e2a5f1",
+    "role_id": "r-operator"
+  }'
+```
+
+Repeat for every group you want to map. **Document the GUID-to-name mapping in your operator runbook** — without it, the next operator looking at certctl's mappings page sees a wall of GUIDs with no way to know which is which. Consider naming the mapping descriptively if your group-mapping schema supports it (Bundle 2 doesn't yet — group-mapping descriptions are a parking-lot item for a follow-on bundle).
+
+## Verification
+
+End-to-end login + audit + Sessions checks are identical to Keycloak.
+
+**Entra-ID-specific:** the audit row's `details.subject` will be Microsoft's `oid` claim (a GUID, the user's object ID), stable across UPN / email changes. The certctl `users` table's `oidc_subject` column holds this GUID.
+
+**JWKS-rotation:** Microsoft auto-rotates signing keys on a documented schedule (every ~6 weeks). The discovery doc + JWKS endpoint always serve the union of active + recently-active keys, so in-flight logins continue to validate. No manual operator action needed in steady state. If you suspect a stuck cache after a Microsoft-side rotation, click "Refresh discovery cache" in the certctl GUI to evict.
+
+## Troubleshooting
+
+**Login completes; ID token contains a `hasgroups: true` claim instead of `groups`.**
+
+Entra ID emits this when a user is in too many groups (>200 by default for ID tokens, >150 for access tokens) — Microsoft truncates the claim and tells the consumer to use Microsoft Graph to look up the full list. certctl does NOT currently support the Graph fallback path (it's a follow-on bundle item).
+
+Workarounds:
+
+- Reduce the user's group membership to <200 (rarely practical in large tenants).
+- Restrict the `groups` claim to "Groups assigned to the application" (Token configuration step 3 above) instead of "Security groups". The "assigned" set is bounded by the app's user assignments and stays under the limit.
+- Use Entra ID's optional `wids` (well-known IDs) claim if you only care about admin/non-admin distinction; certctl can be configured against `wids` by setting `groups_claim_path` accordingly.
+
+**`groups` claim missing entirely.**
+
+Step 3 wasn't completed — Entra ID does NOT emit `groups` by default. Add the claim via Token configuration before users will see it.
+
+**`ErrIssuerMismatch` even though the `tid` in the token matches.**
+
+The v2.0 endpoint emits `iss = https://login.microsoftonline.com/<tenant-id>/v2.0` (no trailing slash). The v1.0 endpoint emits `iss = https://sts.windows.net/<tenant-id>/`. Confirm certctl's `issuer_url` matches v2.0 exactly — no trailing slash, includes `/v2.0`.
+
+**On-prem-synced groups emit GUIDs even when "Cloud-only display names" is selected.**
+
+Expected behavior — Microsoft only emits display names for groups created in Entra ID itself (cloud-only). On-prem-synced groups always emit object IDs. The hybrid case is unfixable from the IdP side; either map against GUIDs (recommended) or migrate the relevant groups to cloud-only.
+
+**The `email` claim is empty even though the user has a primary email.**
+
+Entra ID's `email` claim only populates when:
+1. The user has a "Primary email" set on their Entra ID profile (often blank for B2B guest users).
+2. The optional claim was added in step 4.
+
+For B2B guests, the `preferred_username` claim usually carries the email-shape login. You can configure certctl to use `preferred_username` as the user's display name fallback, but the `User.Email` column will remain blank — that's expected for guests.
+
+**Conditional Access policies blocking the login.**
+
+If your tenant has Conditional Access requiring MFA for new applications, certctl will see the user redirected through the MFA challenge. This works transparently — the certctl service doesn't care that MFA was performed; it only validates the resulting ID token. If MFA is failing for the user, debug at the Entra ID side (Sign-in logs).
+
+## Validation checklist
+
+Same as [keycloak.md](keycloak.md#validation-checklist), with these additions:
+
+- [ ] The ID token's `groups` claim is a string-array of GUIDs (decode at jwt.io).
+- [ ] Each certctl group-mapping uses the GUID, not a human-readable name.
+- [ ] A user with >200 groups successfully logs in (or the operator has documented the limitation + workaround in their internal runbook).
+- [ ] The Entra ID **Sign-in logs** view shows the certctl login event with status "Success".
+
+Sign-off: _______________ (operator) on _______________ (date).

docs/operator/oidc-runbooks/google-workspace.md

@@ -0,0 +1,186 @@
+# Google Workspace OIDC runbook (broker via Keycloak)
+
+> Last reviewed: 2026-05-10
+
+This runbook wires certctl's OIDC SSO surface against [Google Workspace](https://workspace.google.com/) (formerly G Suite). Google's OIDC implementation has a well-known limitation that makes it unsuitable for direct integration with certctl: **the ID token does not emit a groups claim**, so there is no way for certctl's `ErrGroupsUnmapped` fail-closed contract to resolve a user's role assignment.
+
+The recommended pattern is to **broker Google Workspace through Keycloak (or Authentik)** as a federated identity provider. The end-user still signs in with their Google account, but certctl talks to Keycloak — which DOES emit groups — instead of talking to Google directly.
+
+For the canonical reference + mental model, read [keycloak.md](keycloak.md) first; this runbook builds on top of it.
+
+## The Google Workspace quirk in detail
+
+**What Google emits in an ID token:** `iss`, `aud`, `sub`, `azp`, `exp`, `iat`, `email`, `email_verified`, `name`, `picture`, `given_name`, `family_name`, `locale`, `hd` (hosted domain). That's it.
+
+**What it does NOT emit:** `groups`, `roles`, `permissions`, or any indicator of the user's Google Workspace organizational unit / group membership.
+
+There is a **Cloud Identity Groups API** at `https://cloudidentity.googleapis.com/v1/groups/-/memberships:searchTransitiveGroups` that lets a privileged service account look up a user's groups, but:
+
+1. It requires a service account with domain-wide delegation, which is a major security surface to grant to certctl.
+2. It's a separate REST call after the OIDC flow, not a claim — certctl's group-claim resolver is path-shape, not API-shape.
+3. The latency budget of an extra API call per login is non-trivial in steady state.
+
+For these reasons, the broker pattern is strongly preferred. If you absolutely cannot deploy a broker, see "Direct integration without groups" at the bottom of this runbook for a degraded mode where every Google-authenticated user gets a single fixed role.
+
+## Architecture: broker pattern
+
+```
+end user → Google Workspace login → Keycloak (federated IdP) → certctl
+                                       ↑
+                                       │
+                          adds groups claim from Keycloak's group store
+                          (NOT from Google)
+```
+
+In this topology:
+
+- The end user's authentication credentials live at Google.
+- The user's group / role assignments live at Keycloak (manually or via SCIM provisioning from Google).
+- certctl talks ONLY to Keycloak. From certctl's perspective this is identical to the [keycloak.md](keycloak.md) runbook.
+
+## Prerequisites
+
+- A running Keycloak instance with a realm dedicated to certctl. Read [keycloak.md](keycloak.md) and complete that runbook FIRST against a local-only test user. Verify end-to-end OIDC works against Keycloak before adding Google as a federated provider.
+- A Google Workspace tenant where you have Super Admin access OR can ask your Workspace admin to create OAuth credentials.
+- A Google Cloud project (free; same console as Workspace).
+
+## IdP-side configuration
+
+### Step 1: create a Google OAuth client
+
+In the Google Cloud Console (`https://console.cloud.google.com/`):
+
+**APIs & Services → OAuth consent screen → Configure**:
+
+- User Type: **Internal** (restricts to your Workspace domain) OR **External** (any Google account; usually NOT what you want for an internal cert-management tool).
+- App name: `certctl SSO via Keycloak`.
+- User support email: your team's address.
+- Authorized domains: add the domain Keycloak runs on.
+- Save.
+
+**APIs & Services → Credentials → Create Credentials → OAuth client ID**:
+
+- Application type: **Web application**.
+- Name: `certctl-via-keycloak`.
+- Authorized redirect URIs: `https://<keycloak-host>/realms/<realm-name>/broker/google/endpoint` — this is Keycloak's default federated-IdP callback URL. Get the exact URL from Keycloak in step 2 below.
+- Click **Create**.
+
+Copy the **Client ID** and **Client secret**.
+
+### Step 2: add Google as a federated identity provider in Keycloak
+
+In the Keycloak admin console (`https://<keycloak-host>/admin/`):
+
+**Realm → Identity providers → Add provider → Google**:
+
+- Alias: `google` (becomes part of the broker URL).
+- Display name: `Google Workspace`.
+- Client ID: paste from step 1.
+- Client secret: paste from step 1.
+- Default scopes: `openid profile email`.
+- Hosted Domain: your Workspace domain (e.g. `example.com`); restricts to your tenant.
+- Sync mode: **Force** (rewrites the user's first/last name/email from Google on every login; the alternative `Import` only writes on first login).
+- Trust email: **on** (Google verifies emails; certctl-Keycloak chain inherits the trust).
+- Click **Save**.
+
+The **Redirect URI** field at the top of the saved provider's page shows the exact URL you should have entered in Google's console at step 1. Re-verify match.
+
+### Step 3: configure group assignment in Keycloak
+
+This is the load-bearing step — we're explicitly NOT trusting Google for groups, so Keycloak has to provide them.
+
+**Option A: Manual group assignment in Keycloak.**
+
+Federated users from Google appear in **Users** in Keycloak after their first login. You assign them to `certctl-engineers` / `certctl-viewers` / etc. groups in Keycloak's UI manually. Pro: simple. Con: doesn't scale; new hires can't log in until an operator adds them to a group.
+
+**Option B: Default groups via "Default Groups" realm config.**
+
+**Realm settings → User registration → Default Groups → Add**: pick the lowest-privilege group (e.g. `certctl-viewers`). Every new federated user lands here automatically; operators promote individual users to higher groups as needed.
+
+**Option C: Mapper that derives groups from Google claims.**
+
+If your Google Workspace has organizational units that align with your role split, you can add a Keycloak **Identity Provider Mapper** that maps `hd` (hosted domain) or a custom Google directory custom-schema field to a Keycloak group. This is moderately fragile and Workspace-version-dependent; recommend B for most operators.
+
+**Option D: SCIM provisioning from Google to Keycloak.**
+
+Google Workspace can SCIM-push group memberships to Keycloak via the SCIM-for-Google-Cloud-Identity feature. Heavyweight; recommend only if you already have SCIM infrastructure.
+
+This runbook uses **Option B** (default group) for clarity.
+
+### Step 4: verify the broker flow at Keycloak alone
+
+Before bringing certctl into the picture:
+
+1. Log out of Keycloak's admin console.
+2. Hit `https://<keycloak-host>/realms/<realm-name>/account` in an incognito window.
+3. Click "Sign in" — Keycloak's login page should now show **Sign in with Google Workspace** as a button below the local login form.
+4. Click it; authenticate via Google; you should land on Keycloak's account page.
+5. Back in the admin console, the user appears under **Users**. Confirm they're in the default group (Option B).
+
+Only proceed to step 5 when Keycloak alone works end to end.
+
+### Step 5: configure certctl against Keycloak (NOT against Google)
+
+Follow the [keycloak.md](keycloak.md) runbook. Use the realm + client + groups configuration you set up there. The `OIDCProvider.issuer_url` is `https://<keycloak-host>/realms/<realm-name>` — Keycloak's URL, not Google's.
+
+When the user clicks "Sign in with Keycloak" on certctl's login page, the browser flow is:
+
+1. certctl → Keycloak authorize endpoint.
+2. Keycloak's login page shows **Sign in with Google Workspace** + the local login form. User clicks Google.
+3. Keycloak → Google authorize endpoint. User authenticates at Google.
+4. Google → Keycloak callback (`/broker/google/endpoint`). Keycloak resolves the user, assigns the default group.
+5. Keycloak → certctl callback. certctl sees a normal Keycloak ID token with the `groups` claim populated by Keycloak.
+6. certctl mints the session.
+
+End-to-end the user clicks twice (Keycloak's "Sign in with Google" button + Google's consent / login). Subsequent logins skip the consent screen if Google's session is fresh.
+
+## Verification
+
+End-to-end login + audit + Sessions checks are identical to Keycloak. The key Google-Workspace-specific check:
+
+- The `users.oidc_subject` column in certctl's database should contain the Keycloak-side stable subject (a UUID), NOT the Google subject. Decode the certctl-side ID token and confirm `iss` is Keycloak's URL, `sub` is the Keycloak UUID. Don't confuse the certctl ID token with Google's ID token (which lives one hop upstream and certctl never sees directly).
+
+## Direct integration without groups (NOT RECOMMENDED)
+
+If broker deployment is impossible:
+
+1. Configure certctl with `issuer_url = https://accounts.google.com`, `client_id` + `client_secret` from your Google OAuth client (with redirect URI pointed at certctl directly).
+2. Add a SINGLE group→role mapping where `group_name` is the empty string. **Wait — certctl rejects empty group names.** This is the structural reason this mode doesn't work: the fail-closed contract requires a real group claim to match.
+
+The actual workaround is to manually add EVERY operator's email to a per-email mapping, OR to add a custom claim emitter at a thin proxy in front of Google. Both are hacks; the broker pattern is strictly better. We document the constraint here so future operators don't burn cycles trying to make it work.
+
+## Troubleshooting
+
+**Federated Google login completes at Keycloak but the user lands on "no roles assigned" at certctl.**
+
+The user authenticated through Google → Keycloak successfully but Keycloak didn't assign them a group (Option A wasn't completed for that user, or Option B's default group isn't mapped on the certctl side). Check:
+
+- Keycloak → Users → <user> → Groups: is the user in any `certctl-*` group?
+- certctl → Auth → OIDC Providers → Keycloak → Group → role mappings: is that group mapped?
+
+**Google login fails with "redirect_uri_mismatch".**
+
+The Google OAuth client's authorized redirect URI doesn't match Keycloak's broker callback URL exactly. Re-fetch the URL from Keycloak (Identity Providers → Google → Redirect URI field) and paste it verbatim into Google's console.
+
+**Google auto-closes the consent prompt and returns "access_denied".**
+
+Workspace admin policies may block third-party app access. Either the Google OAuth client wasn't approved by the Workspace admin (Google Workspace Admin Console → Security → API controls → Trusted apps), or the OAuth consent screen is configured for "External" but the user is from a different Workspace. Switch to "Internal" if everyone signing in is in the same Workspace.
+
+**Keycloak log shows "Federated identity returned no email claim".**
+
+You requested OAuth scopes other than `openid profile email`. Re-add `email` to the Default Scopes on the Keycloak Identity Provider config.
+
+**Sign-out from certctl doesn't sign the user out of Google.**
+
+Expected. certctl revokes its own session; Google's session continues independently. If the user needs to fully log out, they sign out at https://accounts.google.com/Logout. The certctl + Keycloak chain is the standard "single sign-on, separate sign-outs" model.
+
+## Validation checklist
+
+Same as [keycloak.md](keycloak.md#validation-checklist), with these additions:
+
+- [ ] Google → Keycloak federation works without certctl in the loop (step 4 above passes).
+- [ ] A first-time Google sign-in lands the user in the Keycloak default group (or whatever Option you picked).
+- [ ] The certctl audit row's `details.subject` is the Keycloak UUID, NOT Google's `sub` (which would be a Google account ID).
+- [ ] Removing a user from Google Workspace causes their NEXT certctl session-validate to fail (after their existing session expires) — verify with a deactivated test user.
+
+Sign-off: _______________ (operator) on _______________ (date).

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.

docs/operator/oidc-runbooks/keycloak.md

@@ -0,0 +1,245 @@
+# Keycloak OIDC runbook
+
+> Last reviewed: 2026-05-10
+
+This is the canonical reference runbook for wiring certctl's OIDC SSO surface against [Keycloak](https://www.keycloak.org/). Keycloak is a free / open-source identity provider that runs on-prem or self-hosted; it is also the load-bearing test fixture for Phase 10 of Auth Bundle 2 (`internal/auth/oidc/testfixtures/keycloak.go`), so the certctl-side validation pipeline is exhaustively exercised against it.
+
+If your IdP is something else (Okta, Auth0, Azure AD, Authentik, Google Workspace), see the per-IdP siblings in [this directory](index.md). The mental model + certctl-side wiring are identical; only the IdP-side console differs.
+
+## Prerequisites
+
+**On the Keycloak side:**
+
+- Keycloak ≥ 25.0 (older versions work but the screen flows differ slightly — the Phase 10 fixture pins 25.0).
+- Admin access to a realm — either an existing tenant realm or a fresh one created for certctl. Don't share Keycloak's `master` realm; create a dedicated realm.
+- Network reachability from certctl-server to the Keycloak `https://<keycloak-host>/realms/<realm-name>` discovery endpoint. The certctl service fetches `/.well-known/openid-configuration` at provider creation and at every `RefreshKeys` call.
+- Keycloak's signing alg set to RS256 (default) or any of: RS512, ES256, ES384, EdDSA. HS256/HS384/HS512 + `none` are rejected by certctl's IdP-downgrade-attack defense at provider creation time.
+
+**On the certctl side:**
+
+- `CERTCTL_CONFIG_ENCRYPTION_KEY` set to a stable secret (production deployments only — the encryption-at-rest layer for the OIDC client_secret depends on it).
+- An admin actor holding `auth.oidc.create` + `auth.oidc.edit` (held by `r-admin` by default; granted via `certctl_auth_assign_role_to_key` MCP tool or the GUI's Auth → Keys page).
+- Bundle 2 server build ≥ v2.1.0 (or post-`5204f1b` master).
+
+## IdP-side configuration
+
+The same configuration you'll do by hand here is what the Phase 10 testcontainers fixture imports from `internal/auth/oidc/testfixtures/keycloak-realm.json` — read that file alongside this runbook to see the exact JSON shape Keycloak persists.
+
+### 1. Create or pick a realm
+
+In the Keycloak admin console (`https://<keycloak-host>/admin/`), drop into the realm you'll use. If creating a new one, the realm name will become part of the issuer URL: `https://<keycloak-host>/realms/<realm-name>`.
+
+### 2. Create the OIDC client
+
+**Clients → Create client**:
+
+- Client type: **OpenID Connect**
+- Client ID: `certctl` (or whatever you prefer; it goes into `OIDCProvider.client_id` on the certctl side).
+- Always display in console: off.
+- Click **Next**.
+
+On the capability config page:
+
+- Client authentication: **On** (this makes the client confidential, which is what certctl requires).
+- Authorization: off.
+- Standard flow: **on** (auth-code with PKCE — this is the path certctl uses).
+- Direct access grants: off (ROPC; the test fixture turns this on for ROPC convenience but production should NOT).
+- Implicit flow: off.
+- Service accounts roles: off.
+- Click **Next**.
+
+Login settings:
+
+- Root URL: leave blank.
+- Home URL: blank.
+- Valid redirect URIs: `https://<your-certctl-host>:8443/auth/oidc/callback` — ONE entry, exact match. Wildcards (`*`) work for local dev (`http://localhost:*`) but production should pin the exact host.
+- Valid post logout redirect URIs: blank or `+` (matches the redirect URI list).
+- Web origins: `+` (matches the redirect URI origin) or empty.
+- Click **Save**.
+
+On the saved client's **Credentials** tab, copy the **Client secret** — you'll need it for the certctl-side payload.
+
+### 3. Create the groups
+
+**Groups → Create group**:
+
+- Repeat for every certctl role you want to map to a group. A typical setup creates two:
+  - `certctl-engineers` (intended target: `r-operator`)
+  - `certctl-viewers` (intended target: `r-viewer`)
+- Optionally an `certctl-admins` group → `r-admin` for break-glass-free first-admin bootstrap; see the [`auth-threat-model.md`](../auth-threat-model.md) section on bootstrap admins.
+
+### 4. Configure the group-membership claim mapper
+
+This is the load-bearing step — without it, the ID token won't carry a `groups` claim and every login fails closed with `ErrGroupsUnmapped`.
+
+**Clients → certctl → Client scopes → certctl-dedicated → Add mapper → By configuration → Group Membership**:
+
+- Name: `groups`
+- Token Claim Name: `groups`
+- Full group path: **off** (so the claim emits `engineers`, not `/engineers`; matches the certctl `string-array` group-claim format).
+- Add to ID token: **on**.
+- Add to access token: **on** (optional but recommended; the userinfo-fallback path uses it).
+- Add to userinfo: **on**.
+- Click **Save**.
+
+### 5. Create the user(s)
+
+**Users → Add user**:
+
+- Username: `alice` (or however you identify operators).
+- Email: required (used as the certctl-side `User.Email`).
+- First name + last name: optional but populates `User.DisplayName`.
+- Email verified: **on** if you trust the user.
+- Click **Create**.
+
+On the saved user's **Credentials** tab:
+- Set a password. Mark **Temporary** if you want the user to reset on first login.
+
+On the **Groups** tab:
+- Join the user to the group(s) you created in step 3.
+
+## certctl-side configuration
+
+### Via the GUI
+
+1. Sign in as an admin actor.
+2. Navigate to **Auth → OIDC Providers** in the sidebar.
+3. Click **Configure provider**.
+4. Fill in:
+   - **Display name**: `Keycloak` (free-text; what end-users see on the login page button).
+   - **Issuer URL**: `https://<keycloak-host>/realms/<realm-name>`.
+   - **Client ID**: `certctl` (matches step 2 above).
+   - **Client secret**: paste the secret from step 2's Credentials tab.
+   - **Redirect URI**: `https://<your-certctl-host>:8443/auth/oidc/callback`.
+   - **Groups claim path**: `groups` (the default; matches step 4's Token Claim Name).
+   - **Groups claim format**: `string-array` (the default).
+   - **Fetch userinfo**: off (Keycloak emits groups in the ID token; userinfo fallback is for IdPs that don't).
+   - **Scopes**: `openid profile email` (the certctl service prepends `openid` if missing).
+   - **IAT window seconds**: 300 (default).
+   - **JWKS cache TTL seconds**: 3600 (default).
+5. Click **Save**.
+
+If the discovery doc fetch fails, the modal surfaces the error inline. The most common cause is a typo in the issuer URL — Keycloak emits 404 for any path under `/realms/` that doesn't match an actual realm.
+
+### Via the API
+
+```bash
+curl -X POST https://<your-certctl-host>:8443/api/v1/auth/oidc/providers \
+  -H "Authorization: Bearer ${CERTCTL_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Keycloak",
+    "issuer_url": "https://keycloak.example.com/realms/certctl",
+    "client_id": "certctl",
+    "client_secret": "<paste-the-secret>",
+    "redirect_uri": "https://certctl.example.com:8443/auth/oidc/callback",
+    "groups_claim_path": "groups",
+    "groups_claim_format": "string-array",
+    "fetch_userinfo": false,
+    "scopes": ["openid", "profile", "email"],
+    "iat_window_seconds": 300,
+    "jwks_cache_ttl_seconds": 3600
+  }'
+```
+
+### Via MCP
+
+```
+certctl_auth_create_oidc_provider {
+  "name": "Keycloak",
+  "issuer_url": "https://keycloak.example.com/realms/certctl",
+  "client_id": "certctl",
+  "client_secret": "<paste-the-secret>",
+  "redirect_uri": "https://certctl.example.com:8443/auth/oidc/callback",
+  "groups_claim_path": "groups",
+  "groups_claim_format": "string-array",
+  "scopes": ["openid", "profile", "email"]
+}
+```
+
+### Add the group→role mappings
+
+GUI: **Auth → OIDC Providers → Keycloak → Group → role mappings → Add**.
+
+- IdP group: `certctl-engineers` → certctl role: `r-operator`.
+- IdP group: `certctl-viewers` → certctl role: `r-viewer`.
+
+API equivalent: `POST /api/v1/auth/oidc/group-mappings` with `{"provider_id": "<id>", "group_name": "certctl-engineers", "role_id": "r-operator"}`. MCP equivalent: `certctl_auth_add_group_mapping`.
+
+Empty mapping list = nobody can log in via Keycloak (the fail-closed contract). Add at least one before announcing the SSO endpoint to users.
+
+## Verification
+
+### End-to-end login
+
+1. Open `https://<your-certctl-host>:8443/login` in a fresh incognito window.
+2. The page renders an OIDC button block with `Sign in with Keycloak` (the display name from the create-provider step).
+3. Click it. The browser redirects to Keycloak, you authenticate as `alice`, Keycloak redirects back to certctl, and you land on the dashboard.
+4. Navigate to **Auth → Sessions**. You should see a row with your own actor ID, the IP you logged in from, and the current timestamp under "last seen".
+
+### Audit trail
+
+```bash
+curl https://<your-certctl-host>:8443/api/v1/audit?category=auth \
+  -H "Authorization: Bearer ${CERTCTL_API_KEY}" | jq '.events[] | select(.action == "auth.oidc_login_succeeded")'
+```
+
+You should see a row for the login above, with `details.provider_id` matching the Keycloak provider's id and `details.subject` set to the Keycloak user's `sub` claim (typically a UUID).
+
+### JWKS-rotation drill
+
+Operator action when Keycloak rotates its realm signing key:
+
+1. In Keycloak: **Realm settings → Keys → Providers → Add provider → rsa-generated**, set priority higher than the current key (e.g. 200), enabled = on, active = on.
+2. In certctl: GUI → **Auth → OIDC Providers → Keycloak → Refresh discovery cache** button. Or the CLI / MCP equivalent: `POST /api/v1/auth/oidc/providers/<id>/refresh`.
+3. Run another login. The new ID token is signed under the new key; the certctl service validates it against the freshly-fetched JWKS doc.
+
+The Phase 10 integration test `TestKeycloakIntegration_JWKSRotation_RefreshKeysPicksUpNewKey` exercises this exact flow end to end.
+
+## Troubleshooting
+
+**"Discovery doc fetch failed" at provider creation.**
+The most common cause is a wrong issuer URL — typo in realm name, missing `/realms/` segment, or HTTP→HTTPS redirect that the Go client doesn't follow without explicit headers. Curl the URL manually:
+```
+curl -v https://<keycloak-host>/realms/<realm-name>/.well-known/openid-configuration
+```
+If that returns 404, fix the realm name. If it returns 200 but certctl still fails, check `cmd/server` logs for the wrapped error.
+
+**"IdP downgrade-attack defense" rejected provider creation.**
+Keycloak's realm has a signing key advertised in `id_token_signing_alg_values_supported` that's in certctl's deny-list (HS256/HS384/HS512/`none`). Check **Realm settings → Keys → Providers** — disable any HMAC key providers and re-create the provider in certctl.
+
+**Login redirects to Keycloak, the user authenticates, but the callback redirects back to `/login` with "no roles assigned".**
+The user authenticated successfully but their groups didn't match any configured mapping (`ErrGroupsUnmapped`). Check:
+- The user is actually a member of the group you mapped (Users → user → Groups tab in Keycloak).
+- The group-membership mapper is configured correctly (Clients → certctl → Client scopes → certctl-dedicated → mappers → groups → "Full group path: off" matters).
+- The group name in your certctl mapping exactly matches what Keycloak emits — case-sensitive, no leading slash if "Full group path: off".
+
+You can confirm what Keycloak is actually emitting by decoding the ID token at jwt.io against the Keycloak public key, or by enabling certctl's debug logging on the OIDC service for one login (logs are scrubbed of token contents per the Phase 3 token-leak hygiene contract; debug logs surface only the resolved group list and the mapping decision).
+
+**"id_token verify failed: token used before issued"**
+Clock skew between Keycloak and certctl-server. Either align both to NTP, or bump `iat_window_seconds` on the OIDC provider config (default 300 = 5 minutes). The certctl service caps `iat_window_seconds` at 600.
+
+**"oidc: pre-login session not found or already consumed"**
+The user clicked the OIDC login button, then the browser tab idled past the 10-minute pre-login TTL OR the user opened the IdP login in a new tab and consumed the row from the first one. Have them retry.
+
+**"oidc: state parameter mismatch (replay or forgery)"**
+Either the user double-submitted a callback URL (clicked it twice from email or browser history), or a CSRF attempt. The pre-login row is single-use; second consumption returns `ErrPreLoginNotFound`. Have them retry from the login page.
+
+**Sessions revoked but the user can still hit the API.**
+Check the Phase 4 session contract: the cookie is HMAC-validated on every request, but the actual database row is what `Revoke` deletes. If your reverse proxy is caching the response or the `certctl_session` cookie wasn't actually cleared on the client, the cookie will hit the server's session middleware which will return 401 on the missing-row lookup. The middleware never serves stale data; the issue is upstream of certctl in this case.
+
+## Validation checklist
+
+Before signing off this runbook for production rollout, validate these end-to-end:
+
+- [ ] `auth.oidc_provider_created` audit row appears after the create-provider POST.
+- [ ] `Sign in with Keycloak` button renders on the login page after `getAuthInfo` returns the configured provider.
+- [ ] A user with mapped groups completes the auth-code flow and lands on the dashboard.
+- [ ] A user WITHOUT mapped groups gets the "no roles assigned" landing (not the dashboard).
+- [ ] The `auth.oidc_login_succeeded` and `auth.oidc_login_failed` audit rows correctly distinguish the two cases.
+- [ ] The Sessions page shows the new session, with self-pill on the caller's row.
+- [ ] Revoking the session via the GUI causes the next API request from that browser to 401 + redirect to login.
+- [ ] Running the JWKS-rotation drill (steps above) does not break in-flight logins; rotated tokens validate against the refreshed JWKS.
+- [ ] Editing the provider with `client_secret` blank preserves the existing ciphertext (operator confirms by reading the `oidc_providers.client_secret_encrypted` column before + after the PUT — bytes unchanged).
+
+Sign-off: _______________ (operator) on _______________ (date).

docs/operator/oidc-runbooks/okta.md

@@ -0,0 +1,143 @@
+# Okta OIDC runbook
+
+> Last reviewed: 2026-05-10
+
+This runbook wires certctl's OIDC SSO surface against [Okta](https://www.okta.com/), a commercial cloud IdP. Okta offers a free developer tier (`https://dev-NNNNN.okta.com`) suitable for evaluation; production runs on a paid Workforce Identity tenant.
+
+For the canonical reference + mental model, read [keycloak.md](keycloak.md) first; this runbook only documents the Okta-specific deltas.
+
+## Prerequisites
+
+**On the Okta side:**
+
+- A Workforce Identity tenant (or free Developer Edition account at <https://developer.okta.com/signup/>).
+- Super Admin or Application Admin role in your Okta tenant.
+- Network reachability from certctl-server to `https://<your-org>.okta.com/.well-known/openid-configuration` OR to a custom authorization server endpoint if you're using one (`https://<your-org>.okta.com/oauth2/<auth-server-id>/.well-known/openid-configuration`).
+
+**On the certctl side:** same as Keycloak.
+
+## IdP-side configuration
+
+### 1. Create the OIDC application
+
+In the Okta admin console:
+
+**Applications → Applications → Create App Integration**:
+
+- Sign-in method: **OIDC - OpenID Connect**.
+- Application type: **Web Application**.
+- Click **Next**.
+
+App config:
+
+- App integration name: `certctl`.
+- Logo: optional.
+- Grant types: **Authorization Code** (CHECK). Leave Refresh Token unchecked unless you have a specific reason — certctl doesn't currently use refresh tokens.
+- Sign-in redirect URIs: `https://<your-certctl-host>:8443/auth/oidc/callback`.
+- Sign-out redirect URIs: optional; leave empty unless you also configure RP-initiated logout.
+- Trusted Origins: leave default.
+- Assignments → Controlled access: **Limit access to selected groups** (recommended; pick the `certctl-*` groups from step 3 below).
+- Click **Save**.
+
+On the saved app's **General** tab, copy the **Client ID** and **Client secret** (under Client Credentials). The secret is shown once on creation — copy it immediately or rotate via "Generate new secret".
+
+### 2. Pick or create an authorization server
+
+Okta has TWO authorization-server tiers:
+
+- **The Org Authorization Server** at `https://<your-org>.okta.com` — emits ID tokens with limited claims; cannot host custom claims directly. Use for the simplest setup.
+- **A Custom Authorization Server** at `https://<your-org>.okta.com/oauth2/<auth-server-id>` — fully configurable scopes + claims + access policies. The free developer tier ships with a default custom server at `/oauth2/default`. Recommended for production.
+
+For this runbook we use the default custom server: `https://<your-org>.okta.com/oauth2/default`.
+
+### 3. Create the groups + assign users
+
+**Directory → Groups → Add Group**:
+
+- Repeat for `certctl-engineers`, `certctl-viewers`, optionally `certctl-admins`.
+
+**Directory → People → <user> → Groups**: assign each user to the appropriate `certctl-*` group(s).
+
+Then go back to the App from step 1 and on the **Assignments** tab, assign the `certctl-*` groups to the application. Without this assignment Okta will reject the user's login attempt at the IdP layer with "User is not assigned to the client application".
+
+### 4. Configure the groups claim
+
+This is the load-bearing Okta-specific step. The default authorization server does NOT emit a `groups` claim out of the box — you have to define it.
+
+**Security → API → Authorization Servers → default → Claims → Add Claim**:
+
+- Name: `groups`.
+- Include in token type: **ID Token, Always** (also tick Access Token if you want the userinfo-fallback path to work).
+- Value type: **Groups**.
+- Filter: pick **Matches regex** with the value `certctl-.*` so only the `certctl-*` groups are emitted (saves on token size; users in dozens of unrelated groups get a bloated token otherwise).
+- Disable claim: off.
+- Include in: **Any scope** (or pin to `openid` if you want the claim only on the certctl-flow).
+- Click **Create**.
+
+### 5. (Optional) Add `email` and `profile` claims
+
+The default custom server already emits `email` and `name` under the `profile` and `email` scopes — no action needed unless you've stripped them from a custom config.
+
+## certctl-side configuration
+
+```bash
+curl -X POST https://<your-certctl-host>:8443/api/v1/auth/oidc/providers \
+  -H "Authorization: Bearer ${CERTCTL_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Okta",
+    "issuer_url": "https://your-org.okta.com/oauth2/default",
+    "client_id": "<paste-from-step-1>",
+    "client_secret": "<paste-from-step-1>",
+    "redirect_uri": "https://certctl.example.com:8443/auth/oidc/callback",
+    "groups_claim_path": "groups",
+    "groups_claim_format": "string-array",
+    "fetch_userinfo": false,
+    "scopes": ["openid", "profile", "email"],
+    "iat_window_seconds": 300,
+    "jwks_cache_ttl_seconds": 3600
+  }'
+```
+
+Notes:
+
+- `issuer_url` MUST match exactly what Okta emits as the `iss` claim. For the default custom server it's `https://<your-org>.okta.com/oauth2/default` (no trailing slash). The org server's issuer is just `https://<your-org>.okta.com` (no `/oauth2/...` path). Mismatching either side trips certctl's `ErrIssuerMismatch` sentinel.
+- The `groups` scope is NOT required in the scopes list — Okta emits the claim based on the claim definition's "Include in: any scope" setting. Adding `groups` to the scopes list is harmless if your custom server has the scope defined.
+
+Add the group→role mappings: `certctl-engineers` → `r-operator`, `certctl-viewers` → `r-viewer`, `certctl-admins` → `r-admin`.
+
+## Verification
+
+End-to-end login + audit + Sessions checks are identical to Keycloak.
+
+**Okta-specific:** the audit row's `details.subject` will be Okta's user UID (a 20-char alphanumeric string starting with `00u`), stable across email changes. The certctl `users` table's `oidc_subject` column will hold this UID.
+
+**Optional Okta smoke test in CI:** Phase 10 ships an opt-in smoke test at `internal/auth/oidc/integration_okta_smoke_test.go` (build tags `integration && okta_smoke`). Set `OKTA_ISSUER` + `OKTA_CLIENT_ID` + `OKTA_CLIENT_SECRET` env vars and run `make okta-smoke-test` to drive a discovery + RefreshKeys round-trip against your live tenant. Pre-reqs: enable the Resource Owner Password (ROPC) grant on the application (Sign-On tab → Grant types → Resource Owner Password) for the smoke test only; production certctl uses auth-code-with-PKCE.
+
+**JWKS-rotation drill:** Okta auto-rotates signing keys every ~3 months and publishes the new key alongside the old in the JWKS doc for ~1 month overlap. Manual rotation: **Security → API → Authorization Servers → default → Keys → "Generate new key"**. After rotation, click "Refresh discovery cache" in certctl's GUI; new tokens validate immediately.
+
+## Troubleshooting
+
+**"User is not assigned to the client application" at the Okta login screen.**
+You created the app + the user but didn't assign the user to the app via a group. Either assign the user directly (App → Assignments → Assign to People) or assign the `certctl-*` groups to the app (App → Assignments → Assign to Groups).
+
+**Login completes but `groups` claim is empty in the ID token.**
+Most common Okta gotcha — the default custom server doesn't emit `groups` until you define the claim (step 4 above). Decode the ID token at jwt.io to confirm. If the claim is defined but empty, check the regex filter in step 4 — `certctl-.*` matches names like `certctl-engineers` but NOT `engineers`.
+
+**`ErrIssuerMismatch` after correctly configuring the discovery URL.**
+The issuer claim Okta puts in the ID token MUST match `OIDCProvider.IssuerURL` byte-for-byte, including trailing slash. The default custom server emits `https://<your-org>.okta.com/oauth2/default` (no trailing slash); the org server emits `https://<your-org>.okta.com`. Don't append a trailing slash to either.
+
+**Login succeeds but the certctl `User.Email` is empty.**
+The `email` scope wasn't requested OR the user's email isn't verified at Okta. Add `email` to the certctl scopes config and ensure Okta's user has a verified primary email.
+
+**Okta returns "PKCE code verifier required".**
+The certctl service hard-codes PKCE-S256 on every login (RFC 9700 mandate). If Okta is rejecting the verifier, the most likely cause is a misconfigured app type — confirm the Okta application is "Web Application" (which supports auth-code + PKCE), not "Single-Page Application" (which has different token-binding rules) or "Native App".
+
+**Custom-server access policies blocking the login.**
+By default the `default` custom authorization server has an "Access Policy" with one rule allowing all clients + all users. If you've tightened this (production hygiene), add a rule that allows the `certctl` client + the `certctl-*` groups: **Security → API → Authorization Servers → default → Access Policies → <policy> → Add Rule**.
+
+## Validation checklist
+
+Same as [keycloak.md](keycloak.md#validation-checklist), with Okta-specific values + the access-policy check above.
+
+Sign-off: _______________ (operator) on _______________ (date).