mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-12 13:58:51 +00:00
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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user