certctl/docs/operator/auth-threat-model.md

# Authentication & authorization threat model

> Last reviewed: 2026-05-10

This document describes the attack surface around authentication and
authorization in certctl. It complements [`rbac.md`](rbac.md) and the
per-IdP runbooks at
[`oidc-runbooks/index.md`](oidc-runbooks/index.md) - those docs
explain how to USE the controls; this one explains what those controls
defend against and which threats they explicitly do NOT close.

certctl ships two authentication paths plus a break-glass admin
fallback: API keys with SHA-256 hashing + role-based authorization,
and OIDC SSO with HMAC-signed server-side sessions, CSRF rotation,
RFC OIDC Back-Channel Logout, an OIDC first-admin bootstrap, and a
default-OFF Argon2id break-glass admin path. Each surface brings its
own threat catalogue + mitigations, documented below.

## Threat actors

1. **External attacker with no credential** - probing the public
   HTTP surface. The default trust boundary for everything except
   the protocol-level endpoints (ACME / SCEP / EST / OCSP / CRL,
   which authenticate via embedded credentials per their own RFCs).
2. **Authenticated caller with the wrong role** - has a valid API
   key but the role doesn't grant the requested operation. The
   primary RBAC threat model.
3. **Compromised API key** - attacker holds a valid Bearer token
   that an honest operator originally provisioned. The key may
   carry any role.
4. **Insider operator** - legitimate access; potentially trying
   to escalate privilege or bypass the approval workflow.
5. **Compromised audit reviewer (auditor role)** - read-only
   access to audit events but otherwise untrusted.

The following actors are added by the federated-identity surface:

6. **OIDC-federated end user** - authenticates via the
   organization's IdP (Keycloak / Okta / Auth0 / Entra ID / Authentik
   / Workspace-via-broker). The user's credential lives at the IdP;
   certctl never sees it. Attack vectors center on token forgery,
   session hijacking, and group-claim manipulation.
7. **Stolen session cookie holder** - attacker holds a valid
   `certctl_session` cookie value (typically via XSS, network MITM,
   or a developer who pasted a token into a chat / pastebin). Holds
   the attacker-side ability to make requests as the legitimate user
   until the cookie expires (idle 1h / absolute 8h defaults) or is
   revoked.
8. **Compromised IdP** - the upstream IdP itself is rogue: signs
   tokens for arbitrary users, mints groups arbitrarily, etc. Largely
   out of certctl's control; mitigations are bounded to "the audit
   trail records the source provider on every login, blast radius is
   bounded by group_role_mapping configured for that provider."
9. **Break-glass-password holder** - operator with
   the local Argon2id password set up for SSO outages. Bypasses the
   OIDC + group-claim layer entirely. The default-OFF posture is the
   load-bearing mitigation; once enabled the password is the entire
   attack surface.

## API-key + RBAC defenses

### API-key authentication

- API keys live in `CERTCTL_API_KEYS_NAMED` (env-var) or
  `api_keys` (DB row, written by the day-0 admin bootstrap and
  the future role-management API). Keys hash via SHA-256; the
  middleware compares hashes via `crypto/subtle.ConstantTimeCompare`
  to defeat timing attacks.
- The auth middleware populates `ActorIDKey` / `ActorTypeKey` /
  `TenantIDKey` on every authenticated request context. Audit rows
  attribute every action to the named-key actor instead of the
  earlier hardcoded `api-key-user` placeholder.
- Demo mode (`CERTCTL_AUTH_TYPE=none`) injects the synthetic
  `actor-demo-anon` actor with admin grants. Production deploys
  MUST NOT use demo mode.

### Authorization (RBAC)

- Every gated handler routes through `auth.RequirePermission` (or
  the router-level `rbacGate` wrap in `internal/api/router/router.go`).
  The middleware
  resolves the actor's effective permissions via the
  `Authorizer.CheckPermission` service-layer call; on miss, the
  handler returns HTTP 403 BEFORE the body runs. This is the
  load-bearing gate.
- The five admin-only fine-grained perms (`cert.bulk_revoke` /
  `crl.admin` / `scep.admin` / `est.admin` /
  `ca.hierarchy.manage`) are seeded into `r-admin` only. To
  delegate one, an operator creates a custom role with the
  specific perm and grants it to the right actor.
- The auditor split: `r-auditor` holds only `audit.read` +
  `audit.export`. Pinned by the
  `internal/domain/auth/auditor_test.go` invariants. A regulator
  with the auditor key cannot read certificates, profiles,
  issuers, or any mutating surface.
- The privilege-escalation guard: granting or revoking a role
  requires the caller to hold `auth.role.assign` (enforced in
  `internal/service/auth/actor_role_service.go`). A non-admin
  cannot self-grant admin.
- The reserved-actor guard: mutations against `actor-demo-anon`
  return HTTP 409 from the service layer
  (`ErrAuthReservedActor`). The synthetic actor is operator-
  inaccessible.

### Day-0 bootstrap

