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 the gRPC client certificate — SPIFFE ID (preferred) or Subject CN. Authentication defaults to mtls, but TLS remains opt-in: configure the tls: block with a server certificate, key, and client CA. The REST listener serves plain HTTP and cannot use the gRPC peer-certificate identity; terminate HTTPS at a reverse proxy, protect its connection to the service, and configure a REST-supported credential type such as JWT.

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

Mandatory: pdp: has no default. A config that omits it is a startup error rather than a silent allow, so authorization cannot be disabled by oversight — only by explicitly asking for always_allow, which is named in a warning at every startup.

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 BLAKE3 hash-chain linking for interior tamper-evidence, maintained whether or not signing is enabled. keyrack audit verify <log> checks the chain with no key and catches in-place edits, deletions, and reordering. Ed25519 signing is opt-in, requires a persistent signing key, and adds authorship — which a chain alone cannot give, since an attacker able to rewrite the whole log can recompute every link. Tail-truncation drops the newest events without breaking a chain link; signatures do not detect it either. Detecting it requires an external anchor, such as a signed checkpoint or independent witness. See the security model for both bounds.

4. Production checklist

• gRPC TLS configured; REST HTTPS terminated at a reverse proxy with its service connection protected
• 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