generated from coulomb/repo-seed
Add OpenBao introduction anchor for platform custody model
Document why OpenBao exists across HelixForge, NetKingdom, and Coulomb, how login fields and multi-tenant secret ownership map to paths and policies, and the phased rollout from platform bootstrap to tenant-scoped custody.
This commit is contained in:
275
docs/OpenBaoIntroduction.md
Normal file
275
docs/OpenBaoIntroduction.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 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
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
1. **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**.
|
||||
2. **Mount path ≠ repo, domain, or user group.** It is only *which configured
|
||||
login door* to use. `netkingdom` and legacy `keycape` are aliases to the
|
||||
same KeyCape-backed OIDC config today.
|
||||
3. **`platform-admin` ≠ namespace root.** Blank namespace means root namespace;
|
||||
`platform-admin` is an **operator policy** granting access to paths like
|
||||
`platform/*`.
|
||||
4. **There is no generic `user` login role yet.** Only `platform-admin` is wired
|
||||
for human OIDC. Narrower roles come with tenant onboarding.
|
||||
|
||||
### Streamlined operator experience (target)
|
||||
|
||||
```text
|
||||
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)
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```text
|
||||
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.
|
||||
|
||||
```text
|
||||
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.social` with KeyCape OIDC and `platform-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-admin` is intentionally broad for bootstrap; it must shrink as
|
||||
tenant paths appear.
|
||||
|
||||
### Direction (inception → production)
|
||||
|
||||
1. **Platform custody** — operator keys, shared infra, break-glass discipline.
|
||||
2. **Tenant paths** — `tenants/coulomb/*` for first internal tenant apps.
|
||||
3. **Workload auth** — per-namespace, per-service-account OpenBao roles.
|
||||
4. **Human role split** — readonly, tenant-admin, no default `platform-admin`
|
||||
for routine tenant work.
|
||||
5. **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` (see
|
||||
`helix-forge` agent instructions); ops-warden issues SSH certs only, not
|
||||
vault secrets.
|
||||
|
||||
---
|
||||
|
||||
## Phased rollout checklist
|
||||
|
||||
Use this as a maturity ladder, not a single big bang.
|
||||
|
||||
- [x] OpenBao deployed; audit enabled; root token retired or break-glass only
|
||||
- [x] Human operator path: KeyCape OIDC, MFA, browser UI
|
||||
- [x] Platform operator secrets under `platform/operators/`
|
||||
- [ ] Streamlined login mask (hide namespace, method, mount, role)
|
||||
- [ ] `platform-readonly` role for auditors
|
||||
- [ ] Path tree for `tenants/coulomb/`
|
||||
- [ ] Kubernetes auth roles for platform workloads
|
||||
- [ ] Tenant-scoped OIDC roles (no `platform-admin` for 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.
|
||||
Reference in New Issue
Block a user