theta42/theta-suite
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #124 from theta42/feature/openbao-secrets

Browse Source 
v1.28.0: OpenBao as the central secrets store for the stack
This commit is contained in:
William Mantly
2026-08-01 12:55:32 -04:00
committed by GitHub
parent 3277972037 f7df04c2f0
commit 09c3f3e02e
10 changed files with 596 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+144
View File
@@ -8,6 +8,150 @@ orchestration code; see each submodule's own `CHANGELOG.md`
[sso-manager-node](https://github.com/theta42/sso-manager-node/blob/master/CHANGELOG.md))
for what changed inside the apps it composes.
## [v1.28.0] - 2026-08-01
OpenBao becomes the central secrets store for the whole stack. Every app now
loads its secrets from OpenBao at boot via the new
[`@simpleworkjs/bao-conf`](https://simpleworkjs.github.io/bao-conf/) package;
end users get personal per-user secret storage through the SSO UI; external
apps get scoped `secret/apps/<app>/*` access. `setup.sh` mints the policies
and scoped tokens, `bootstrap.js` writes generated creds into OpenBao, and a
new `docs/secrets.md` documents the architecture.
### Changed (theta-env orchestration)
- **`setup.sh`** — after the KV-v2 enable, a new idempotent block writes four
OpenBao policies (`sso-broker`, `sso-admin`, `proxy`, `jump-host`) via
heredocs, a `sso-broker` token role (`allowed_policies_glob` `user-*`/`app-*`,
24h period), and mints scoped `SSO_VAULT_TOKEN` / `PROXY_VAULT_TOKEN` /
`JUMP_VAULT_TOKEN` (orphan, renewable, reused from `setup.env` if still
valid). `seed_app_conf` seeds `secret/{sso-manager,proxy,jump-host}/conf`
from the operator-edit `/config/*-secrets.js` files on first run. The
bootstrap exec now passes the root `VAULT_ADDR`/`VAULT_TOKEN` for seeding.
The root token stays in `setup.env` for maintenance only — it is never passed
to a service container. `bash -n` + `shellcheck` clean.
- **`docker-compose.yml`** — `sso-manager`/`proxy`/`jump-host` get
`VAULT_ADDR=http://openbao:8200` and `VAULT_TOKEN=${SSO|PROXY|JUMP}_VAULT_TOKEN:-`;
`proxy`/`jump-host` gain `depends_on: openbao: service_started`. compose
config valid.
- **`bootstrap/bootstrap.js`** — `baoPut()` writes the generated OAuth client
creds to `secret/proxy/conf` and `secret/jump-host/conf` (POST replaces; the
full file object), so OpenBao — not the on-disk `/config/*-secrets.js` — is
authoritative after first boot. Fail-soft. `node --check` clean.
- **`docs/secrets.md`** (new) — the full secrets architecture: load path,
policy/token table, the `sso-broker` role, seeding, end-user personal
secrets, external-app convention (curl + Node `bao-conf` examples), operator
rotation, backups. Linked from the README and the docs nav (`_config.yml`).
- **README** — Configuration section rewritten (OpenBao authoritative, link to
`docs/secrets.md`); Secrets-backup section adds the `openbao-data` volume.
### Submodule bumps
- `sso-manager-node` → **v1.16.0** (was v1.15.2-era).
- `proxy` → **v1.13.1** (was v1.12.1; passes through v1.13.0).
- `jump-host` → **v1.14.1** (was v1.11.0-era; passes through v1.14.0).
- `ldap-client` unchanged (v1.1.1).
#### sso-manager-node — [v1.16.0](https://github.com/theta42/sso-manager-node/releases/tag/v1.16.0)
OpenBao becomes the central secrets store for the theta42 stack, and the SSO
Manager becomes its broker. This is the SSO's half of the move: it loads its
own secrets from OpenBao, mints scoped tokens for users and external apps,
and exposes a fixed, role-scoped personal-secrets UI.
##### Changed
- **Secrets now load from OpenBao at boot** via
[@simpleworkjs/bao-conf](https://simpleworkjs.github.io/bao-conf/), which
deep-merges `secret/sso-manager/conf` over the file-loaded config
(replacing the old `utils/conf_manager.js`, which did a shallow-per-key
merge). `bin/www` runs `bao-conf.init()` after `models.initORM()` and
before `listen`. Fail-soft: if OpenBao is unreachable, boot continues from
`CONF_SECRETS`. The SSO authenticates with a scoped `VAULT_TOKEN` (policy
`sso-broker`), never the root token. The admin **Configuration** UI
(`/api/conf`) now writes through `bao-conf.set('sso-manager', …)`.
- **`/api/vault` proxy reworked** — the old endpoint was an ungated
pass-through that never injected an `X-Vault-Token` (so the UI was both
ungated *and* broken). It is now `middleware.auth` → `scopeGuard` → a
token-injecting proxy. `scopeGuard` resolves a per-user (`user-<uid>`) or
per-admin (`sso-admin`) token via the new `utils/vault_broker.js`
(Redis-cached, minted through the `sso-broker` token role) and enforces a
path prefix as a second layer on top of the OpenBao policy. The client
`auth-token` is stripped; only the server-minted token reaches OpenBao.
- **Vault UI reworked and renamed** (`views/vaultwarden.ejs` →
`views/vault.ejs`; the `/vault` route is now `middleware.auth`-gated).
Non-admin users see only their `secret/users/<uid>/` namespace; admins get
free-form path entry across `secret/` plus an **Apps** tab to mint scoped
tokens for external apps (`secret/apps/<name>/*`, shown once with copy +
`curl` convention).
- Bumped package version to track the release tag.
##### Removed
- `nodejs/utils/conf_manager.js` (replaced by `@simpleworkjs/bao-conf`).
- `nodejs/views/vaultwarden.ejs` (renamed `vault.ejs`).
##### Security
- **Committed-secrets remediation.** `config/sso-secrets.js` (LDAP bind
password, SMTP, `oauth.jwtSecret`) and `nodejs/test_plugins.js` (a
hardcoded Proxmox root API token and a UniFi password) were tracked on
master. They are now untracked + gitignored (`config/*-secrets.js`), and
`test_plugins.js` is deleted; `config/proxy-secrets.js.example` added as a
placeholder template. **The secrets remain in git history — rotation at
the providers is the real remediation and is the operator's to perform.**
OpenBao is now the authoritative store; the local files are seed artifacts
only.
> Note: sso releases v1.12.0–v1.15.2 were tagged from merge PRs without
> corresponding `CHANGELOG.md` entries or GitHub releases; v1.16.0 resumes
> the changelog.
#### proxy — [v1.13.1](https://github.com/theta42/proxy/releases/tag/v1.13.1) (via [v1.13.0](https://github.com/theta42/proxy/releases/tag/v1.13.0))
##### v1.13.1 — Fixed
- **Bumped `@simpleworkjs/bao-conf` to 1.0.1** so standalone/no-OpenBao boots
don't crash. bao-conf 1.0.0's `init()` threw when `VAULT_TOKEN` was unset,
which — combined with `bin/www`'s `.catch(() => process.exit(1))` — made the
proxy exit at boot in any deployment without an OpenBao sidecar (standalone
Docker, bare metal). 1.0.1 makes `init()` fail-soft on a missing token (warn
+ continue from `CONF_SECRETS`), matching the documented contract. The
theta-env stack is unaffected (it always sets a scoped `VAULT_TOKEN`).
##### v1.13.0 — Changed
- **Secrets now load from OpenBao at boot** via
[@simpleworkjs/bao-conf](https://simpleworkjs.github.io/bao-conf/), which
deep-merges `secret/proxy/conf` over the file-loaded config. The proxy
authenticates to OpenBao with a scoped `VAULT_TOKEN` (policy `proxy` —
read-only on its own path), never the root token. Because the OIDC
`clientSecret` is captured at require time inside `createOidcClient` (during
`require('../models')`, which `require('../app')` triggers transitively),
`bin/www` now defers `require('../app')` until after `bao-conf.init()`
resolves. Fail-soft: if OpenBao is unreachable, boot continues from
`CONF_SECRETS`. The `config/proxy-secrets.js` file is now an operator-edit
seed artifact (gitignored); OpenBao is authoritative.
- Bumped package version to track the release tag.
#### jump-host — [v1.14.1](https://github.com/theta42/jump-host/releases/tag/v1.14.1) (via [v1.14.0](https://github.com/theta42/jump-host/releases/tag/v1.14.0))
##### v1.14.1 — Fixed
- **Bumped `@simpleworkjs/bao-conf` to 1.0.1** so standalone/no-OpenBao boots
don't crash. bao-conf 1.0.0's `init()` threw when `VAULT_TOKEN` was unset,
which — combined with `bin/www`'s `.catch(() => process.exit(1))` — made the
jump host exit at boot in any deployment without an OpenBao sidecar
(standalone Docker, bare metal). 1.0.1 makes `init()` fail-soft on a missing
token (warn + continue from `CONF_SECRETS`), matching the documented
contract. The theta-env stack is unaffected (it always sets a scoped
`VAULT_TOKEN`).
##### v1.14.0 — Changed
- **Secrets now load from OpenBao at boot** via
[@simpleworkjs/bao-conf](https://simpleworkjs.github.io/bao-conf/), which
deep-merges `secret/jump-host/conf` over the file-loaded config. The jump
host authenticates to OpenBao with a scoped `VAULT_TOKEN` (policy
`jump-host` — read-only on its own path), never the root token. Because the
OIDC `clientSecret` is captured at require time inside `createOidcClient`
(during `require('../models')`), `bin/www` now runs `bao-conf.init()`
**before** `require('../models')`. Fail-soft: if OpenBao is unreachable,
boot continues from `CONF_SECRETS`. The `config/jump-secrets.js` file is now
an operator-edit seed artifact (gitignored); OpenBao is authoritative.
- Bumped package version to track the release tag.
## [v1.27.2] - 2026-08-01
- Updated `proxy` to v1.12.1 (Dependabot security/maintenance bumps).
README.md
+27 -10
View File
@@ -181,11 +181,21 @@ operator-owned and `setup.env` is ignored.
would 404. Idempotent; skips a host that already exists.
6. Prints your first admin login + the public URLs.
### Configuration — `./config/` (no `.env` files)
### Configuration & secrets — OpenBao + `./config/`
All config and secrets live in a bind-mounted `./config/` directory (gitignored),
read by each app's `@simpleworkjs/conf` via the `CONF_SECRETS` env var, which
the entrypoint points at the mounted file:
Secrets live in **OpenBao** (a Vault fork, container `openbao:8200` on
`theta-net`), the single authoritative store. Each app loads them at boot with
[@simpleworkjs/bao-conf](https://simpleworkjs.github.io/bao-conf/), which
deep-merges `secret/<app>/conf` over the file-loaded config — **fail-soft**, so
if OpenBao is unreachable the app boots from the file fallback. End users get
personal per-user secret storage (`secret/users/<uid>/*`) in the SSO **Vault**
UI, and admins mint scoped tokens for external apps (`secret/apps/<name>/*`).
See **[docs/secrets.md](docs/secrets.md)** for the full architecture, policies,
token model, rotation, and the external-app convention.
A bind-mounted `./config/` directory (gitignored) holds the operator-edit
seed files and the fail-soft fallback, read by each app's `@simpleworkjs/conf`
via the `CONF_SECRETS` env var:
- **`./config/sso-secrets.js`** — SSO config: `ldap` (base, admin password,
user/group bases), `oauth` (issuer, `jwtSecret`), `smtp`, `name`, plus
@@ -196,11 +206,15 @@ the entrypoint points at the mounted file:
same `serviceAccountPass`), `auth` (admin groups/users).
`./setup.sh` generates both on first run from `./setup.env` (the one place the
domain is entered — see *Quickstart*) with random secrets. There is **no
`.env` / `proxy.env`** — edit `./config/*.js` directly. Compose only interpolates
port defaults (`SSO_PORT`, `HTTP_PORT`, etc.), which you can override on the
command line: `SSO_BIND=127.0.0.1 ./setup.sh`. See `config.example/` for the
full annotated shape, and each submodule's `secrets.js.example`.
domain is entered — see *Quickstart*) with random secrets, seeds them into
OpenBao, and mints scoped per-app tokens (`SSO_VAULT_TOKEN` /
`PROXY_VAULT_TOKEN` / `JUMP_VAULT_TOKEN`) into `./.env`. There is **no
`.env` / `proxy.env`** for app config — edit `./config/*.js` directly (and
re-seed into OpenBao, or use the SSO Configuration UI for live edits). Compose
only interpolates port defaults (`SSO_PORT`, `HTTP_PORT`, etc.), which you can
override on the command line: `SSO_BIND=127.0.0.1 ./setup.sh`. See
`config.example/` for the full annotated shape, and each submodule's
`secrets.js.example`.
> **Migrating from an older `.env`-based deployment?** If `.env` and/or
> `proxy.env` exist when you first run `./setup.sh`, it migrates them into
@@ -329,8 +343,11 @@ docker compose cp sso-manager:/data/dump.rdb sso-manager.rdb
docker compose exec proxy redis-cli BGSAVE
docker compose cp proxy:/data/dump.rdb proxy.rdb
# Secrets
# Secrets — ./config/ (the seed/fallback; OpenBao is authoritative)
cp -a ./config config-backup && chmod 700 config-backup
# OpenBao (the authoritative secret store — back up its data volume)
docker run --rm -v theta-env_openbao-data:/data -v "$PWD":/backup alpine \
tar czf /backup/openbao-data.tgz -C /data .
```
### Restore — full disaster recovery
bootstrap/bootstrap.js
Vendored
+60
View File
@@ -23,6 +23,13 @@
* into the file (the sso-manager mounts ./config
* read-write for this purpose).
*
* Generated creds are ALSO written into OpenBao (secret/proxy/conf and, when
* the jump host is enabled, secret/jump-host/conf) so the proxy + jump host
* load them from OpenBao at boot via @simpleworkjs/bao-conf. setup.sh passes
* the root VAULT_TOKEN on this exec for that purpose. The OpenBao write is
* fail-soft: if VAULT_TOKEN is unset or OpenBao is unreachable, the /config
* file remains the fallback and bootstrap does not fail the bring-up over it.
*
* Idempotent: re-running converges to the ./config values. The LDAP service
* account + admin passwords are reset to the file values on each run; the
* OAuth client is created if missing. If proxy-secrets.js already holds a
@@ -87,6 +94,44 @@ const ADMIN_GROUPS = ['app_sso_admin', 'app_sso_oauth_admin'];
const log = (...a) => process.stderr.write('[bootstrap] ' + a.join(' ') + '\n');
const out = (k, v) => process.stdout.write(`${k}=${v}\n`);
// ── OpenBao (Vault) writes ───────────────────────────────────────────────────
// bootstrap generates the proxy's + jump host's OAuth client creds and writes
// them back into /config/*-secrets.js (the file fallback). It ALSO writes the
// complete conf into OpenBao so the proxy + jump host load it from there at
// boot via @simpleworkjs/bao-conf. setup.sh passes the root VAULT_TOKEN on this
// exec. Fail-soft: if VAULT_TOKEN is unset or OpenBao is unreachable, the write
// is skipped with a warning — the file remains the fallback and bootstrap does
// not fail the bring-up over it.
const VAULT_ADDR = process.env.VAULT_ADDR || 'http://openbao:8200';
const VAULT_TOKEN = process.env.VAULT_TOKEN || '';
// Re-require a /config module after its file has been rewritten on disk
// (require caches the old contents otherwise).
function freshRequire(p) {
delete require.cache[require.resolve(p)];
return require(p);
}
// PUT (replace) the data at secret/data/<vaultPath> with `data`. Warn-only.
async function baoPut(vaultPath, data) {
if (!VAULT_TOKEN) { log('OpenBao: VAULT_TOKEN unset — skipping write of secret/' + vaultPath); return; }
try {
const res = await fetch(`${VAULT_ADDR}/v1/secret/data/${vaultPath}`, {
method: 'POST',
headers: { 'X-Vault-Token': VAULT_TOKEN, 'Content-Type': 'application/json' },
body: JSON.stringify({ data }),
});
if (!res.ok) {
const text = await res.text().catch(() => '');
log(`WARNING: OpenBao write secret/${vaultPath} failed (${res.status}) ${text} — app will use its file fallback`);
} else {
log(`OpenBao: wrote secret/${vaultPath}`);
}
} catch (e) {
log(`WARNING: OpenBao write secret/${vaultPath} threw (${e.message}) — app will use its file fallback`);
}
}
// Replicate the SSO's hashPasswordSSHA512 (models/user_ldap.js) exactly so the
// directory stores passwords the SSO can verify on bind (pw-sha2 module).
function hashPasswordSSHA512(password) {
@@ -663,6 +708,14 @@ async function provisionJumpHost(token) {
resolvedClientId = id;
}
// Mirror the (now-current) proxy-secrets.js into OpenBao so the proxy
// loads it from there at boot via @simpleworkjs/bao-conf. Re-require
// fresh: writeProxyCreds rewrote the file out from under the cached
// `proxy` object. setup.sh's seed already put a placeholder version
// here; this replaces it with the complete file (operator edits +
// generated OAuth creds). Warn-only.
await baoPut('proxy/conf', freshRequire('/config/proxy-secrets.js'));
// Provision the jump host (mint token + write config) when enabled.
// Warn-only — never fail the whole bring-up over the optional service.
let jumpClientId = null;
@@ -670,6 +723,13 @@ async function provisionJumpHost(token) {
try {
jumpClientId = await provisionJumpHost(token);
out('JUMP_HOST_CONFIGURED', '1');
// Mirror jump-secrets.js (just written by provisionJumpHost)
// into OpenBao so the jump host loads it from there at boot via
// @simpleworkjs/bao-conf. setup.sh's seed may have put a
// placeholder/stale version here; this replaces it with the
// complete file (LDAP bind, minted API token, OAuth client).
// Warn-only.
await baoPut('jump-host/conf', freshRequire(JUMP_SECRETS));
} catch (e) {
log(`WARNING: jump host provisioning failed (${e.message || e}) — continuing`);
}
docker-compose.yml
+30 -7
View File
@@ -59,14 +59,18 @@ services:
- "${LDAPS_PORT:-636}:636"
# Plain LDAP (389) is NOT mapped — direct-LDAP clients should use LDAPS.
environment:
# Config (LDAP, OAuth, SMTP, ...) comes from ./config/sso-secrets.js (see
# volumes below), not from env. NODE_ENV/NODE_PORT are the only env the app
# reads that are not part of its conf tree.
# Config (LDAP, OAuth, SMTP, ...) is loaded by @simpleworkjs/conf from
# ./config/sso-secrets.js (see volumes), then @simpleworkjs/bao-conf
# deep-merges secret/sso-manager/conf from OpenBao over it at boot
# (VAULT_ADDR/VAULT_TOKEN below). NODE_ENV/NODE_PORT are the only other
# env the app reads. VAULT_TOKEN is the scoped SSO_VAULT_TOKEN minted by
# setup.sh (policy sso-broker) — NOT the root token.
- NODE_ENV=production
- NODE_PORT=3001
- LDAP_SERVER_ID=${LDAP_SERVER_ID:-}
- LDAP_REPLICATION_HOSTS=${LDAP_REPLICATION_HOSTS:-}
- VAULT_TOKEN=${VAULT_TOKEN:-}
- VAULT_ADDR=http://openbao:8200
- VAULT_TOKEN=${SSO_VAULT_TOKEN:-}
# Optional upstream HTTP(S) proxy for outbound calls (SMTP, etc.) at
# runtime. See the build args above for the same setting during build.
- HTTP_PROXY=${CFG_HTTP_PROXY:-}
@@ -116,6 +120,8 @@ services:
depends_on:
sso-manager:
condition: service_healthy
openbao:
condition: service_started
ports:
- "${HTTP_PORT:-80}:80"
- "${HTTPS_PORT:-443}:443"
@@ -125,10 +131,17 @@ services:
# to lock it to localhost once the proxy fronts it under TLS.
- "${MGMT_BIND:-0.0.0.0}:${MGMT_PORT:-3000}:3000"
environment:
# oidc/ldap/auth config comes from ./config/proxy-secrets.js (see volumes),
# not from env. NODE_ENV/NODE_PORT are process env the app reads directly.
# oidc/ldap/auth config is loaded by @simpleworkjs/conf from
# ./config/proxy-secrets.js (see volumes), then @simpleworkjs/bao-conf
# deep-merges secret/proxy/conf from OpenBao over it at boot. The OAuth
# clientSecret is consumed at require time, so bao-conf.init() runs
# BEFORE require('../app') in bin/www. NODE_ENV/NODE_PORT are process env
# the app reads directly. VAULT_TOKEN is the scoped PROXY_VAULT_TOKEN
# (policy proxy — read only secret/proxy/conf).
- NODE_ENV=production
- NODE_PORT=3000
- VAULT_ADDR=http://openbao:8200
- VAULT_TOKEN=${PROXY_VAULT_TOKEN:-}
# Optional upstream HTTP(S) proxy for outbound calls (ACME/Let's
# Encrypt, DNS providers) at runtime.
- HTTP_PROXY=${CFG_HTTP_PROXY:-}
@@ -137,7 +150,9 @@ services:
volumes:
# Operator-edited proxy secrets (proxy-secrets.js). READ-ONLY — the proxy
# only reads it; the sso-manager bootstrap writes the OAuth creds. The
# entrypoint points CONF_SECRETS at /config/proxy-secrets.js.
# entrypoint points CONF_SECRETS at /config/proxy-secrets.js. Kept as a
# fail-soft fallback: bao-conf.init() is fail-soft, so if OpenBao is
# unreachable the app boots from this file instead.
- ./config:/config:ro
# Persist Redis (AOF + RDB) so Host records, permissions, DNS creds, local
# users, AND the auto-ssl Let's Encrypt certs survive container recreation.
@@ -177,11 +192,19 @@ services:
depends_on:
sso-manager:
condition: service_healthy
openbao:
condition: service_started
ports:
- "${JUMP_SSH_PORT:-2222}:2222" # SSH front door
- "${JUMP_WEB_BIND:-0.0.0.0}:${JUMP_WEB_PORT:-3002}:3002" # web UI/API
environment:
- NODE_ENV=production
# Secrets are loaded by @simpleworkjs/conf from ./config/jump-secrets.js,
# then @simpleworkjs/bao-conf deep-merges secret/jump-host/conf from
# OpenBao over it at boot. VAULT_TOKEN is the scoped JUMP_VAULT_TOKEN
# (policy jump-host — read only secret/jump-host/conf).
- VAULT_ADDR=http://openbao:8200
- VAULT_TOKEN=${JUMP_VAULT_TOKEN:-}
# Optional upstream HTTP(S) proxy for outbound calls (the directory API
# client) at runtime.
- HTTP_PROXY=${CFG_HTTP_PROXY:-}
docs/_config.yml
+3
View File
@@ -25,6 +25,9 @@ nav:
- title: Architecture
page: /architecture.html
icon: fa-sitemap
- title: Secrets
page: /secrets.html
icon: fa-key
- title: Standalone
page: /standalone.html
icon: fa-puzzle-piece
docs/secrets.md
+195
View File
@@ -0,0 +1,195 @@
---
layout: default
title: Secrets (OpenBao)
description: theta-env's central secrets architecture — OpenBao as the single store for all app, per-user, and external-app secrets, with scoped tokens and policies.
---
# Secrets — OpenBao as the central store
theta-env keeps **every secret in one place: [OpenBao](https://openbao.org/)**
(a Vault-community fork), running on the `theta-net` docker network at
`http://openbao:8200`. The three apps (SSO Manager, proxy, jump host) load
their boot secrets from it; end users get personal per-user secret storage
through the SSO UI; and external apps get scoped, self-contained access to
their own namespace.
This page is the operator reference. For the package API, see
[@simpleworkjs/bao-conf](https://simpleworkjs.github.io/bao-conf/).
## Why a central store
Before this, secret handling was partial and inconsistent: only the SSO read
one path from OpenBao; the proxy and jump host read bind-mounted
`./config/*-secrets.js` files; the bootstrap wrote generated OAuth creds to
those files on disk; and the SSO `/api/vault` UI was an ungated, broken
pass-through. Centralising on OpenBao gives every app the same fail-soft load
path, makes per-user secret storage possible, and lets external apps get
least-privilege access without anyone handing them the root token.
## The load path (every app)
1. `@simpleworkjs/conf` **synchronously** loads the bind-mounted
`./config/<app>-secrets.js` at require time — the file is the operator-edit
layer and the fail-soft fallback.
2. `@simpleworkjs/bao-conf`'s `init({ path: '<app>', conf })` **deep-merges**
`secret/data/<app>/conf` from OpenBao over the live `conf` object. It is
**fail-soft**: if OpenBao is unreachable or the path is absent, boot
continues with the file-loaded config.
3. A few secrets are **captured at require time** (notably the OIDC
`clientSecret`, consumed inside `createOidcClient` during
`require('../models')`). So `init()` must resolve *before* that
`require()`. Each app's `bin/www` handles this:
- **proxy** — defers `require('../app')` (which transitively loads models)
behind `bao-conf.init()`.
- **jump host** — gates the explicit `require('../models')` behind
`bao-conf.init()`.
- **SSO** — swaps the old `conf_manager.init()` call (same position in its
existing `.then()` boot chain) for `bao-conf.init()`; nothing in the SSO
captures a secret at require time, so no reordering was needed.
`VAULT_TOKEN` (a scoped per-app token, **not** the root token) and
`VAULT_ADDR=http://openbao:8200` are passed to each container via
`docker-compose.yml`. The `./config/*-secrets.js` mounts stay as the fallback.
## Policies, token role, and tokens
`setup.sh` creates the ACL policies and mints the per-app tokens
(idempotently — re-running keeps existing tokens and re-mints only expired
ones). The root token stays in `.env` for setup/maintenance **only** and is
never passed to a service container.
| Policy | Capabilities | Held by |
|---|---|---|
| `sso-broker` | read/write `secret/sso-manager/conf`, `secret/users/*`, `secret/apps/*`; `update` on `auth/token/create/sso-broker`; `update` on `sys/policies/acl/user-*`, `app-*`, `sso-admin` | SSO (`SSO_VAULT_TOKEN`) |
| `sso-admin` | read/write/list all of `secret/*` | admin UI sessions (minted by the broker) |
| `proxy` | read `secret/proxy/conf` | proxy (`PROXY_VAULT_TOKEN`) |
| `jump-host` | read `secret/jump-host/conf` | jump host (`JUMP_VAULT_TOKEN`) |
| `user-<uid>` | read/write `secret/users/<uid>/*` | per-user tokens (minted lazily by the broker) |
| `app-<name>` | read/write `secret/apps/<name>/*` | per-external-app tokens (minted by an admin) |
**Token role `sso-broker`** — `allowed_policies=sso-admin`,
`allowed_policies_glob=user-*,app-*`, orphan, renewable, `token_period=24h`.
The SSO mints per-user, per-admin, and per-app tokens *through* this role at
runtime, so it never needs the root token to issue scoped access.
The three per-app tokens (`SSO_VAULT_TOKEN`, `PROXY_VAULT_TOKEN`,
`JUMP_VAULT_TOKEN`) are minted orphan + renewable and stored in `./.env` by
`setup.sh`. They use OpenBao's default service-token TTL; if one expires,
re-run `./setup.sh` and the `ensure_token` helper re-mints it (the old one
expires on its own). Automated renewal is a planned follow-up, not yet built.
## Seeding
`setup.sh` seeds, on first run only (skipped if the path already exists):
- `secret/sso-manager/conf` — from `./config/sso-secrets.js` (operator-set
LDAP/SMTP/`jwtSecret`; the SSO has no bootstrap-generated creds, so the file
is the complete source of truth).
- `secret/proxy/conf` — from `./config/proxy-secrets.js` (placeholder OAuth
creds at this point).
- `secret/jump-host/conf` — from `./config/jump-secrets.js` after the bootstrap
writes it.
The **bootstrap** (`bootstrap/bootstrap.js`) then generates the real OAuth
client credentials and writes the *complete* `proxy-secrets.js` and
`jump-secrets.js` objects into `secret/proxy/conf` and `secret/jump-host/conf`
(POST, replacing the placeholder seed). After the first run, OpenBao is
authoritative; the `./config/*-secrets.js` files are operator-edit seed
artifacts and the fail-soft fallback.
## End-user personal secrets
Every logged-in user has a personal namespace `secret/users/<uid>/*`, reached
through the SSO UI at **Vault → My Secrets**. The SSO mints a `user-<uid>`
token on first access (cached in Redis for the token's lifetime) and proxies
`/api/vault` to OpenBao with **that** token injected server-side — the
client's SSO session token never reaches OpenBao.
- **Non-admins** see only their own namespace; the UI fixes the path prefix
to `users/<uid>/`. They can list, read, write, and delete secrets there.
- **Admins** (`app_sso_admin` / `app_super_admin`) get free-form access across
all of `secret/` plus an **Apps** tab (see below).
Scoping is enforced at **two** layers: the SSO's `scopeGuard` rejects any path
outside the subject's prefix with a 403 (defense-in-depth), and the token's
own OpenBao policy enforces the same at the API layer.
## External apps
An external (non-theta42) app gets scoped access to its own namespace,
`secret/apps/<name>/*`, via a token an admin mints once from the SSO UI's
**Vault → Apps** tab. The token is shown **once** (copy it immediately; it is
not stored retrievably) and confined by an `app-<name>` policy.
Convention:
- `secret/apps/<name>/conf` for config-style secrets, `secret/apps/<name>/*`
for arbitrary keys.
- The app authenticates with the header `X-Vault-Token: <minted token>`
against `http://<openbao-host>:8200/v1/secret/data/apps/<name>/...`.
Non-Node consumers (curl):
```bash
VAULT_ADDR=http://openbao:8200 # or your external-facing openbao address
# Write
curl -X POST "$VAULT_ADDR/v1/secret/data/apps/my-service/conf" \
-H "X-Vault-Token: <token>" -H "Content-Type: application/json" \
-d '{"data":{"db_password":"..."}}'
# Read
curl -s "$VAULT_ADDR/v1/secret/data/apps/my-service/conf" \
-H "X-Vault-Token: <token>" | jq .data.data
```
Node consumers can use [@simpleworkjs/bao-conf](https://simpleworkjs.github.io/bao-conf/)
directly:
```js
const baoConf = require('@simpleworkjs/bao-conf');
const data = await baoConf.get('apps/my-service/conf'); // secret/data/apps/my-service/conf
await baoConf.set('apps/my-service/conf', { db_password: '...' });
```
## Operator rotation
If a secret is exposed (or just on a routine schedule), rotate it at the
**provider** first (the LDAP server, the SMTP host, the OAuth `jwtSecret`,
etc.), then update OpenBao:
```bash
# Read the current sso-manager conf
docker exec -e BAO_TOKEN="$VAULT_TOKEN" openbao bao kv get secret/sso-manager/conf
# Write a new value (KV-v2 POST replaces the data; merge carefully)
docker exec -e BAO_TOKEN="$VAULT_TOKEN" openbao bao kv put secret/sso-manager/conf \
ldap.bindPassword='<new>' smtp.password='<new>' oauth.jwtSecret='<new>'
```
Then restart the affected app so `bao-conf.init()` re-reads it
(`docker compose restart sso-manager`). Call-time readers pick up the change
on next read; require-time captures (OIDC `clientSecret`) need the restart.
> The SSO admin **Configuration** UI (`/api/conf`) writes `secret/sso-manager/conf`
> and updates the live conf immediately, so SMTP/discovery/oauth edits made
> there don't need a manual `bao kv put`.
## Backups
The OpenBao data volume `openbao-data` holds every secret. Back it up with the
rest of the stack (see the README's *Backups and restore* section). The
`./config/*-secrets.js` files are **not** a complete secret backup once OpenBao
is authoritative — they're the first-run seed and the fallback. A full disaster
recovery restores both the `openbao-data` volume (the authoritative store) and
`./config/` (the seed/fallback), then runs `./setup.sh` to unseal OpenBao and
re-mint the per-app tokens.
## What's not in scope yet
- **Renewal automation** — per-app/user tokens use OpenBao's default TTL and
are re-minted by `setup.sh` on expiry; a periodic renewal worker is a
follow-up.
- **History scrubbing** — if a secret was committed to git, rotating it is the
fix; scrubbing it from git history (BFG / `git filter-repo`) is a separate,
git-destructive operation you can opt into.
- **Per-app secrets beyond boot config** (e.g. the proxy's DNS-provider creds,
the jump host's per-user LDAP SSH keys) moving into OpenBao — only the
boot-critical `*-secrets.js` contents moved in this phase.
jump-host
+1 -1
Submodule jump-host updated: f386a5f9c3...db3333e26d
proxy
+1 -1
Submodule proxy updated: a44d7ef7ab...4aa994121a
setup.sh
+134 -7
View File
@@ -703,6 +703,119 @@ if ! docker exec -e BAO_TOKEN="$VAULT_TOKEN" openbao bao secrets list -format=js
docker exec -e BAO_TOKEN="$VAULT_TOKEN" openbao bao secrets enable -path=secret kv-v2 >/dev/null
fi
# ── 3c. OpenBao policies, token role, per-app tokens ─────────────────────────
# Each app gets a least-privilege scoped token (a policy over only its own
# secret/<app>/conf). sso additionally gets the `sso-broker` policy so it can
# mint per-user (user-<uid>) and per-app (app-<name>) tokens at runtime through
# the sso-broker token role. The root VAULT_TOKEN stays in .env for
# setup/maintenance ONLY and is never passed to a service container. Everything
# here is idempotent — re-running setup.sh keeps existing policies/tokens.
# Run a `bao` command inside the openbao container as root.
bao_run() { docker exec -e BAO_TOKEN="$VAULT_TOKEN" openbao bao "$@"; }
# Write an ACL policy from stdin HCL only if it does not already exist.
ensure_policy() {
local name="$1"
if bao_run policy read "$name" >/dev/null 2>&1; then
info " policy ${name} already exists — keeping."
else
info " writing policy ${name}..."
docker exec -i -e BAO_TOKEN="$VAULT_TOKEN" openbao bao policy write "$name" - >/dev/null
fi
}
# Read KEY= from ./.env (empty if absent) — reuse a previously minted token
# instead of minting a fresh one on every setup.sh run.
env_get() {
local key="$1" file=./.env
[[ -f "$file" ]] || return 0
grep -m1 "^${key}=" "$file" 2>/dev/null | cut -d= -f2-
}
# Mint an orphan, renewable token for `policy` and persist it to .env as `key`,
# OR reuse the token already in .env if it is still valid (re-mint on expiry).
ensure_token() {
local key="$1" policy="$2" existing tok
existing="$(env_get "$key")"
if [[ -n "$existing" ]] && docker exec -e BAO_TOKEN="$existing" openbao bao token lookup >/dev/null 2>&1; then
info " ${key} already minted + valid — keeping."
return 0
fi
info " minting ${key} (policy=${policy})..."
tok="$(bao_run token create -policy="$policy" -orphan=true -field=token)" \
|| die "failed to mint ${key} (policy=${policy})"
env_upsert "$key" "$tok"
}
# Seed secret/<vault_path> from a /config/*.js module on first run only
# (skipped if the path already exists). Fail-soft: a seed failure leaves the
# app's file-mounted config as the fallback — boot is not blocked.
seed_app_conf() {
local vault_path="$1" mod="$2"
if bao_run kv get "secret/${vault_path}" >/dev/null 2>&1; then
info " secret/${vault_path} already seeded — keeping."
return 0
fi
info "Seeding secret/${vault_path} from ${mod}..."
docker exec sso-manager node -e "console.log(JSON.stringify(require('${mod}')))" 2>/dev/null \
| docker exec -i -e BAO_TOKEN="$VAULT_TOKEN" openbao bao kv put "secret/${vault_path}" - >/dev/null \
|| warn " could not seed secret/${vault_path} (continuing — app will use its file fallback)"
}
info "Configuring OpenBao policies..."
# sso-broker — sso's authority to read/write its own conf, mint per-user and
# per-app tokens (auth/token/create/sso-broker), and create the matching
# user-<uid> / app-<name> / sso-admin policies.
ensure_policy sso-broker <<'HCL'
path "secret/data/sso-manager/conf" { capabilities = ["create", "read", "update", "delete", "list"] }
path "secret/metadata/sso-manager/conf" { capabilities = ["list", "read", "delete"] }
path "secret/data/users/*" { capabilities = ["create", "read", "update", "delete", "list"] }
path "secret/metadata/users/*" { capabilities = ["list", "read", "delete"] }
path "secret/data/apps/*" { capabilities = ["create", "read", "update", "delete", "list"] }
path "secret/metadata/apps/*" { capabilities = ["list", "read", "delete"] }
path "auth/token/create/sso-broker" { capabilities = ["update"] }
path "sys/policies/acl/user-*" { capabilities = ["create", "read", "update", "delete", "list"] }
path "sys/policies/acl/app-*" { capabilities = ["create", "read", "update", "delete", "list"] }
path "sys/policies/acl/sso-admin" { capabilities = ["create", "read", "update", "delete", "list"] }
HCL
# sso-admin — admin users in the vault UI: read/write/list everything under secret/.
ensure_policy sso-admin <<'HCL'
path "secret/data/*" { capabilities = ["create", "read", "update", "delete", "list"] }
path "secret/metadata/*" { capabilities = ["list", "read", "delete"] }
HCL
# proxy / jump-host — read only their own boot conf.
ensure_policy proxy <<'HCL'
path "secret/data/proxy/conf" { capabilities = ["read"] }
path "secret/metadata/proxy/conf" { capabilities = ["read", "list"] }
HCL
ensure_policy jump-host <<'HCL'
path "secret/data/jump-host/conf" { capabilities = ["read"] }
path "secret/metadata/jump-host/conf" { capabilities = ["read", "list"] }
HCL
# sso-broker token role: lets sso mint user-*/app-*/sso-admin tokens. Orphan,
# renewable, 24h period. Wildcards need allowed_policies_glob — allowed_policies
# is exact-match only.
info "Configuring sso-broker token role..."
if ! bao_run read auth/token/roles/sso-broker >/dev/null 2>&1; then
docker exec -i -e BAO_TOKEN="$VAULT_TOKEN" openbao bao write auth/token/roles/sso-broker - <<'JSON' >/dev/null
{"allowed_policies":["sso-admin"],"allowed_policies_glob":["user-*","app-*"],"orphan":true,"renewable":true,"token_period":"24h"}
JSON
else
info " token role sso-broker already exists — keeping."
fi
info "Minting per-app OpenBao tokens (stored in .env, passed to containers as VAULT_TOKEN)..."
ensure_token SSO_VAULT_TOKEN sso-broker
ensure_token PROXY_VAULT_TOKEN proxy
ensure_token JUMP_VAULT_TOKEN jump-host
info "OpenBao secrets configured:"
info " policies: sso-broker, sso-admin, proxy, jump-host (+ per-user/app created lazily by sso)"
info " token role: sso-broker (mints user-*/app-*/sso-admin tokens, 24h period)"
info " app tokens: SSO_VAULT_TOKEN, PROXY_VAULT_TOKEN, JUMP_VAULT_TOKEN in .env"
# ── 4. Start SSO Manager, wait for health ─────────────────────────────────────
# SSO_GIT_COMMIT: sso-manager-node is a git submodule here, so its .git is a
# pointer file (not a real repo) -- the image can't resolve its own commit
@@ -727,12 +840,15 @@ for i in $(seq 1 60); do
sleep 2
done
if ! docker exec -e BAO_TOKEN="$VAULT_TOKEN" openbao bao kv get secret/sso-manager/conf >/dev/null 2>&1; then
info "Seeding sso-manager/conf into Openbao..."
docker exec sso-manager node -e "console.log(JSON.stringify(require('/config/sso-secrets.js')))" > "$CONFIG_DIR/seed-conf.json"
cat "$CONFIG_DIR/seed-conf.json" | docker exec -i -e BAO_TOKEN="$VAULT_TOKEN" openbao bao kv put secret/sso-manager/conf -
rm -f "$CONFIG_DIR/seed-conf.json"
fi
info "Seeding app configs into OpenBao (idempotent)..."
# sso-manager/conf holds the operator-set LDAP/SMTP/jwtSecret values — sso has
# no bootstrap-generated creds, so the file is the complete source of truth.
seed_app_conf sso-manager/conf /config/sso-secrets.js
# proxy/conf is seeded from the operator file (placeholder OAuth creds); the
# bootstrap (step 5) then writes the real generated OAuth client creds into
# OpenBao over this. proxy boots at step 6, after bootstrap, so it sees the
# real values.
seed_app_conf proxy/conf /config/proxy-secrets.js
# Read the summary values (hosts, admin, base DN) back from ./config via the
# running container's node — works whether ./config was generated or pre-existing.
@@ -764,7 +880,11 @@ info " Admin uid: ${ADMIN_UID}"
# ── 5. Run the bootstrap (writes CLIENT_ID/CLIENT_SECRET/ALREADY_CONFIGURED) ──
# The bootstrap reads its inputs from /config/*.js (not env) and writes the
# generated OAuth client creds back into /config/proxy-secrets.js. No -e flags.
# generated OAuth client creds back into /config/proxy-secrets.js AND into
# OpenBao (secret/proxy/conf, secret/jump-host/conf) so the proxy + jump host
# load them from OpenBao at boot. The root VAULT_TOKEN is passed on this one
# exec so bootstrap can write those paths; it is never handed to a service
# container.
info "Running bootstrap (creates/updates the LDAP service account, first admin, OAuth client)..."
# Host facts for the directory seed — collected HERE (on the host; inside the
# container hostname/uname describe the container, not the machine). Same
@@ -786,6 +906,8 @@ BOOTSTRAP_OUT=$("${COMPOSE[@]}" exec -T \
-e STACK_HOST_KERNEL="$STACK_HOST_KERNEL" \
-e CFG_JUMP_HOST_ENABLED="${CFG_JUMP_HOST_ENABLED:-}" \
-e CFG_JUMP_HOST="${CFG_JUMP_HOST:-}" \
-e VAULT_ADDR=http://openbao:8200 \
-e VAULT_TOKEN="$VAULT_TOKEN" \
sso-manager node /bootstrap/bootstrap.js) \
|| die "bootstrap failed:\n${BOOTSTRAP_OUT}"
@@ -872,6 +994,11 @@ if [[ "$JUMP_ENABLED" == "1" ]]; then
JUMP_GIT_COMMIT="$(git -C jump-host rev-parse --short HEAD 2>/dev/null || echo unknown)"
export JUMP_GIT_COMMIT
env_upsert JUMP_GIT_COMMIT "$JUMP_GIT_COMMIT"
# Seed jump-host/conf from the file bootstrap just wrote (it mints the API
# token + OAuth client into /config/jump-secrets.js at step 5). bootstrap
# also writes this to OpenBao directly, so this is a fallback for when
# bootstrap's jump provisioning warned-but-continued.
seed_app_conf jump-host/conf /config/jump-secrets.js
info "Building + starting jump-host (optional; enabled via CFG_JUMP_HOST_ENABLED)..."
"${COMPOSE[@]}" up -d --build jump-host
sso-manager-node
+1 -1
Submodule sso-manager-node updated: 74746e409b...ebb5b2c2a7