- `CERTCTL_BOOTSTRAP_TOKEN` is constant-time-compared by
  `EnvTokenStrategy.Validate`. The strategy is one-shot via
  `sync.Mutex`-guarded `consumed` bool; the second call returns
  `ErrDisabled` (HTTP 410), not `ErrInvalidToken` (HTTP 401), so
  a probing attacker cannot distinguish "wrong token, retry"
  from "already consumed".
- The strategy also re-probes admin existence on every Validate.
  If an admin actor lands during the gap between Available and
  Validate, the second caller still gets HTTP 410.
- The minted plaintext key is written to the response body once.
  It is NEVER logged. The token-leak hygiene test in
  `internal/api/handler/auth_bootstrap_test.go` redirects
  `slog.Default` to a buffer and grep-asserts that neither the
  bootstrap token nor the minted key appears in any log line,
  audit row, or HTTP header.
- The minted key is hashed before persistence. Lost key →
  rotate via the regular RBAC API; the plaintext is not
  recoverable from the DB.

### Approval workflow + flip-flop loophole closure

- `CertificateProfile.RequiresApproval=true` gates two surfaces:
  (a) issuance + renewal of every cert pointing at the profile,
  (b) edits to the profile itself. The flip-flop loophole closure
  closure prevents the flip-flop bypass where an admin disables
  approval, mutates, re-enables.
- Same-actor self-approve is rejected at the service layer with
  `ErrApproveBySameActor` for both `cert_issuance` and
  `profile_edit` kinds. Two-person integrity is the load-bearing
  invariant; pinned by tests in
  `internal/service/approval_test.go`.

### Audit trail

- Every mutating operation flows through `AuditService.RecordEvent`
  or `RecordEventWithCategory`. The audit-category extension added the
  `event_category` column with a `CHECK` constraint enforcing
  the closed enum (`cert_lifecycle` / `auth` / `config`); the
  category surfaces the auth-mutation slice to the auditor view.
- The WORM trigger from migration 000018
  (`audit_events_worm_trigger`) blocks `UPDATE` and `DELETE` at
  the database layer. Even an admin DB user cannot tamper with
  audit history without dropping the trigger.
- The audit redactor (`internal/service/audit_redact.go`)
  scrubs credentials + PII from the `details` JSONB before
  persistence; an `_redacted_keys` field surfaces what the
  redactor took out for compliance review.

### Protocol-endpoint allowlist

ACME / SCEP / EST / OCSP / CRL endpoints authenticate via
embedded credentials defined by their own RFCs (JWS-signed,
challenge passwords, mTLS, public-by-RFC). The auth middleware
explicitly bypasses these via `IsProtocolEndpoint`. The
`internal/api/router/phase12_protocol_allowlist_test.go` regression
test pins the invariant at three layers (middleware bypass, allowlist
constant, router-level no-rbacGate-wraps-protocol-paths).

## OIDC + sessions + break-glass defenses

### OIDC token validation

- **Algorithm allow-list, never `none`, never HMAC.** The service-
  layer pinning lives in `internal/auth/oidc/service.go::disallowedAlgs`
  + `isDisallowedAlg`. The per-token alg check at sig-verify time
  (`isDisallowedAlg`, line ~1177) is the load-bearing defense — every
  ID token whose JWS header carries an alg outside the allow-list
  (RS256 / RS512 / ES256 / ES384 / EdDSA) is rejected with
  `ErrAlgRejected`. coreos/go-oidc additionally enforces the allow-list
  per-token at verify time as defense-in-depth against an upstream
  library regression. The IdP-downgrade-attack secondary defense at
  provider creation / `RefreshKeys` (v2.1.0-relaxed semantics)
  intersects the IdP's advertised `id_token_signing_alg_values_supported`
  with the allow-list and rejects only when the intersection is EMPTY
  — i.e., the IdP advertises NO acceptable alg. Pre-v2.1.0 the check
  strict-denied on ANY HS*/`none` advertisement; that broke against
  Keycloak 26.x (which lists every alg it's capable of in its discovery
  doc, including HS*, even when the realm only signs with RS256). The
  relaxation is safe because the per-token alg pin already prevents
  a real algorithm-confusion attack — a forged HS256 token using the
  IdP's RS256 pubkey as HMAC secret is rejected at sig-verify regardless
  of what the discovery doc advertises. Operators worried about a
  compromised IdP rotating to weak algs without rotating its certctl
  provider config get defense-in-depth from `JWKSStatus` + the alert
  hooks in the GUI panel.
- **Exact `iss` match.** ID-token `iss` claim must equal the
  configured `OIDCProvider.IssuerURL` byte-for-byte (sentinel
  `ErrIssuerMismatch`). A token from a different IdP - even one
  with the same `aud` - cannot ride a misconfigured provider row.
- **`aud` + `azp` checks.** Service-layer re-verification of the
  audience claim (must include `client_id`) plus the `azp` claim
  for multi-aud tokens (per OIDC core §3.1.3.7 step 5; sentinels
  `ErrAudienceMismatch`, `ErrAZPRequired`, `ErrAZPMismatch`). An
  attacker with a token issued for a different client cannot replay
  it against certctl.
- **`at_hash` REQUIRED when access_token is present.** OIDC core
  treats `at_hash` as a "MAY"; certctl tightens to "MUST"
  (`ErrATHashRequired`). A substituted access token cannot ride
  alongside a clean ID token through the verifier.
