tegwick
329e48f64a
All checks were successful
Build and Publish Container Image / build-and-push (push) Successful in 46s
KEY-WP-0013-T05's tenant blocker did not need the decision it was waiting on. The two proposed resolutions differ in where a human's tenant comes from -- the directory record, or the client registration -- and an implementation exists that is correct under either, so the choice can be made later without another migration. A client registration may now declare a tenant. humanTenant() resolves it by four rules: no declaration keeps the directory answer unchanged; a declared zone applies where the directory has placed the user nowhere; agreement passes; and a declared zone conflicting with a directory assignment refuses issuance rather than relabelling the user. The refusal is the design, not an edge case. A registration can bind a zone for unplaced users and can never move a placed one, so this gets the approval chain its tenant:platform without writing a general cross-tenant override into the issuer. It fails closed rather than picking a winner, because either answer would be a silent cross-tenant assertion, and it reports 403 with error_type: tenant_binding so an operator can tell a misconfigured registration from a rejected login. If the owners later populate directory tenants, the same code stops supplying the zone and starts enforcing agreement with it. Safe only because client registrations are static and deployment-owned. The tenant contract records that this rule must be revisited if dynamic client registration is ever admitted. Tests cover all four rules; neutering the conflict check fails the relabel test rather than passing silently. T05 now waits on one thing only: the client_id and callback URI from informed-decision once it has a deployed origin. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016uV8zoCKpA1WRAxsKRYbdH Assistant: claude-code Assistant-Model: opus Assistant-Process: 1182213@bnt-lap001 Assistant-Session: 966597b9-ae61-46a4-8b9e-1594ab3ec4ad
81 lines
5 KiB
Markdown
81 lines
5 KiB
Markdown
# Approval-engine token contract
|
|
|
|
Static client registrations may set `audience: approval-engine`. This selects
|
|
only the access-token audience; OIDC ID tokens retain `aud=clientId`. Omitting
|
|
`audience` preserves the existing client-ID access audience, including OpenBao
|
|
consumers. Request `audience` and `resource` parameters cannot override it.
|
|
Access tokens contain the granted `scope` string for both supported grant types.
|
|
|
|
`config/service-clients.example.yaml` provides the two requested confidential
|
|
clients: secrets-engine-approval gets read/consume, and approval-engine-operator
|
|
gets lifecycle/observation scopes without consume. Service tokens contain
|
|
`principal_type=service`, tenant, roles, scope, assurance, issuer, subject,
|
|
audience, issue time and expiry; the lifetime is 15 minutes. The issuer signs
|
|
with RS256 and publishes its public key through `/jwks`.
|
|
|
|
Human approvers need a separate authorization-code/PKCE registration with an
|
|
exact deployment-owned callback, `audience: approval-engine`,
|
|
`allowedScopes: [openid, approval:read, approval:approve]`, and
|
|
`mfaRequired: true`. Do not add consume or other approval grants to that client.
|
|
No callback is invented here. The ID token is for the login client; present the
|
|
access token to approval-engine.
|
|
|
|
That client must also declare `tenant: tenant:platform`. A human token's tenant
|
|
comes from the directory record, which assigns none today, so without the
|
|
declaration the token would carry `tenant:coulomb` and be refused here. See
|
|
[the tenant contract](tenant-claim-contract.md) for the four resolution rules and
|
|
for why a declared zone can never relabel a user the directory has placed.
|
|
|
|
`approval:read` is present because approval-engine showed the surface cannot
|
|
render a decision without it: `GET /v1/approvals/{id}` and `/claim` both require
|
|
it, so the earlier `[openid, approval:approve]` would have let an approver submit
|
|
an entry they were never able to display. Reading through the owning component's
|
|
own service identity would also work, but it weakens the one claim that surface
|
|
exists to make — evidence of what *this person* was shown — so the read is
|
|
granted to the human principal instead. `approval:consume` stays excluded: human
|
|
principals are refused consume in approval-engine's code regardless, and
|
|
consumption belongs to the PEP causing the side effect.
|
|
|
|
### The assurance object
|
|
|
|
KeyCape emits `assurance` on every human token, unscoped. approval-engine stores
|
|
it verbatim into the approval entry, where it is the only place `mfaRequired:
|
|
true` survives into the record, so its shape is a contract:
|
|
|
|
| Field | Type | Meaning |
|
|
| --- | --- | --- |
|
|
| `level` | string | `aal1` or `aal2`. `aal2` exactly when MFA was verified in this authorization. The closest thing to `acr`. |
|
|
| `methods` | string[] | `["pwd"]`, or `["pwd","otp"]` when MFA was verified. The closest thing to `amr`. |
|
|
| `mfa` | bool | Whether MFA was verified. Redundant with `level` by construction, and kept because a consumer asserting on one should not have to know the mapping. |
|
|
| `source` | string | Always `key-cape`. Names which issuer made the assertion. |
|
|
| `at` | number | Unix seconds at which the user **authenticated** — not when the token was minted. |
|
|
|
|
`at` is authentication time on purpose. A reused browser session can be hours
|
|
old, and a record saying MFA happened at mint time would overstate how recently
|
|
the person proved anything. Where an authorization rides an existing session, the
|
|
original login instant is carried through.
|
|
|
|
The level is derived from what happened in *this* authorization, never from
|
|
enrollment state: a user with MFA enrolled who was not challenged gets `aal1`.
|
|
A consumer that needs a maximum age should compare `at`, not assume freshness.
|
|
|
|
These fragments are not live registrations. The two service registrations require
|
|
custody-managed values for the named environment references and a reviewed
|
|
rollout of this version, including the upstream issuer precondition. Platform's
|
|
CCR-2026-0017/0018 use OpenBao field `CLIENT_SECRET`; their approval remains open.
|
|
The separate human registration needs its actual UI-owned callback. A bearer-only
|
|
approval resource server has no such callback; its absence does not prevent
|
|
service-client issuance or service startup, and service credentials cannot be
|
|
counted as human approval evidence. Never log the token or secret. Verify the resulting
|
|
access token against the deployed issuer's `/jwks`, checking issuer, audience,
|
|
expiry, subject, principal type, tenant, roles, scope and assurance. Verify that
|
|
operator consume and human consume requests are rejected. Local tests verify
|
|
signatures against the JWKS handler; they do not constitute live issuance proof.
|
|
|
|
Negative verification requires the token endpoint's typed refusal: HTTP 400,
|
|
`invalid_profile_usage`, feature `scope` for excess scope; HTTP 401 with feature
|
|
`Authorization` for a predecessor secret. A timeout, 5xx, malformed response,
|
|
invalid signature or JWKS failure is not proof of denial.
|
|
|
|
KeyCape owns issuance and client grants/disablement. OpenBao and the deployment
|
|
operator own credential custody; approval-engine enforces its resource policy.
|