EQTY LabDocs

Key Configuration

DID signing keys for users, service accounts, and platform workflows, and the providers that hold them.

View as Markdown

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.

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.