diff --git a/README.md b/README.md index 0202acb..4ff880f 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ The SSO Manager and the proxy it fronts, both stood up by one `./setup.sh` run: | SSO Manager Dashboard | Proxy Hosts | | --- | --- | -| ![SSO Manager dashboard](docs/images/sso-dashboard.png) | ![Proxy host list](docs/images/proxy-hosts.png) | +| [![SSO Manager dashboard](docs/images/sso-dashboard.png)](docs/images/sso-dashboard.png) | [![Proxy host list](docs/images/proxy-hosts.png)](docs/images/proxy-hosts.png) | **Why use this instead of running the two separately?** The two only become useful once the proxy is registered as an OIDC client of the SSO and pointed at diff --git a/docs/_config.yml b/docs/_config.yml index b770f1b..a1c59dc 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,7 +1,7 @@ title: theta-env description: A unified, one-command SSO Manager + OIDC proxy stack for home labs and small businesses theme: jekyll-theme-cayman -show_downloads: true +show_downloads: false github: repository_url: https://github.com/theta42/theta-env zip_url: https://github.com/theta42/theta-env/archive/refs/heads/master.zip diff --git a/docs/index.md b/docs/index.md index ffc5986..270f16f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,123 +5,62 @@ title: Home # theta-env -A single repo that runs the whole theta42 identity + access stack — -[SSO Manager](https://github.com/theta42/sso-manager-node) (OIDC provider + LDAP) -and the [theta42/proxy](https://github.com/theta42/proxy) (OIDC-protected reverse -proxy) — together, with **one command**, for home labs and small businesses. +The whole theta42 identity + access stack in one repo, brought up with a +single command — for home labs and small businesses. -It exists for people whose needs are met by these two projects and who want to -run them "very simply." Each project still works **standalone**; this repo just -wires them together and automates the first-run glue. +It wires together two projects that already work on their own — +[SSO Manager](https://theta42.github.io/sso-manager-node/) (OIDC provider + +LDAP directory) and [Proxy](https://theta42.github.io/proxy/) (an +OIDC-protected reverse proxy that can also look users up directly in LDAP) — +and automates the fiddly part: registering the proxy as an OIDC client of the +SSO and pointing it at the right LDAP directory, with hostnames and secrets +generated from one `setup.env`. ## Screenshots The SSO Manager and the proxy it fronts, both stood up by one `./setup.sh` run: -| SSO Manager Dashboard | Proxy Hosts | -| --- | --- | -| ![SSO Manager dashboard](images/sso-dashboard.png) | ![Proxy host list](images/proxy-hosts.png) | +SSO Manager dashboard +Proxy host list ---- +*(click either screenshot to view full size)* -## Quick start +## Why this over running them separately + +Each project works standalone, but they only become useful together once the +proxy is registered as an OIDC client of the SSO *and* pointed at the SSO's +LDAP directory — and the domain has to match across half a dozen config +fields, or logins silently fail. Doing that by hand is fiddly. `setup.sh` +asks for your domain once, generates both apps' config with it filled in +everywhere, registers the proxy as an OIDC client automatically, and +snapshots state before every rebuild. + +## What you get + +- **SSO Manager**, fronted by the proxy under TLS — manage users, groups, + and OAuth clients. +- **Proxy** — add the hosts you want to protect with OIDC login. +- **LDAPS** for legacy apps that bind directly. +- **Self-service API tokens** in both apps' UIs, for scripting/CI without a + browser session. + +## Get it ```bash git clone --recursive https://github.com/theta42/theta-env.git cd theta-env cp setup.env.example setup.env # then edit setup.env: set CFG_DOMAIN to your domain -./setup.sh # first run: generates ./config/ from setup.env, builds + bootstraps + starts +./setup.sh ``` -You need **Docker** + **Docker Compose**. `./setup.sh` is idempotent — re-run any -time to converge the stack to `./config/`. +You need **Docker** + **Docker Compose**. `./setup.sh` is idempotent — re-run +any time to converge the stack to `./config/`. For the full config reference, +architecture, and running each project standalone, see the +**[GitHub repository](https://github.com/theta42/theta-env)**. -See the [Quickstart Guide](quickstart.html) for a walkthrough of `./config/` and -what `setup.sh` does, [Architecture](architecture.html) for how the pieces fit -together, and [Standalone](standalone.html) for running each project on its own. +## Related projects ---- - -## What you get - -- **SSO Manager** at `https://` — log in as your first admin to manage - users, groups, and OAuth clients. Fronted by the proxy under TLS. -- **Proxy** at `https://` — add the Host records you want to protect - with OIDC login. -- **LDAPS** at `ldaps://:636` — legacy apps can bind directly (admin or - the read-only `cn=ldapclient` service account the bootstrap creates). -- **API tokens** — both apps let any logged-in user mint self-service personal - access tokens (`Authorization: Bearer sso_…` / `prx_…`) to drive the management - API from scripts/CI without a browser session. A token authenticates as its - creator (carrying their permissions); mint/rotate/revoke under **API Tokens** - in each UI. See each submodule's DEPLOYMENT for the details. - ---- - -## The `./config/` values you must set - -All config and secrets live in `./config/sso-secrets.js` + -`./config/proxy-secrets.js` (gitignored), generated by the first `./setup.sh`. -There is **no `.env`**. Set at least these in `./config/sso-secrets.js`: - -| Key (in `sso-secrets.js`) | What it is | -|-----|------------| -| `stack.ldapBaseDn` | Directory base, e.g. `dc=lab,dc=local`. | -| `ldap.bindPassword` | LDAP root password (generated). **Back it up.** | -| `oauth.jwtSecret` | Signs the SSO's tokens (generated). **Back it up.** | -| `stack.ssoHost` | Public hostname the proxy serves the SSO UI at. | -| `stack.proxyHost` | Public hostname the proxy serves its own mgmt UI at. | -| `bootstrap.adminUid` / `bootstrap.adminPass` | Your first admin login. | - -See `config.example/` for the full annotated shape (SMTP, LDAP cert CN, proxy -OIDC/LDAP/auth, …). - ---- - -## Architecture - -``` - ┌──────────────────────────────────────────────┐ - │ your browser / apps │ - └───────────────┬──────────────────────────────┘ - │ https - ┌─────────▼─────────┐ - │ proxy │ OpenResty :80/:443/:4443 - │ (OIDC + LDAP) │ mgmt app :3000 (localhost) - └─────────┬─────────┘ bundled redis - ┌─────────────┼──────────────────────┐ - │ ldaps:636 │ http:3001 (internal)│ OIDC token/userinfo - ▼ ▼ │ - ┌──────────────────────────┐ │ - │ sso-manager │◄────────────────┘ - │ OIDC provider + OpenLDAP │ bundled redis - │ web UI :3001 (localhost) │ - │ ldaps :636 (LAN clients) │ - └───────────────────────────┘ -``` - -The proxy is **both** an OIDC client of the SSO (for login) **and** a direct LDAP -client (for user lookups). See [Architecture](architecture.html) for the full -diagram + the first-run bootstrap flow. - ---- - -## Documentation - -- [Quickstart Guide](quickstart.html) — full walkthrough of `./config/` + `setup.sh`. -- [Architecture](architecture.html) — the 3-repo + submodule + 2-container - design, and how the bootstrap wires the proxy into a fresh SSO. -- [Standalone](standalone.html) — running SSO Manager or the proxy on its own. - ---- - -## Community - -- [GitHub Repository](https://github.com/theta42/theta-env) -- [Issue Tracker](https://github.com/theta42/theta-env/issues) - ---- - -## License - -MIT License — see the repository for details. \ No newline at end of file +- **[SSO Manager](https://theta42.github.io/sso-manager-node/)** — the OIDC + provider + LDAP directory this stack runs. +- **[Proxy](https://theta42.github.io/proxy/)** — the reverse proxy this + stack runs in front of it.