- **Single-use state + nonce.** Both 32-byte random server-generated
  values, persisted in the pre-login row keyed by the cookie. The
  pre-login row is consumed via `DELETE...RETURNING` on lookup
  (atomic single-use). `subtle.ConstantTimeCompare` on both. State
  replay returns `ErrPreLoginNotFound`; nonce mismatch returns
  `ErrNonceMismatch`.
- **PKCE-S256 mandatory.** RFC 9700 §2.1.1 requires PKCE on auth-
  code; certctl hard-codes S256 via `oauth2.GenerateVerifier` +
  `oauth2.S256ChallengeOption`. The `plain` method is not just
  unsupported - the `ErrPKCEPlainRejected` sentinel exists so a
  future regression that surfaces a plain path trips a test.
- **`iat` window.** Configurable per-provider (default 300s, capped
  at 600s by the domain validator). Defends against clock-skew
  attacks where an attacker submits a stale-but-valid token.
- **JWKS rotation handled transparently** by coreos/go-oidc's built-
  in cache, plus the operator-triggered `Service.RefreshKeys` for
  forced refresh (and the auto-refresh on JWKS-cache TTL expiry,
  default 3600s).
- **JWKS-fetch failure during a key rotation: fail closed.** The
  service maps go-oidc's network errors to `ErrJWKSUnreachable`
  (HTTP 503 to the in-flight login). Existing sessions are
  untouched. No exponential backoff, no auto-retry; the operator
  triages.
- **Encrypted `client_secret` at rest.** AES-256-GCM via
  `internal/crypto.EncryptIfKeySet` (the same v3-blob path issuer
  + target credentials use). The `client_secret_encrypted` column
  is `json:"-"` on the domain type so a misconfigured handler
  cannot wire-leak.

### Session minting + cookies

- **Length-prefixed HMAC.** Cookie wire format is
  `v1.<session_id>.<signing_key_id>.<base64url-no-pad(HMAC-SHA256)>`.
  HMAC input is **length-prefixed** as `len(sid):sid:len(kid):kid`
  - NOT bare-concat. The bare-concat form admits a collision
  attack: `<a, bc>` and `<ab, c>` produce identical HMAC inputs,
  letting a forger swap one byte across the boundary. Pinned by
  `TestComputeHMAC_LengthPrefixDefeatsConcatCollision` +
  `TestService_Validate_ConcatenationCollisionDefeatedByLengthPrefix`.
  The `v1.` version prefix is reserved; unknown prefixes are
  rejected with no fallback.
- **Cookie hardening.** `HttpOnly=true` (no JS access; defends XSS
  cookie theft), `Secure=true` (HTTPS-only; defends network MITM
  given HTTPS-Everywhere v2.2 milestone), `SameSite=Lax` default
  (configurable to Strict via `CERTCTL_SESSION_SAMESITE`), `Path=/`,
  no domain attribute (host-only).
- **Idle + absolute timeouts.** 1h idle / 8h absolute defaults
  (configurable via `CERTCTL_SESSION_IDLE_TIMEOUT` /
  `_ABSOLUTE_TIMEOUT`). The session row tracks `last_seen_at`,
  `idle_expires_at`, `absolute_expires_at` independently; the
  scheduler's `sessionGCLoop` (default 1h) sweeps expired rows.
- **CSRF defense.** Plaintext CSRF token in the JS-readable
  `certctl_csrf` cookie (intentionally `HttpOnly=false` so the GUI
  reads it for the `X-CSRF-Token` header). SHA-256 hash on the
  session row. `CSRFMiddleware` on state-changing methods uses
  `subtle.ConstantTimeCompare` against the hash. API-key actors
  (no session row) are CSRF-exempt - pinned by the bundle-1-compat
  CI guard.
- **Optional defense-in-depth IP / UA bind** (default OFF;
  `CERTCTL_SESSION_BIND_IP` / `_BIND_USER_AGENT`). Mismatch
  returns `ErrSessionIPMismatch` / `ErrSessionUAMismatch`. Use
  with care - mobile clients on changing networks fail closed.
- **Signing-key rotation primitive.** `RotateSigningKey` mints a
  new HMAC key; the old key stays valid for the configured
  retention window (default 24h via
  `CERTCTL_SESSION_SIGNING_KEY_RETENTION`) so existing cookies
  validate during the rollover. Past retention, the old key's row
  is dropped and any cookie still signed under it returns
  `ErrSigningKeyNotFound`.
- **EnsureInitialSigningKey is fail-fatal at server boot.** Wired
  in `cmd/server/main.go` via `logger.Error + os.Exit(1)` so a
  server with a broken DB or RNG cannot boot into a state where
  session validation is impossible.
- **Pre-login cookie discriminated from post-login.** Pre-login
  carries the `pl-` id prefix; post-login carries `ses-`. Defense-
  in-depth: `Validate` rejects pre-login cookies (pinned by
  `TestService_Validate_RejectsPreLoginCookieAtPostLoginGate`) so a
  stolen pre-login cookie cannot be replayed against the post-login
  gate.

