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.
This commit is contained in:
shankar0123
2026-05-11 16:54:07 +00:00
parent 1b03d0c594
commit 56e2ea1ad7
20 changed files with 260 additions and 292 deletions
+13 -15
View File
@@ -5,7 +5,7 @@
This is the upgrade guide for an existing certctl deployment moving
from v2.0.x's "every API key is admin or not" model to v2.1.0's
RBAC primitive. Everything keeps working through the upgrade - the
Bundle 1 migration backfills every existing API key to the
migration backfills every existing API key to the
`r-admin` role on first boot, so the pre-existing automation that
was using those keys does not change behavior. **However**, most
keys do not need full admin power; this guide walks the operator
@@ -13,7 +13,7 @@ through the post-upgrade scope-down flow.
## ⚠️ SECURITY: AUDIT YOUR API KEYS
Bundle 1 maps **every** existing `CERTCTL_API_KEYS_NAMED` entry
v2.1.0 maps **every** existing `CERTCTL_API_KEYS_NAMED` entry
(and every legacy `CERTCTL_AUTH_SECRET`-synthesized key) to the
`r-admin` role on the first boot after migration 000029 applies.
This is the safe-for-back-compat default - your CI / agents / scripts
@@ -29,18 +29,18 @@ release notes for v2.1.0 lead with this callout for a reason.
### 1. Apply the migration
The migration runner is idempotent. Re-applying is a no-op if the
schema is already at the target version. Migrations that ship in
the Bundle 1 slice of v2.1.0:
schema is already at the target version. The five RBAC migrations
that ship in v2.1.0:
| Migration | What it does |
|---|---|
| `000029_rbac.up.sql` | Creates `tenants`, `roles`, `permissions`, `role_permissions`, `actor_roles`. Seeds 7 default roles + 33-permission catalogue + the synthetic `actor-demo-anon` admin grant. Backfills every named API key into `actor_roles` with the `r-admin` role. |
| `000030_rbac_admin_perms.up.sql` | Seeds 5 admin-only fine-grained permissions (`cert.bulk_revoke`, `crl.admin`, `scep.admin`, `est.admin`, `ca.hierarchy.manage`) into `r-admin` only. |
| `000031_api_keys.up.sql` | Creates the `api_keys` table for runtime-minted keys (Bundle 1 Phase 6 bootstrap). |
| `000031_api_keys.up.sql` | Creates the `api_keys` table for runtime-minted keys (day-0 bootstrap path). |
| `000032_audit_category.up.sql` | Adds `event_category` column to `audit_events` with the closed enum (`cert_lifecycle` / `auth` / `config`). |
| `000033_approval_kinds.up.sql` | Adds `approval_kind` + `payload` to `issuance_approval_requests` for the Phase 9 approval-bypass closure. |
| `000033_approval_kinds.up.sql` | Adds `approval_kind` + `payload` to `issuance_approval_requests` for the approval-bypass closure. |
The Bundle 1 server applies these on first boot. No operator
The v2.1.0 server applies these on first boot. No operator
action is required other than running the upgrade.
### 2. Verify the backfill landed
@@ -147,8 +147,8 @@ bootstrap flow + the threat model.
## What changes for code that called `IsAdmin`
Pre-Bundle-1, the five admin handlers checked `auth.IsAdmin(ctx)`
directly in the body. Bundle 1 Phase 3.5 moved those checks to
In v2.0.x, the five admin handlers checked `auth.IsAdmin(ctx)`
directly in the body. v2.1.0 moved those checks to
the router via the `auth.RequirePermission` middleware (wrapped
through the `rbacGate` helper in
`internal/api/router/router.go`). The behavior contract is
@@ -164,9 +164,9 @@ the helper is internal), the new convention is:
(or `migrations/000029_rbac.up.sql`'s catalogue).
3. Grant the perm to the right default roles.
The five admin-only fine-grained perms shipped in Phase 3.5 stay
on `r-admin` only by default. Operators delegate by creating
custom roles with the specific perm.
The five admin-only fine-grained perms stay on `r-admin` only by
default. Operators delegate by creating custom roles with the
specific perm.
## Helm-specific upgrade
@@ -288,9 +288,7 @@ boot regardless of schema version).
- [`docs/operator/auth-threat-model.md`](../operator/auth-threat-model.md) -
what the new controls defend against
- [`docs/reference/profiles.md`](../reference/profiles.md) - the
Phase 9 approval-bypass closure
approval-bypass closure on `RequiresApproval` profile edits
- [`docs/operator/security.md`](../operator/security.md) - the
full security posture
- `cowork/auth-bundle-1-prompt.md` - the design + phase plan
- `cowork/auth-bundles-index.md` - the per-phase status tracker
- `CHANGELOG.md` - the v2.1.0 release notes lead with this guide