3 Commits

Author	SHA1	Message	Date
shankar0123	56e2ea1ad7	docs: v2.1.0 release polish — strip internal bundle/phase tags, update status for OIDC ship ... README: - Rewrite Status block: drop the stale 'federated identity not yet shipped' line; flag v2.1.0 OIDC + sessions + back-channel logout + break-glass as early-access; encourage GitHub issues for IdP rough edges. (A1 framing — keep early-access umbrella, no SAML/WebAuthn/JIT roadmap teaser.) - Add OIDC SSO bullet to 'What it does' covering per-IdP runbooks, group-claim → role mapping, AES-256-GCM client_secret encryption, JWKS auto-refresh, PKCE-S256, RFC 9700 §4.7.1 pre-login binding, RFC 9207 iss check, __Host- cookies, CSRF rotation, idle+absolute expiry, BCL, break-glass admin. - Update Security paragraph: three auth paths (API keys / OIDC / break-glass), HMAC-signed sessions, CSRF rotation, RFC OIDC BCL. - Correct CI coverage thresholds against .github/coverage-thresholds.yml (service 70%, handler 75%, crypto 88%, auth packages 85-95%); 'static analysis' replaces the inflated '11 linters' claim (actual count is 4 active). Docs B3 sweep — strip operator-facing 'Bundle N' / 'Phase N' tags: - docs/operator/auth-threat-model.md — rewrite intro; rename 5 H2 sections (API-key + RBAC defenses / OIDC + sessions + break-glass defenses / OIDC + sessions threat catalogue / Closed federated- identity threats / Future-work threats); clean ~12 H3/prose hits. - docs/operator/rbac.md — strip Bundle 1 framing from intro, scope_id deferral note, MCP tools section, day-0 bootstrap, and 'Where to look next'. - docs/operator/auth-benchmarks.md — drop 'Phase 14' framing from title intro, hardware floor caption, result table caption, methodology, and pre-merge audit section. - docs/operator/security.md — already cleaned earlier this session (RBAC / day-0 / approval-bypass / OIDC federation / sessions / OIDC first-admin / break-glass H3s). - docs/operator/oidc-runbooks/{index,keycloak,authentik,okta, azure-ad}.md — strip Auth Bundle 2 framing + Phase 10/3/4 references; replace with feature-name prose. - docs/operator/legacy-clients-tls-1.2.md — drop Bundle F / M-023 audit-reference framing; keep CWE-326. - docs/operator/database-tls.md — drop Bundle B / M-018 framing from intro + Helm section. - docs/operator/runbooks/disaster-recovery.md — drop 'Production hardening II Phase 10' status callout. - docs/migration/oidc-enable.md — retitle 'Enable OIDC SSO'; strip Bundle 1/2 framing from prereqs, troubleshooting, related docs; update __Host- cookie callout from 'audit MED-14' to v2.1.0-BREAKING. - docs/migration/api-keys-to-rbac.md — strip Bundle 1 framing from intro, migration table, IsAdmin section, and cross-references. - docs/migration/acme-from-cert-manager.md — strip residual 'Phase 5' tags from cert-manager integration test references. - docs/reference/configuration.md — retitle Auth section. - docs/reference/profiles.md — strip Bundle 1 Phase 9 framing from RequiresApproval section + Related list. - docs/reference/auth-standards-implemented.md — rewrite intro (API-key + RBAC + OIDC + sessions + back-channel logout + break-glass); rename 'Bundle 1 (RBAC) standards covered separately' H2; clean per-row Phase references. - docs/README.md — rewrite nav-table entries to drop Bundle 1/2 parentheticals; retitle 'Enable OIDC SSO' migration entry. No code or test changes; pure operator-facing prose polish for the v2.1.0 tag.	2026-05-11 16:54:07 +00:00
shankar0123	f203a5372d	auth-bundle-2 Phase 11 follow-on: drop external-tester reference from oidc-runbooks/index.md ... The 'external tester' merge-gate criterion was removed from the auth-bundles-index.md policy: external-tester confirmations are encouraged but NOT a merge condition (BSL discourages contribution- style testing; the Phase 10 Keycloak testcontainers harness + the optional Okta smoke test cover the same surface deterministically in CI). Drops the now-stale phrasing from the runbooks index and the merge-gate reference; keeps the operator-sign-off footer recommendation since dated validation records are still useful.	2026-05-10 15:58:03 +00:00
shankar0123	2893f9b48e	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.	2026-05-10 15:49:56 +00:00