### Back-channel logout

- **OpenID Connect Back-Channel Logout 1.0** (NOT RFC 8414).
  Endpoint: `POST /auth/oidc/back-channel-logout`. The IdP signs a
  logout JWT and POSTs it to certctl when a user logs out at the
  IdP. The handler validates the JWT against the IdP's JWKS via
  the same alg allow-list as the login flow.
- **Required claims pinned.** `iss` / `aud` / `iat` / `jti` /
  `events` (with the spec-mandated logout event type); exactly
  one of `sub` / `sid`; `nonce` MUST be absent (per spec §2.4
  - logout tokens MUST NOT carry a nonce). All four pinned by
  the back-channel-logout negative-test matrix.
- **`jti`-based replay defense.** The handler
  tracks recently-seen `jti` values to defeat logout-token replay
  attacks where an attacker captures a logout JWT and replays it.
- **Cache-Control: no-store** on the response per spec §2.5.

### OIDC first-admin bootstrap

- **Coexists with the env-var-token bootstrap path.** Both can be
  configured; the admin-existence probe ensures only one wins.
- **Group-scoped.** `CERTCTL_BOOTSTRAP_ADMIN_GROUPS` is a comma-
  separated allowlist of IdP group names; users in any one of those
  groups become admins on FIRST login per tenant. Non-empty
  intersection with the user's resolved groups is required.
- **One-shot per tenant via admin-existence probe.** Once any actor
  holds `r-admin` in the tenant, the bootstrap hook silently falls
  through to normal mapping (no admin grant). Operators rely on
  this to avoid an "always-admin-on-login" backdoor.
- **Explicit OIDC provider gate.** `CERTCTL_BOOTSTRAP_OIDC_PROVIDER_ID`
  pins which provider's tokens are eligible. A multi-IdP deploy
  cannot have any provider's group claims become admin.
- **Audit row on every grant.** `bootstrap.oidc_first_admin` event
  with `event_category=auth` + INFO log; the auditor monitors.

### Break-glass admin

- **Default-OFF.** `CERTCTL_BREAKGLASS_ENABLED=false` is the default;
  the entire surface (4 endpoints) is disabled. Operators flip it
  on during SSO incidents and back off after recovery.
- **Surface invisibility via 404-not-403.** Every endpoint returns
  HTTP 404 when disabled - public login AND admin endpoints. A
  scanner cannot distinguish "endpoint disabled" from "endpoint
  doesn't exist." All five service-layer methods short-circuit with
  `ErrDisabled` before any DB lookup; the handler maps to
  `http.NotFound`.
- **Argon2id with OWASP 2024 params.** `m=64MiB`, `t=3`, `p=4`,
  16-byte salt, 32-byte output, per-password random salt, PHC-format
  hash. The hash column is `json:"-"` so handlers cannot wire-leak.
- **Lockout state machine.** `CERTCTL_BREAKGLASS_LOCKOUT_THRESHOLD`
  (default 5) failures within
  `CERTCTL_BREAKGLASS_LOCKOUT_RESET_INTERVAL` (default 1h) trip a
  `CERTCTL_BREAKGLASS_LOCKOUT_DURATION` lock (default 30s; bumped
  from 100ms after the test discovered Argon2id verify itself takes
  ~80-200ms each, making a millisecond-scale lockout invisible).
  Atomic single-statement `IncrementFailure` defeats concurrent
  racing attempts. Idempotent `ResetFailureCount`.
- **Constant-time across all failure paths.** `verifyDummy()` runs a
  real Argon2id pass against an all-zeros throwaway salt on the
  no-credential and locked-account paths so all three failure modes
  (wrong password / locked / no actor) take statistically
  indistinguishable time. Pinned by
  `TestPhase7_5_ConstantTimeAcrossWrongPasswordAndNoCredentialPaths`
  (asserts within 5x ratio on durations).
- **Audit row + WARN log at boot.** `auth.breakglass_login_*`
  events with `event_category=auth`. `cmd/server/main.go` emits a
  WARN-level log when `ENABLED=true` so the operator's log review
  notices an over-long enablement.
- **Rate limit on the public login endpoint.** 5 attempts/minute
  via the existing `middleware.NewRateLimiter`.

## OIDC + sessions threat catalogue

The following sub-sections enumerate the threat surface introduced by
the OIDC + sessions surface and the mitigations the platform ships. They are deliberately
exhaustive - if a threat is listed here it has a concrete mitigation
or a documented "operator-driven, out of scope" framing. New threats
discovered post-2026-05-10 should be added here with a dated commit
note.

### OIDC token forgery vectors and mitigations

