# KeyCape service authentication for OpenBao

Date: 2026-08-23  
Status: accepted provider contract; live client provisioning remains a
deployment and custody operation

## Ownership boundary

KeyCape owns static confidential-client registration, client authentication,
JWT signing, IAM Profile service claims, expiry, and disabling future issuance.
The OpenBao platform owner owns JWT auth mounts, exact-bound roles, policies,
OpenBao token TTL/use limits, and value-safe authorization evidence. The
consumer owns renewal and fail-closed use. OpenBao or its approved delivery
path owns confidential-client secret custody.

KeyCape accepts the `codex-railiance-platform` issuance identity and the
`secrets-engine-openbao` service identity under this contract. It does not own
the resulting OpenBao identity token or policy. ops-warden remains the SSH
certificate issuer only, and user-engine is not in the machine-principal path.

## Exchange and claims

The consumer sends `POST /token` with `grant_type=client_credentials`, HTTP
Basic client authentication, and the allow-listed `scope=openbao:login`.
KeyCape returns an RS256 access token and no ID token or refresh token.

Every issued service token contains:

| Claim | Contract |
| --- | --- |
| `iss` | the configured KeyCape issuer |
| `sub` | the registration's exact `serviceSubject` |
| `aud` | the exact `clientId` |
| `iat`, `exp` | issue and expiry time; maximum per-client lifetime below |
| `principal_type` | `service` |
| `tenant` | the registration's exact tenant |
| `roles` | the registration's allow-listed roles |
| `groups` | an empty array |
| `scope` | only requested scopes from the registration allow-list |
| `assurance` | AAL1, `client_secret`, non-MFA, source `key-cape` |

OpenBao JWT roles must bind the exact issuer, audience, subject,
`principal_type`, tenant, and required role. A consumer must reject an issuer
or claim mismatch before attempting OpenBao login.

## Accepted registrations

The source-of-truth non-secret fragments are in
`config/service-clients.example.yaml`.

| Client | Subject | Role | Scope | Maximum JWT lifetime |
| --- | --- | --- | --- | --- |
| `codex-railiance-platform` | `service:codex:railiance-platform` | `coding-agent` | `openbao:login` | 15 minutes |
| `secrets-engine-openbao` | `service:secrets-engine` | `secrets-engine` | `openbao:login` | 15 minutes |

The confidential secret is referenced as an environment variable in KeyCape
configuration and must be materialized without entering Git, State Hub, chat,
process arguments, or normal logs. Registering or rotating the live value is a
separate approved custody action.

## Renewal, expiry, and revocation

- There is no refresh token. Obtain a new KeyCape JWT with a new
  `client_credentials` exchange when no more than three minutes remain.
- A consumer may retry a transient exchange failure with bounded backoff only
  while its current JWT is still valid. It must stop the privileged operation
  at expiry.
- KeyCape JWTs are self-contained and cannot be recalled after issue. Disabling
  the client or rotating its secret stops new issuance; the residual exposure
  is bounded by the 15-minute JWT lifetime and the OpenBao token's independent
  TTL/use limits.
- After OpenBao login, the consumer must explicitly revoke the OpenBao token in
  its cleanup path. A cleanup failure is actionable evidence and must not print
  a JWT, OpenBao token, client secret, or token accessor.

## Failure semantics

Authentication, scope, claim, signature, issuer, expiry, OpenBao login, and
cleanup failures are fail-closed. Steady-state consumers must not implicitly
fall back to bootstrap token files, an operator identity, a broader AppRole, or
an unbound JWT role. Bootstrap files remain explicitly selected setup or
break-glass providers and require their own authorization and evidence.

Verification must inspect metadata and capabilities without reading a secret
value. A coding-agent check must prove the `agent-high-risk-boundary` deny wins
against any otherwise readable workload policy.