mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 12:41:30 +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:
+18
-17
@@ -9,14 +9,14 @@
|
||||
> [`security.md#demo-to-production-cutover-audit-2026-05-11-a-8`](security.md#demo-to-production-cutover-audit-2026-05-11-a-8).
|
||||
|
||||
This is the operator-facing reference for the role-based access
|
||||
control primitive that ships with Bundle 1 (auth bundle 1) of certctl.
|
||||
control primitive in certctl.
|
||||
Read this if you're running certctl in production and need to grant /
|
||||
revoke access to API keys, set up the auditor split, or onboard the
|
||||
first admin.
|
||||
|
||||
For the threat model behind these controls, see
|
||||
[`auth-threat-model.md`](auth-threat-model.md). For the migration
|
||||
flow from a pre-Bundle-1 deployment, see
|
||||
flow from a pre-RBAC (v2.0.x) deployment, see
|
||||
[`docs/migration/api-keys-to-rbac.md`](../migration/api-keys-to-rbac.md).
|
||||
|
||||
## Mental model
|
||||
@@ -69,7 +69,7 @@ giving them the keys to the kingdom. The
|
||||
forward.
|
||||
|
||||
The five **admin-only fine-grained perms** seeded by migration
|
||||
000030 (Phase 3.5 conversion) gate the high-blast-radius endpoints:
|
||||
000030 gate the high-blast-radius endpoints:
|
||||
|
||||
- `cert.bulk_revoke` - `POST /api/v1/certificates/bulk-revoke` and the EST sibling
|
||||
- `crl.admin` - `/api/v1/admin/crl/cache`
|
||||
@@ -141,14 +141,14 @@ even if no scoped grant exists. The reverse is also true - a
|
||||
scoped grant doesn't satisfy a request against a different scope.
|
||||
The Authorizer's `CheckPermission` is the single point of truth.
|
||||
|
||||
> **Note (Bundle 1 deferral):** the `scope_id` column is not
|
||||
> **Note (deferral):** the `scope_id` column is not
|
||||
> currently FK-constrained against the resource tables. An
|
||||
> operator can grant a permission at scope `profile`/`p-bogus`
|
||||
> without `p-bogus` existing; the gate still works (no rows match
|
||||
> at request time), but the API does not 404 the grant. Bundle 2
|
||||
> tracks the strict-FK closure. See
|
||||
> at request time), but the API does not 404 the grant. Strict-FK
|
||||
> closure is tracked for a follow-on release. See
|
||||
> `internal/repository/postgres/auth.go::AddPermission`'s
|
||||
> `TODO(bundle-2)` comment.
|
||||
> `TODO` comment.
|
||||
|
||||
## Granting + revoking access
|
||||
|
||||
@@ -194,7 +194,7 @@ certctl-cli auth keys scope-down --non-interactive ./scope-down.json
|
||||
|
||||
The mutating role-lifecycle commands (`certctl-cli auth roles
|
||||
create / update / delete` + `roles add-permission / remove-permission`)
|
||||
are tracked as Bundle 1 Phase 5.5 follow-up; today, manage custom
|
||||
are tracked as a follow-on; today, manage custom
|
||||
roles via the HTTP API or GUI.
|
||||
|
||||
### From the HTTP API
|
||||
@@ -258,7 +258,7 @@ distinguish wide cleanups from targeted demotions in the access log.
|
||||
|
||||
### From the MCP server
|
||||
|
||||
Bundle 1 Phase 11 ships 12 RBAC tools:
|
||||
The MCP server ships 12 RBAC tools:
|
||||
`certctl_auth_me`, `certctl_auth_list_roles`, `certctl_auth_get_role`,
|
||||
`certctl_auth_create_role`, `certctl_auth_update_role`,
|
||||
`certctl_auth_delete_role`, `certctl_auth_list_permissions`,
|
||||
@@ -296,7 +296,7 @@ To create an auditor key:
|
||||
|
||||
## Day-0 bootstrap (first-admin path)
|
||||
|
||||
Bundle 1 Phase 6 ships a one-shot bootstrap endpoint for fresh
|
||||
certctl ships a one-shot bootstrap endpoint for fresh
|
||||
deployments where no admin actor exists yet.
|
||||
|
||||
1. Set `CERTCTL_BOOTSTRAP_TOKEN=$(openssl rand -hex 32)` in the
|
||||
@@ -321,9 +321,10 @@ deployments where no admin actor exists yet.
|
||||
|
||||
The token is constant-time-compared. The server logs a startup
|
||||
warning if `CERTCTL_BOOTSTRAP_TOKEN` is set AND admin actors
|
||||
already exist (config-drift signal). For OIDC-first-admin (the
|
||||
"first user who signs in via SSO becomes admin" pattern), wait for
|
||||
Bundle 2.
|
||||
already exist (config-drift signal). For the OIDC-first-admin
|
||||
path (the "first user who signs in via SSO becomes admin"
|
||||
pattern), see
|
||||
[`docs/migration/oidc-enable.md`](../migration/oidc-enable.md).
|
||||
|
||||
## Demo mode (`CERTCTL_AUTH_TYPE=none`)
|
||||
|
||||
@@ -344,11 +345,11 @@ example folders only.
|
||||
- [Threat model](auth-threat-model.md) - what attacks this primitive
|
||||
defends against and which it does not
|
||||
- [Migration guide](../migration/api-keys-to-rbac.md) - moving
|
||||
pre-Bundle-1 deployments onto RBAC
|
||||
pre-RBAC (v2.0.x) deployments onto RBAC
|
||||
- [Profiles](../reference/profiles.md) - the `RequiresApproval=true`
|
||||
flow that Bundle 1 Phase 9 closure protects from flip-flop
|
||||
- [Approval workflow](approval-workflow.md) - the Rank 7 Infisical
|
||||
deep-research deliverable that the Phase 9 closure piggybacks on
|
||||
flow with the flip-flop-bypass closure
|
||||
- [Approval workflow](approval-workflow.md) - the two-person
|
||||
integrity primitive backing `RequiresApproval`
|
||||
- `internal/auth/` - the middleware + keystore + RequirePermission
|
||||
- `internal/service/auth/` - the service-layer Authorizer
|
||||
- `cowork/auth-bundle-1-prompt.md` - the design + phase plan
|
||||
|
||||
Reference in New Issue
Block a user