docs(handbook): setting up key custody — all three modes (#112 follow-up) #207

Merged

Cordy merged 3 commits from docs-openbao-custody into main

2026-08-13 01:50:05 +00:00

Cordy commented

2026-08-13 01:49:49 +00:00

Owner

Adds a customer-facing "Setting up key custody" section to docs/handbook/encryption.md, right after the conceptual custody-modes list and before the recovery-identity section. Written for someone self-deploying Cairn, covering the operational setup for all three modes:

keycloak-profile — the confidential service-account client (view-users + manage-users), why it's separate from the sign-in client, config fields, and the AD caveat.
openbao — enable KV v2, the least-privilege policy scoped to <mount>/{data,metadata}/<prefix>/*, minting a periodic token, config fields, lazy per-user/per-space paths, and OpenBao-must-be-unsealed as a hard dependency. Distilled from the #112 e2e that just landed.
deployment — single master identity, the no-per-user-isolation caveat, and the instanceSeed multi-instance note.

Product-neutral (generic <keycloak-host>, <openbao-host>, <mount> placeholders — no lab hostnames/IPs), per the handbook rules. Existing content untouched; the section was spliced in by a self-removed one-shot workflow. Docs only.

Adds a customer-facing **"Setting up key custody"** section to `docs/handbook/encryption.md`, right after the conceptual custody-modes list and before the recovery-identity section. Written for someone self-deploying Cairn, covering the operational setup for all three modes: - **keycloak-profile** — the confidential service-account client (view-users + manage-users), why it's separate from the sign-in client, config fields, and the AD caveat. - **openbao** — enable KV v2, the least-privilege policy scoped to `<mount>/{data,metadata}/<prefix>/*`, minting a periodic token, config fields, lazy per-user/per-space paths, and OpenBao-must-be-unsealed as a hard dependency. Distilled from the #112 e2e that just landed. - **deployment** — single master identity, the no-per-user-isolation caveat, and the `instanceSeed` multi-instance note. Product-neutral (generic `<keycloak-host>`, `<openbao-host>`, `<mount>` placeholders — no lab hostnames/IPs), per the handbook rules. Existing content untouched; the section was spliced in by a self-removed one-shot workflow. Docs only.

Cordy added 3 commits

2026-08-13 01:49:50 +00:00