Integration Guide

Integrating KeyRack into your production infrastructure.

1. Authentication (AuthN)

KeyRack does not bundle an identity provider. It integrates with your existing IdP.

JWT / OIDC

Works with any OIDC-compliant IdP (Keycloak, Auth0, Okta, Azure AD, Google Identity Platform):

authn:
  type: jwt
  jwks_url: https://idp.example.com/.well-known/jwks.json
  issuer: https://idp.example.com
  audience: keyrack-api

mTLS

Identity from client certificate — SPIFFE ID (preferred) or Subject CN.

Other methods

• bootstrap_token — dev and initial provisioning
• forwarded_identity — behind a trusted reverse proxy
• chain — combine multiple authenticators
• insecure — dev only

2. Authorization (AuthZ)

External Cedar Policy Decision Point (PDP) on every operation:

pdp:
  type: http
  endpoint: "http://localhost:8181/v1/authorize"
  timeout_ms: 5000

Fail-closed: if the PDP is unreachable, all operations are denied. The PDP never sees key material.

Use the bundled keyrack-cedar-pdp or any HTTP/gRPC-shaped PDP. See Cedar starter schema in the upstream repo.

3. Audit

Every operation emits a structured audit event:

audit:
  type: nats          # or: stdout, file
  url: "nats://localhost:4222"
  subject: "keyrack.audit"

sign_audit_events: true
audit_signing_key_path: "/var/lib/keyrack/audit-signing-key"

Events include Ed25519 signatures and BLAKE3 hash-chain linking.

4. Production checklist

• TLS on gRPC and REST endpoints
• PostgreSQL storage (not SQLite) for production
• External PDP with fail-closed behavior verified
• JWT or mTLS auth configured (not insecure or long-lived bootstrap tokens)
• Audit sink to durable storage (NATS or file with rotation)
• Audit signing key provisioned and backed up
• HSM provider configured (PKCS#11 or KMIP) for production crypto
• Cache TTL set appropriately for HYOK lockout requirements
• Prometheus scraping configured on /metrics
• Health probes on /healthz and /readyz

Full reference

The complete integration guide lives in the keyrack-oss repository.

See also: Operator guide · Security model · HYOK demo