--- title: "Key Configuration" description: "DID signing keys for users, service accounts, and platform workflows, and the providers that hold them." source: "Guardian Platform" --- Auth Service keeps DID signing keys for users, service accounts, and platform workflows in a key provider. Tokens it issues through token exchange are signed with a separate RSA key, not a provider key; see [Token Exchange and Refresh Tokens](./token-exchange.mdx#operational-requirements). ## Key Uses - DID signing for governance evidence and integrity workflows. - User, platform, and service-account signing operations. ## Supported Key Providers Use Azure Key Vault, AWS KMS, Google Cloud KMS, or OpenBao Transit 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 OpenBao Transit is supported for fresh installations with P-256/SHA-256. It requires `KEY_MANAGEMENT_PROVIDER=openbao`, `DID_KEY_ALGORITHM=p256`, and complete endpoint, dedicated mount, prefix, and authentication settings. The endpoint must use HTTPS, except for a literal loopback IP such as `127.0.0.1` (not `localhost`) when `ENVIRONMENT` is explicitly set to exactly `development`; the unset default does not count. See the Auth Service README's OpenBao Transit profile for setup and recovery. `POST /protected/sign-pdf` issues a P-256 certificate for this profile, because the certificate follows the platform key's curve. Migrating keys that already exist in a cloud KMS to OpenBao is a separate, unsupported operation. Auth Service authenticates to OpenBao with either a token file or Kubernetes workload identity. Kubernetes workload authentication is selected with `OPENBAO_AUTH_METHOD=kubernetes` and explicit auth mount, role, projected JWT file, and audience settings. An operator binds the role to the intended service account and namespace and configures a separate Kubernetes TokenReview reviewer. Active requests renew scoped credentials; projected-token replacement, idle expiry, or renewal failure triggers reauthentication. See the Auth Service README for the exact settings, administrative boundary, validation evidence, and recovery limits. `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. ## Operator Responsibilities - Configure the key provider before enabling signing workflows. - Restrict key-management access to approved platform operators. ## Rotation Guidance DID keys are identities: a `did:key` is derived from its public key, so rotating one changes the DID. Do not rotate DID keys; OpenBao deployments reject a rotated key that no longer matches its stored association. Rotate the token signing key according to the customer's security policy, during a maintenance window, with a new `AUTH_SERVICE_KEY_ID`. Auth Service publishes only the current key, so tokens signed with the old key stop validating at once, and clients must refresh or sign in again. Keep audit records for key changes and never publish private key material in release documentation. ## User Impact Most users do not manage DID keys directly. They see the result in signed governance evidence, credentials, and lineage workflows. If signing is unavailable, credential and integrity-related workflows may fail until key access is restored. ## Troubleshooting If signing fails, confirm the key provider is reachable, the configured key exists, and Auth Service has permission to use it. Token exchange does not depend on the key provider: a failure to create a user's DID key is logged and the exchange still succeeds. 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. ## Related - [Key Management](../deployment/key-management.mdx) — choosing a cloud key management provider - [Backup and Restore](../deployment/backup-and-restore.mdx#key-management) — protecting non-exportable signing keys from deletion - [Token Exchange and Refresh Tokens](./token-exchange.mdx) — the workflow that creates each user's DID key - [Integrity Service Operations](../integrity-service/operations.mdx) — why Integrity Service signing depends on these keys - [Auth Service Configuration](./configuration.mdx) — where the key-management provider is set