From 11fb2c0a54af56fb8aa6ce2fba9c0a4534737e8c Mon Sep 17 00:00:00 2001 From: William Mantly Date: Mon, 13 Jul 2026 21:56:48 -0400 Subject: [PATCH] docs: document that the domain/base DN is entered once (#37) The base DN (stack.ldapBaseDn) is the single place the domain is set; the LDAP DNs (bindDN/userBase/groupBase) and oauth.issuer all derive from it and must stay consistent. Drifting them apart (leaving bindDN at dc=example,dc=com while ldapBaseDn is the real domain) makes the SSO bind against a non-existent root DN and every login fails with Invalid Credentials. - secrets.js.example: clarifying comment at ldapBaseDn - DEPLOYMENT.md: "domain entered once as the base DN" note + theta-env setup.env cross-link (merged the two duplicate theta-env blockquotes) - README.md: cross-link to DEPLOYMENT.md from "Server set up" Docs only; no app/secrets-structure change. Co-authored-by: Claude --- DEPLOYMENT.md | 18 +++++++++++++++--- README.md | 6 ++++++ secrets.js.example | 5 ++++- 3 files changed, 25 insertions(+), 4 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 475edf6..47ce35a 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -62,9 +62,21 @@ admin password, org, domain, cert CN, JWT secret) out of the same file. No `app_*` env is passed — `app_*` env would override `secrets.js` (env beats the file in `@simpleworkjs/conf`), so the file is kept authoritative. -> Running the unified `theta-env` stack? Its `setup.sh` generates -> `./config/sso-secrets.js` (+ `./config/proxy-secrets.js`) for you with random -> secrets and snapshots state before rebuilds — see the theta-env README. +> **Your domain is entered once, as the LDAP base DN.** Set `stack.ldapBaseDn` +> (e.g. `dc=718it,dc=biz`) and keep the LDAP DNs consistent with it — they all +> derive from that one value: `ldap.bindDN` = `cn=admin,`, +> `ldap.userBase` = `ou=people,`, `ldap.groupBase` = `ou=groups,`, +> and `stack.ldapDomain` = the dotted form (`718it.biz`). `oauth.issuer` is the +> public SSO URL (`https://`). Drifting these apart (e.g. leaving +> `ldap.bindDN` at `dc=example,dc=com` while `stack.ldapBaseDn` is your real +> domain) makes the SSO bind against a non-existent root DN and every login +> fails with `Invalid Credentials`. +> +> Running the unified `theta-env` stack? You don't hand-edit these DNs at all +> — its `setup.sh` generates `./config/sso-secrets.js` (+ `./config/proxy-secrets.js`) +> from a single `setup.env` (where the domain is asked once, as the base DN) with +> random secrets, and snapshots state before rebuilds — so the DNs can't drift. +> See the theta-env README. **Quick test (defaults):** with no `./config/sso-secrets.js` the entrypoint falls back to env-mode with safe defaults (`dc=example,dc=com`, admin password diff --git a/README.md b/README.md index 79e6da1..51a1915 100755 --- a/README.md +++ b/README.md @@ -9,6 +9,12 @@ The server requires: * NodeJS 13.x * LDAP server +> Setting up the whole stack (Docker) or want the secrets-file layout? See +> [DEPLOYMENT.md](DEPLOYMENT.md) — your domain is entered **once**, as the LDAP +> base DN (`stack.ldapBaseDn`); the LDAP DNs (`bindDN`/`userBase`/`groupBase`) +> and `oauth.issuer` all derive from it and must stay consistent. Running the +> unified `theta-env` stack, `setup.sh` fills those in for you from `setup.env`. + ### OpenLDAP configuration #### Password hashing (required) diff --git a/secrets.js.example b/secrets.js.example index 22317fc..e79f734 100644 --- a/secrets.js.example +++ b/secrets.js.example @@ -52,7 +52,10 @@ module.exports = { // Read by docker-entrypoint.sh (server-side slapd config + validation), the // superproject bootstrap script, and setup.sh. Omit for bare-metal use. stack: { - ldapBaseDn: 'dc=example,dc=com', // slapd suffix (also drives seed OUs) + ldapBaseDn: 'dc=example,dc=com', // slapd suffix (also drives seed OUs). + // The base DN also appears in ldap.bindDN/userBase/groupBase above and + // in oauth.issuer — keep them consistent with this value + // (cn=admin,, ou=people,, ou=groups,, https://). ldapDomain: 'example.com', // default cert CN + OAuth issuer host ldapCertCn: '', // cert CN; empty -> defaults to ldapDomain ssoHost: 'sso.example.com', // public SSO hostname (OAuth issuer URL)