| Vector | Mitigation |
|---|---|
| Alg confusion (HS256 token signed with the IdP's public key) | Alg allow-list rejects HS256 / HS384 / HS512 / `none`. Service-layer + go-oidc enforce in two layers. IdP-downgrade-attack defense at provider-creation time. |
| Audience injection (token issued for a different client) | Service-layer `aud` re-check post-go-oidc verify; multi-aud tokens require matching `azp`. Sentinels `ErrAudienceMismatch` / `ErrAZPRequired` / `ErrAZPMismatch`. |
| Issuer mismatch (token from a different IdP with the same alg + key shape) | Exact `iss` string match (`ErrIssuerMismatch`). The 21-case OIDC negative-test matrix pins the byte-for-byte requirement. |
| Nonce replay (capturing a fresh token + replaying with the same nonce) | Single-use nonce stored in the pre-login row; `LookupAndConsume` is `DELETE...RETURNING` (atomic). Second use returns `ErrPreLoginNotFound`. |
| State replay (CSRF on the IdP redirect) | Same single-use mechanism as nonce. State is `subtle.ConstantTimeCompare`d. |
| `at_hash` substitution (clean ID token with a swapped access token) | `at_hash` REQUIRED when access_token present (certctl tightens OIDC core's MAY → MUST). `ErrATHashRequired` if missing; `ErrATHashMismatch` if non-matching. |
| `iat` window manipulation (stale token replay) | `iat_window_seconds` configurable per-provider (default 300, cap 600). Future `iat` returns `ErrIATInFuture`; older-than-window returns `ErrIATTooOld`. |
| JWKS rotation mid-login | coreos/go-oidc's built-in cache + auto-refresh on TTL expiry. Operator-triggered `Service.RefreshKeys` for forced refresh. |
| JWKS-fetch failure during a key rotation | `ErrJWKSUnreachable` (HTTP 503 to in-flight login). Existing sessions untouched. Operator clicks "Refresh discovery cache" once IdP recovers. No exponential backoff. |

### Session hijacking vectors and mitigations

| Vector | Mitigation |
|---|---|
| Cookie theft via XSS | `HttpOnly` on the session cookie; CSP headers from the security-hardening middleware prevent inline-script execution. |
| Cookie theft via network MITM | `Secure` flag + TLS 1.3-only control plane (HTTPS-Everywhere v2.2 milestone). |
| CSRF on state-changing methods | `SameSite=Lax` default + double-submit-cookie pattern with hashed CSRF token on the session row. CSRFMiddleware fires on POST/PUT/PATCH/DELETE for session-authenticated callers; API-key actors are exempt. |
| Session-cookie forgery via concatenation collision | Length-prefixed HMAC input (`len(sid):sid:len(kid):kid`). Pinned by two tests + a doc-block at the top of `service.go`. |
| Stolen-cookie replay (attacker uses a valid cookie until expiry) | Short idle timeout (1h default) + admin-revoke-all-for-actor + back-channel logout from IdP + GUI session revocation. |
| Cross-tab session interference | Cookie value is opaque + length-prefixed; tabs sharing the cookie share the session row. Sign-out in one tab calls `POST /auth/logout`; the next request from any tab gets a missing-row 401. |
| Session-row race on sign-out vs in-flight request | `Validate` is the single point that reads the row; missing row = 401. There is no "stale read" path because every request re-validates. |

### IdP compromise scenarios

A rogue IdP issues malicious tokens (signs tokens for arbitrary users,
mints arbitrary groups, etc.). Mitigations are largely out of certctl's
control - the trust root is the IdP. Documented behaviors:

- **Operator should monitor IdP audit logs.** Federated identity is
  only as trustworthy as the IdP it federates from. The `iss` claim
  on every certctl audit row points at the source IdP so the
  operator can correlate against IdP-side audit.
- **Operator can rotate group-role mappings from the GUI without
  redeploying.** If the IdP is compromised but not yet
  decommissioned, the operator can dial down access via
  `Auth → OIDC Providers → <provider> → Group → role mappings`
  and remove every mapping. Subsequent logins fail closed
  (`ErrGroupsUnmapped`); existing sessions continue until expiry.
- **The audit trail records every OIDC login including the source
  provider.** Blast radius is bounded by the `group_role_mapping`
  table for that provider. A compromised provider configured with
  only `engineers → r-operator` cannot escalate to `r-admin` via
  any token forgery.
- **The provider-delete path returns 409 when sessions exist for it.**
  `ErrOIDCProviderInUse` forces the operator to revoke the
  provider's active sessions before deletion - prevents accidental
  loss of audit lineage on a hot incident.

### Back-channel logout failure modes

| Mode | Behavior | Mitigation |
|---|---|---|
| IdP unreachable | certctl never receives the logout signal; sessions persist until idle/absolute timeout (1h/8h defaults). | Operator keeps absolute timeout short relative to risk tolerance. Manual revoke via GUI is always available. |
| Logout token signature invalid | certctl returns 400; no session revoked; `auth.oidc_back_channel_logout_failed` audit row. | Operator-monitored audit row surfaces forged-logout-token attempts. |
| Logout token replay (attacker captures + replays a valid logout JWT) | `jti`-based deduplication rejects the replay; first delivery succeeds, second returns 400. | Pinned by back-channel-logout negative tests. |
| Logout token alg confusion | Same alg allow-list as the login flow; HS-family rejected. | The OIDC alg allow-list applies to BCL too (same `Provider.RemoteKeySet`). |
| Missing `events` claim | Spec §2.4 requires the OIDC-defined logout event type; missing returns 400. | Pinned by negative test. |
| `nonce` claim present | Spec §2.4 requires `nonce` MUST NOT appear in logout tokens; presence returns 400. | Pinned by negative test. |

### Group-claim manipulation

Per-IdP group-claim shapes are documented in
[`oidc-runbooks/index.md`](oidc-runbooks/index.md). Manipulation
threats:

| Vector | Mitigation |
|---|---|
| Operator misconfigures mapping (e.g. `engineers → r-admin` instead of `r-operator`) | `auth.group_mapping_added` / `_removed` audit row with `event_category=auth`. The auditor role monitors. |
| Operator misconfigures `groups_claim_path` (e.g. `groups` when Auth0 emits `https://your-namespace/groups`) | User's group claim is ignored, user lands at "no roles assigned" screen. The GUI's OIDC provider detail page surfaces the configured path so the operator can verify. |
| IdP renames a group (e.g. `engineers → eng-team`) | Mappings silently break; users get fewer roles than expected. `auth.oidc_login_unmapped_groups` audit row fires on every such login; auditor monitors for unexpected spikes. |
| IdP user maintainer adds a user to an unintended group | Group is mapped to a higher-privilege role than intended; user gets the role on next login. Bounded blast radius: the group→role mapping is what they got, not arbitrary admin. Defense-in-depth: review mappings periodically; the auditor role can pull `auth.oidc_login_succeeded` rows by `details.subject` to spot drift. |

### Bootstrap phase risks

This section extends the day-0 bootstrap section with the OIDC
first-admin path.

| Vector | Mitigation |
|---|---|
| `CERTCTL_BOOTSTRAP_TOKEN` (env-var fallback path) leaks | One-shot via `consumed` bool + admin-existence probe. Both arms close the path the moment any admin lands. |
| `CERTCTL_BOOTSTRAP_ADMIN_GROUPS` misconfigured to a wide group (e.g. `everyone`) | Unintended user becomes admin on first OIDC login. Mitigation: scope-down via `certctl-cli auth keys scope-down --suggest`. Operators configure narrow groups. The audit row on `bootstrap.oidc_first_admin` surfaces every grant. |
| Both bootstrap strategies enabled simultaneously | Whichever fires first wins; the second sees admin-already-exists and falls through to normal mapping. No double-admin landing. |
| `CERTCTL_BOOTSTRAP_OIDC_PROVIDER_ID` left unset with multi-IdP deploy | Hook fires on ANY provider's tokens. Mitigation: explicit gate documented in `cmd/server/main.go` startup logging; operator audit reviewed pre-tag. |

### Break-glass risks

| Vector | Mitigation |
|---|---|
| Phished password (operator gives password to attacker) | Bypasses OIDC + every group-claim gate. Mitigation: default-OFF posture; lockout after 5 failures; WebAuthn pairing (v3 / Decision 12) closes the gap properly. |
| Brute-force online | Lockout state machine + 5/min rate limit on `/auth/breakglass/login`. |
| Brute-force offline (DB compromise) | Argon2id with OWASP 2024 params (~80-200ms per verify). Cracking remains expensive even with GPU. |
| Operator forgets to disable post-incident | Break-glass becomes a permanent backdoor. Mitigation: WARN log at boot when ENABLED=true; audit row on every break-glass login; runbook prescribes "disable within 24h of SSO recovery." |
| Side-channel timing on no-credential vs wrong-password vs locked | All three paths take statistically indistinguishable time via `verifyDummy()`. Pinned by the timing-statistical test. |
| Surface fingerprinting (scanner identifies break-glass exists) | All four endpoints return 404 (NOT 403) when disabled. Surface-invisibility - identical to a non-existent route. |
| Reserved-actor `actor-demo-anon` mutation via break-glass admin | Service layer rejects with `ErrAuthReservedActor` (HTTP 409). Same gate as the RBAC path. |

### Token-leak hygiene (the explicit grep policy)

ID tokens, access tokens, refresh tokens, authorization codes, PKCE
verifiers, state, nonce, signing keys, break-glass passwords MUST
NEVER appear in any log line at any level.

The invariant is enforced by per-package `logging_test.go` files that
redirect `slog.Default` to a buffer, run the service paths, and
grep-assert the secret values are absent from every captured line.
The pattern is `internal/auth/bootstrap/service_test.go`; the OIDC,
session, and break-glass packages follow the same shape:

- `internal/auth/oidc/logging_test.go` - token / code / verifier /
  state / nonce / cookie / client_secret / alg name absent from
  HandleAuthRequest, HandleCallback, alg-rejection, and provider-
  load paths.
- `internal/auth/session/service_test.go` - signing-key bytes absent
  from cookie-mint + validate paths.
- `internal/auth/breakglass/service_test.go` - plaintext password +
  Argon2id hash absent from every audit row + log line +
  HTTP-response shape (json:"-" probe via `json.Marshal`).

The `details` JSONB column on `audit_events` runs through the
audit redactor (`internal/service/audit_redact.go`) before
persistence; the redactor's allow-list is conservative enough that
adding a new token-shaped field to a new audit row defaults to
redacted, not leaked.

## Closed federated-identity threats

Each item below was an open threat under the earlier API-key-only
deployment posture. Status reflects current closure as of v2.1.0.

1. **OIDC federation** - ✅ closed. SAML and WebAuthn remain on the
   future-work list (Decision 12 — WebAuthn pairs with break-glass
   for hardware-token MFA). The break-glass path is a partial
   mitigation for the no-MFA case during SSO incidents.
2. **Session management** - ✅ closed. HMAC-signed
   `__Host-certctl_session` cookie with length-prefixed wire format,
   1h idle / 8h absolute expiry, scheduler-driven GC, server-side
   revocation list (delete the row), GUI's "Sessions" page surfaces
   own + all-actor revocation, back-channel logout from the IdP.
3. **Local password accounts (break-glass)** - ✅ closed. Argon2id
   + lockout + default-OFF + 404-not-403 surface invisibility. NOT
   for general human auth - only the "SSO is broken, need admin
   access right now" path. WebAuthn pairing on the future-work list.
4. **OIDC first-admin bootstrap** - ✅ closed.
   `CERTCTL_BOOTSTRAP_ADMIN_GROUPS` +
   `CERTCTL_BOOTSTRAP_OIDC_PROVIDER_ID` env vars + group-scoped +
   admin-existence-probe.
5. **Rate limiting on the bootstrap endpoint** - acceptable
   (one-shot by construction; per-IP rate limiting on the broader
   API is in place via `middleware.NewRateLimiter`). The break-glass
   `/auth/breakglass/login` endpoint carries the same rate-limit
   primitive at 5/min.

## Future-work threats

The following are not yet closed:

1. **WebAuthn / FIDO2 second factor** - operator console is OIDC
   (or break-glass password) only. No hardware-token requirement
   even on the admin path. Decision 12.
2. **Time-bound role grants / JIT elevation** - the
   `actor_roles.expires_at` column exists, no UI/API yet.
3. **SAML federation** - OIDC only. Operators on SAML-only IdPs use
   the broker pattern (run Keycloak as a SAML-to-OIDC bridge); see
   the Google Workspace runbook for the same broker shape.
4. **Multi-tenant data isolation activation** - the schema and
   repository layer carry tenant_id columns + a query-coverage CI
   guard, but tenant ACLs are not enforced. v2.1.0 ships
   single-tenant only (`t-default` seeded). The managed-service
   hosting work (operator decision item) is where multi-tenant
   flips on.
5. **HSM / FIPS-validated signing key for sessions** - the session
   signing key is software-only (HMAC-SHA256, in-memory key
   material, encrypted at rest via `internal/crypto`). Operators
   in FIPS 140-3 environments need to supply their own
   `Signer` implementation; the abstraction at
   `internal/crypto/signer/` accommodates this but no PKCS#11
   driver ships yet.
6. **OIDC RP-initiated logout** (the "/end_session_endpoint" flow
   where certctl signs a logout token + redirects the browser to
   the IdP). v2.1.0 implements ONLY the back-channel flow (IdP →
   certctl). Operators wanting the full bidirectional logout pair
   wait on a follow-on release.
7. **GUI E2E via Playwright** - tracked alongside #9 above.
8. **Per-IdP runbook external-tester sign-off** - encouraged via
   the operator-sign-off footers in `oidc-runbooks/*.md` but NOT a
   merge gate (operator decision 2026-05-10; the earlier
   "≥ 2 external testers" requirement was retired).

## Compliance mapping

The control set in this document supports the following
framework requirements. This is a mapping; it is not a claim of
formal certification.

- **SOC 2 CC6.1** (logical access controls) - RBAC primitive
  with role-based gating on every mutating endpoint.
- **SOC 2 CC6.3** (privileged access management) - `r-admin`
  role separation + role-grant audit trail with two-person
  integrity on approval-tier profile edits.
- **HIPAA §164.312(b)** (audit controls) - `event_category`
  column lets the auditor role review authentication / authorization
  changes specifically. WORM trigger keeps the audit table
  append-only at the database layer.
- **NIST SSDF PO.5.2** (separation of duties) - two-person
  integrity for compliance-tier issuance via the
  `RequiresApproval` flow + the approval-bypass closure on
  profile edits.
- **FedRAMP AU-9** (audit information protection) - WORM
  enforcement + auditor-only read access (the auditor role
  cannot mutate, the WORM trigger blocks UPDATE/DELETE).
- **PCI-DSS §10** (audit logging) - every mutating operation
  emits an audit row with actor + action + resource + timestamp +
  category. The audit table is append-only.

## Operator-facing checks

Run these periodically to verify the controls are working.

1. `certctl-cli auth keys list` - confirm no unexpected actor
   holds `r-admin`. Audit any new admin grants against the audit
   log.
2. `SELECT actor, action, COUNT(*) FROM audit_events WHERE
   action LIKE 'approval_%' AND timestamp > NOW() - INTERVAL '7
   days' GROUP BY actor, action;` - confirm approvals are
   happening and not concentrated in a single approver.
3. `SELECT COUNT(*) FROM audit_events WHERE actor =
   'system-bypass';` - MUST return 0 in production. A non-zero
   count means `CERTCTL_APPROVAL_BYPASS=true` was set; production
   deploys MUST leave it unset.
4. `SELECT actor, COUNT(*) FROM audit_events WHERE action =
   'bootstrap.consume';` - MUST return at most one row per
   tenant. Multiple rows means the bootstrap endpoint was called
   more than once, which the strategy's one-shot guard should
   have prevented; investigate.
5. `certctl-cli auth me` while authenticated as the auditor
   key - `effective_permissions` must contain `audit.read` +
   `audit.export` ONLY. Any other permission means a role grant
   widened the auditor's surface; revoke immediately.

The following checks were added with v2.1.0's federated-identity surface:

6. `SELECT COUNT(*) FROM oidc_providers;` - confirm only the
   expected providers are configured. An unexpected row is a
   compromise indicator. Cross-check with the
   `auth.oidc_provider_created` audit row to find when + by whom.
7. `SELECT actor_id, COUNT(*) FROM sessions WHERE NOT revoked AND
   absolute_expires_at > NOW() GROUP BY actor_id ORDER BY 2 DESC;`
   - confirm no actor has an unexpectedly large session count.
   Multi-session-per-actor is normal (laptop + phone), but a single
   actor with 50+ active sessions is a compromised-key signal.
8. `SELECT COUNT(*) FROM audit_events WHERE action LIKE
   'auth.oidc_login_unmapped_groups' AND timestamp > NOW() -
   INTERVAL '7 days';` - non-zero rows mean users are completing
   IdP authentication but failing the group-mapping step. Either
   the IdP renamed a group, or an unauthorized user attempted
   access. Investigate.
9. `SELECT COUNT(*) FROM audit_events WHERE action LIKE
   'auth.breakglass_%' AND timestamp > NOW() - INTERVAL '7 days';`
   - non-zero rows in steady state mean break-glass is being used
   outside an SSO incident OR was left enabled. Confirm
   `CERTCTL_BREAKGLASS_ENABLED` is `false` in non-incident windows.
10. `SELECT COUNT(*) FROM audit_events WHERE action =
    'bootstrap.oidc_first_admin';` - MUST return at most one row
    per tenant. Multiple rows means the OIDC bootstrap hook fired
    more than once per tenant, which the admin-existence probe
    should have prevented; investigate.
11. `SELECT COUNT(*) FROM session_signing_keys WHERE retired_at IS
    NOT NULL AND retired_at < NOW() - INTERVAL '7 days';` - retired
    keys past the retention window should have been GC'd. Non-zero
    rows mean the scheduler's `sessionGCLoop` is wedged.

## Cross-references

API-key + RBAC anchors:

- [`rbac.md`](rbac.md) - the operator how-to
- [`security.md`](security.md) - the wider security posture
- [`approval-workflow.md`](approval-workflow.md) - the two-person
  integrity gate
- [`docs/migration/api-keys-to-rbac.md`](../migration/api-keys-to-rbac.md) - 
  upgrade flow
- `internal/auth/` - middleware + keystore + RequirePermission +
  bootstrap
- `internal/service/auth/` - Authorizer + privilege-escalation
  guard + reserved-actor guard
- `migrations/000029_rbac.up.sql` - schema + seed
- `migrations/000030_rbac_admin_perms.up.sql` - five admin-only
  fine-grained perms
- `migrations/000032_audit_category.up.sql` - auditor surface
- `migrations/000033_approval_kinds.up.sql` - approval-bypass
  closure

OIDC + sessions + back-channel logout + break-glass anchors:

- [`oidc-runbooks/index.md`](oidc-runbooks/index.md) - per-IdP setup
  guides (Keycloak / Authentik / Okta / Auth0 / Entra ID / Google
  Workspace) with cross-IdP recurring concepts at the top
- `internal/auth/oidc/` - OIDC service (HandleAuthRequest /
  HandleCallback / RefreshKeys), hand-rolled groupclaim resolver,
  alg allow-list, IdP downgrade-attack defense
- `internal/auth/session/` - session service (length-prefixed HMAC,
  cookie minting, idle/absolute expiry, signing-key rotation, GC),
  CSRF middleware, chained-auth combinator
- `internal/auth/breakglass/` - default-OFF break-glass admin
  (Argon2id + lockout + constant-time + surface-invisibility)
- `internal/auth/oidc/testfixtures/` - Keycloak
  testcontainers harness (`//go:build integration`)
- `migrations/000034_oidc_providers.up.sql` - OIDC providers +
  group-role mappings tables
- `migrations/000035_sessions.up.sql` - sessions + session-signing-
  keys tables
- `migrations/000036_users.up.sql` - users (federated-human
  identity) table
- `migrations/000037_oidc_pre_login.up.sql` - pre-login table + 7
  new auth permissions
- `migrations/000038_breakglass_credentials.up.sql` - break-glass
  credentials table + 2 new permissions
- `scripts/ci-guards/N-bundle-2-security-empty-preserved.sh` -
  OpenAPI `security: []` count guard
- `scripts/ci-guards/bundle-1-compat-regression.sh` -
  API-key-only compat assertions (5 invariants)
- `scripts/ci-guards/bundle-1-to-2-upgrade-regression.sh` -
  OIDC-upgrade-path assertions (6 invariants)