Key Configuration

Auth Service uses keys for platform signing workflows and, in supported provider modes, Auth Service-issued tokens.

Key Uses

• DID signing for governance evidence and integrity workflows.
• Platform and service-account signing operations.
• Token signing for Keycloak and Microsoft Entra token-exchange deployments.

Auth0 and generic OIDC deployments rely on provider-issued user tokens and do not use Auth Service token exchange.

Supported Key Providers

Use Azure Key Vault, AWS KMS, or Google Cloud KMS for customer environments. Use the mock provider only for local development or test environments.

Auth migration 000015 must be applied before starting this Auth image with OpenBao. If migrations run separately, deploy the migration first: OpenBao startup requires the deployment guard table. Azure, AWS, GCP, and mock installations never use the guard tables; the migration is additive for them, and their startup, provider-switch, and coordinate-change behavior is unchanged. The OpenBao guard pins provider, algorithm, endpoint, Transit mount, and key prefix. Do not clear the guard to switch an initialized OpenBao deployment to another provider.

OpenBao Transit (development only)

OpenBao Transit is available as an explicitly enabled, fresh-install development profile with P-256/SHA-256. It requires KEY_MANAGEMENT_PROVIDER=openbao, DID_KEY_ALGORITHM=p256, an explicitly set ENVIRONMENT=development (the implicit default does not satisfy the gate), OPENBAO_DEVELOPMENT_ENABLED=true, and complete endpoint, dedicated mount, prefix, and token-file settings. See the Auth Service README’s development OpenBao profile for setup and recovery. This profile does not qualify customer migration, production use, or VC/PDF interoperability.

DID_KEY_CACHE_TTL_MINUTES does not apply to OpenBao, which reads fresh metadata for each operation.

OpenBao key deletion returns HTTP 501; keys are retained. Operators disable signing through policy denial or runtime-token revocation. Auth Service cannot destroy keys, rotate them, export private material, or administer the mount. Existing providers retain their existing deletion semantics. Provider and public-key associations persist in Auth Service’s database and reject silent replacement identities after configuration or custody changes.

Rotation Guidance

Plan key rotation during a maintenance window. Confirm downstream services can validate newly signed material before retiring old keys. Keep audit records for key changes and never publish private key material in release documentation.

Troubleshooting

If signing or token exchange fails, confirm the key provider is reachable, the configured key exists, and Auth Service has permission to use it.

OpenBao signing health is available at the API-secret-protected /health/signing endpoint. It checks seal state, runtime path permissions, platform public metadata, and the committed association without signing. Grant the runtime policy update on sys/capabilities-self before enabling this check. Liveness and database readiness stay independent of custody outages. The response includes fixed-outcome Transit signing counters and latency buckets; structured request events also include metadata-resolution failures. See the Auth Service README for health states, measurement boundaries, policy setup, and recovery. This endpoint adds no production enablement.