tegwick
0d6d76f230
Mark all tasks done after live deployment of the railiance-platform overlay gateway and update the phased checklist in OpenBaoIntroduction.md.
11 KiB
OpenBao in the HelixForge / NetKingdom / Coulomb Universe
This document anchors why OpenBao exists in the platform, what it is responsible for, and where we are headed. It is written for operators, architects, and builders working across HelixForge intent, NetKingdom security architecture, and Coulomb as the first reference tenant.
Operational runbooks and deployment detail live in adjacent repos. This file
is the conceptual home in helix-forge.
| Topic | Canonical detail |
|---|---|
| Deployment, Helm, break-glass | railiance-platform/docs/openbao.md |
| Platform vs tenant security model | net-kingdom/docs/platform-identity-security-architecture.md |
| KeyCape OIDC wiring | net-kingdom/sso-mfa/k8s/keycape/README.md |
| Credential routing for agents | helix-forge/AGENTS.md (Credential and access routing) |
Purpose
OpenBao is the platform secrets service: the place where sensitive material is stored, accessed under policy, audited, and delivered to trusted actors.
HelixForge describes how capabilities evolve. NetKingdom describes who may act and under what trust model. Coulomb is tenant zero — the first internal tenant on that platform. OpenBao sits in the custody plane:
- It holds API keys, database passwords, signing material, operator credentials, and workload secrets.
- It does not replace identity (KeyCape), application authorization (flex-auth), or general configuration in Git.
The goal is IT security from inception to production: secrets enter custody early, move through governed paths, and reach production workloads without living in Git, chat, State Hub, or ad hoc env files.
What OpenBao is — and is not
| OpenBao is | OpenBao is not |
|---|---|
| A centralized secret store with policy and audit | An identity provider |
| A broker for dynamic credentials (DB, PKI, SSH, …) | An application authorization engine |
| A delivery point for workloads (API, CSI, ESO) | A tenant registry or user directory |
| The system of record for secret values | A substitute for SOPS/age in Git-at-rest bootstrap |
Privacy of secrets is achieved through path layout, identity binding, and least-privilege policies — not merely by storing data inside OpenBao.
Place in the stack
Human / service / agent principal
|
v
NetKingdom IAM Profile (identity semantics)
|
+-- KeyCape (+ privacyIDEA MFA) --> humans, OIDC login
|
+-- flex-auth (+ Topaz) --> application authorization
|
v
OpenBao (custody) --> secret paths, policies, audit
|
v
Workloads (K8s pods, jobs, operators) --> consume secrets via scoped auth
- KeyCape answers: who is this principal, which groups/tenants apply?
- flex-auth answers: may this principal perform action A on resource R?
- OpenBao answers: may this principal read or write secret path P?
End users of tenant applications should normally not browse OpenBao. They authenticate to apps; apps (or operators) fetch secrets through scoped machine or operator identity.
Browser login — what the UI fields mean
Operators reach the UI at https://bao.coulomb.social. The raw OpenBao login
form exposes four fields. For platform operators today, most should be hidden
presets, not user choices.
| UI field | Technical meaning | User/admin mental model |
|---|---|---|
| Namespace | OpenBao-internal partition (multi-tenancy inside one cluster) | Leave blank = the single root vault we use today |
| Method | Auth backend type (OIDC, token, kubernetes, …) | OIDC = “Sign in with KeyCape” |
| Mount path | Which auth backend handles login (auth/<mount>/) |
netkingdom = platform identity plane login door |
| Role | OIDC auth role → maps claims to OpenBao policies | platform-admin = platform operator custody |
Common misconceptions
- Namespace ≠ tenant/vendor. Coulomb, customers, and HelixForge are not selected in the namespace box. Tenant scope is expressed in identity claims, KV paths, and policies.
- Mount path ≠ repo, domain, or user group. It is only which configured
login door to use.
netkingdomand legacykeycapeare aliases to the same KeyCape-backed OIDC config today. platform-admin≠ namespace root. Blank namespace means root namespace;platform-adminis an operator policy granting access to paths likeplatform/*.- There is no generic
userlogin role yet. Onlyplatform-adminis wired for human OIDC. Narrower roles come with tenant onboarding.
Streamlined operator experience (target)
Sign in with KeyCape
[ Sign in ]
Hidden presets: namespace blank, method OIDC, mount netkingdom, role
platform-admin. Retire keycape from the default mask once compatibility
notes are no longer needed.
Do not use the root token through the browser UI.
Multi-entity secret ownership
NetKingdom targets a platform that is multi-tenant, multi-vendor, multi-application, multi-customer, and multi-user. Many of those entities need secrets. Yes, OpenBao can hold them all — with explicit ownership rules.
OpenBao does not natively understand “tenant” or “vendor”. We encode ownership:
| Layer | Responsibility |
|---|---|
| Path convention | Every secret has an unambiguous owner prefix |
| Identity | KeyCape groups, K8s service accounts, scoped tokens |
| Policy | Least privilege: which paths each identity may touch |
| Delivery | ESO / CSI / API — only the intended workload receives the value |
| Audit | Who accessed which path (values are not logged) |
Target path taxonomy (evolving)
platform/ # platform control plane only
platform/operators/<service>/ # operator API keys, bootstrap creds
platform/workloads/<ns>/<sa>/<name> # platform workload secrets
tenants/coulomb/ # tenant zero (reference tenant)
tenants/coulomb/apps/<app>/ # application secrets
tenants/coulomb/vendors/<vendor>/ # vendor integration secrets
tenants/<customer>/ # future customer tenants
tenants/<customer>/apps/<app>/ # customer application secrets
Aligns with NetKingdom language:
tenant:platform # platform control plane
tenant:coulomb # first internal / reference tenant
tenant:customer:<name> # future customer tenants
tenant:sandbox:<name> # sandboxes
Actor → access (target matrix)
| Actor | Auth path | Typical secret scope |
|---|---|---|
| Platform operator | KeyCape OIDC → platform-admin |
platform/* (narrow over time) |
| Platform auditor | KeyCape OIDC → platform-readonly |
metadata, no secret reads |
| Tenant admin (future) | KeyCape OIDC → tenant-<id>-admin |
tenants/<id>/* only |
| Workload (pod) | Kubernetes auth → per-SA role | one path prefix, read-only where possible |
| Break-glass | offline/root procedures | emergency only, audited |
Tenant administrators must not be able to alter platform root trust, global identity config, or policies governing the platform itself.
Workloads
A workload is a running piece of software that does a job without a human at the keyboard: API server, worker, cron job, operator script running as a service account.
| Term | Meaning |
|---|---|
| User | Human (e.g. platform operator via KeyCape) |
| Application | Software product (Inter-Hub, a tenant app) |
| Workload | Running instance of that application in the cluster |
| Service account | The workload's machine identity in Kubernetes |
Humans use OIDC + MFA. Workloads use Kubernetes auth (or tightly scoped tokens) so secrets are delivered automatically and least-privilege.
Human operator → OIDC (KeyCape) → platform-admin → platform/operators/...
Inter-Hub pod → Kubernetes auth → inter-hub-role → platform/workloads/inter-hub/...
Tenant app pod → Kubernetes auth → tenant-app-role → tenants/coulomb/apps/myapp/...
Current state vs direction
Today (bootstrap / platform phase)
- Single OpenBao cluster on Railiance01, root namespace only.
- Browser UI at
bao.coulomb.socialwith KeyCape OIDC andplatform-admin. - Platform operator paths under
platform/(e.g. Inter-Hub and ops-hub operator keys). - Humans for attended custody; workloads largely still catching up on Kubernetes auth + ESO/CSI delivery.
platform-adminis intentionally broad for bootstrap; it must shrink as tenant paths appear.
Direction (inception → production)
- Platform custody — operator keys, shared infra, break-glass discipline.
- Tenant paths —
tenants/coulomb/*for first internal tenant apps. - Workload auth — per-namespace, per-service-account OpenBao roles.
- Human role split — readonly, tenant-admin, no default
platform-adminfor routine tenant work. - Customer tenants — isolated paths and policies; optional OpenBao namespaces later if compliance requires stronger partitions.
HelixForge capability work should treat secret path + policy + delivery as part of a capability's security contract, not an afterthought.
Rules of custody (non-negotiable)
- Secret values, root tokens, unseal shares, and display-once API keys never go into Git, State Hub, workplans, chat, or logs.
- Display-once material is stored at the approved OpenBao path immediately, then removed from temp files.
- Prefer metadata-only inspection in the UI when checking whether a secret exists.
- Route credential ownership questions through
warden route(seehelix-forgeagent instructions); ops-warden issues SSH certs only, not vault secrets.
Phased rollout checklist
Use this as a maturity ladder, not a single big bang.
- OpenBao deployed; audit enabled; root token retired or break-glass only
- Human operator path: KeyCape OIDC, MFA, browser UI
- Platform operator secrets under
platform/operators/ - Streamlined login mask (hide namespace, method, mount, role) —
HF-WP-0003, overlay inrailiance-platform/helm/openbao-ui-overlay/ platform-readonlyrole for auditors- Path tree for
tenants/coulomb/ - Kubernetes auth roles for platform workloads
- Tenant-scoped OIDC roles (no
platform-adminfor tenant admins) - External Secrets Operator / CSI delivery for app charts
- Per-tenant audit review practices
- Optional OpenBao namespaces for high-isolation customers
Summary
OpenBao is how the Coulomb / NetKingdom platform keeps secrets private to their owners at scale: one vault, many owners, enforced by naming, identity, and policy. HelixForge supplies the evolution loop; NetKingdom supplies the trust model; Coulomb proves the first tenant path. OpenBao is the custody layer that lets that model survive contact with production.
One line: Sign in with KeyCape for platform custody; encode tenant and application ownership in paths and policies; let workloads authenticate as themselves — so secrets stay out of Git and in governed hands from inception through production.