release(v2.0.2): unify component docs, bump theta-directory/proxy/jump-host (#194)
Unifies the GitHub Pages docs site: the SSO/Proxy/Jump Host pages, their
nav labels, and each component's own README now consistently say Theta
Directory / Theta Proxy / Theta Gateway, drop marketing sections ("Why this
over the alternatives", "Get it", "Related projects") that don't apply to a
suite component, remove every standalone/bare-metal install path, and link
to theta42.github.io/theta-suite/... instead of the old per-repo Pages sites.
Bumps submodules: theta-directory v2.0.2, proxy v2.0.1, jump-host v2.0.1.
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
GitHub
+3
-3
@@ -28,13 +28,13 @@ nav:
|
||||
- title: Secrets
|
||||
page: /secrets.html
|
||||
icon: fa-key
|
||||
- title: SSO Manager
|
||||
- title: Theta Directory
|
||||
page: /sso/
|
||||
icon: fa-users
|
||||
- title: Proxy
|
||||
- title: Theta Proxy
|
||||
page: /proxy/
|
||||
icon: fa-shield-halved
|
||||
- title: Jump Host
|
||||
- title: Theta Gateway
|
||||
page: /jump-host/
|
||||
icon: fa-terminal
|
||||
- title: Changelog
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
# Documentation
|
||||
|
||||
This directory is the GitHub Pages documentation site for the Jump Host project.
|
||||
|
||||
**Live site:** https://theta42.github.io/jump-host/
|
||||
|
||||
## Pages
|
||||
|
||||
- `index.md` — overview and quick start
|
||||
- `connecting.md` — usage: the username grammar, the TUI picker, SFTP/WinSCP
|
||||
- `architecture.md` — how auth, access resolution, key injection, and bridging work
|
||||
- `installation.md` — Docker, bare-metal, and theta-env install; the LDAP write-ACL
|
||||
|
||||
## Local preview
|
||||
|
||||
```bash
|
||||
gem install jekyll bundler
|
||||
cd docs && jekyll serve
|
||||
# http://localhost:4000/jump-host/
|
||||
```
|
||||
|
||||
## Updating
|
||||
|
||||
Edit the markdown, push to `master`, and GitHub Pages rebuilds automatically.
|
||||
@@ -56,8 +56,8 @@ name → IP → address hostname. A raw IP that isn't an accessible directory ho
|
||||
is refused unless explicitly allowed.
|
||||
|
||||
> The directory auto-creates `<slug>_access` / `<slug>_admin` groups for every
|
||||
> host and service (see the SSO's
|
||||
> [Directory & Inventory](https://theta42.github.io/sso-manager-node/directory.html)
|
||||
> host and service (see Theta Directory's
|
||||
> [Directory & Inventory](../sso/directory.html)
|
||||
> docs), which is exactly what this authorization reads.
|
||||
|
||||
## 3. Upstream Authentication (PKI or LDAP Keys) {#upstream-authentication}
|
||||
@@ -96,7 +96,7 @@ Byte counts per direction are tallied cheaply for the audit record.
|
||||
## Web UI, API & audit
|
||||
|
||||
An Express + EJS + Bootstrap app on `:3002` — the same front-end stack and
|
||||
look/feel as the SSO Manager and Proxy. Login is OIDC against the SSO plus a
|
||||
look/feel as Theta Directory and Theta Proxy. Login is OIDC against the SSO plus a
|
||||
local anti-lockout admin (`auth.adminUsers`), with admin access gated by
|
||||
`auth.adminGroups`. It exposes:
|
||||
|
||||
@@ -111,12 +111,12 @@ success + failure reason, downstream host-key fingerprint, timing, and bytes in/
|
||||
|
||||
## Where it sits in the stack
|
||||
|
||||
- **[SSO Manager](https://theta42.github.io/sso-manager-node/)** — provides the
|
||||
- **[Theta Directory](../sso/)** — provides the
|
||||
OpenLDAP directory (users, groups, `sshPublicKey`) and the inventory API this
|
||||
jump host reads.
|
||||
- **[ldap-client](https://github.com/theta42/ldap-client)** — enrolls the
|
||||
downstream Linux hosts (SSSD/PAM + `AuthorizedKeysCommand`) that the jump host
|
||||
connects into.
|
||||
- **[Proxy](https://theta42.github.io/proxy/)** — fronts the jump host's web UI
|
||||
- **[Theta Proxy](../proxy/)** — fronts the jump host's web UI
|
||||
under TLS.
|
||||
- **[theta-env](https://theta42.github.io/theta-env/)** — wires it all together.
|
||||
- **theta-suite** — wires it all together.
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 123 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 83 KiB After Width: | Height: | Size: 177 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 74 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 72 KiB After Width: | Height: | Size: 72 KiB |
+23
-48
@@ -1,25 +1,24 @@
|
||||
---
|
||||
layout: default
|
||||
title: Home
|
||||
description: An SSH jump host for the theta42 stack — one public host and directory-driven access to every downstream machine you're entitled to.
|
||||
description: Theta Gateway — an SSH jump host for theta-suite, giving directory-driven access to every downstream machine you're entitled to from one public host.
|
||||
---
|
||||
|
||||
# Jump Host
|
||||
# Theta Gateway
|
||||
|
||||
An SSH jump host for the [theta42](https://github.com/theta42) self-hosted
|
||||
stack. Users SSH into **one** public host and land on any downstream host
|
||||
they're entitled to — authenticated against the shared LDAP directory,
|
||||
authorized from the [SSO Manager](https://theta42.github.io/sso-manager-node/)'s
|
||||
inventory graph, and audited end to end.
|
||||
The SSH jump host component of [theta-suite](../). Users SSH into **one**
|
||||
public host and land on any downstream host they're entitled to —
|
||||
authenticated against the shared LDAP directory, authorized from
|
||||
[Theta Directory](../sso/)'s inventory graph, and audited end to end.
|
||||
|
||||
No per-host accounts, no distributing keys, no VPN. The same people who log in
|
||||
to your SSO are the people who can reach your machines — and only the machines
|
||||
their directory groups grant.
|
||||
to Theta Directory are the people who can reach your machines — and only the
|
||||
machines their directory groups grant.
|
||||
|
||||
Part of the theta42 self-hosted identity stack, alongside
|
||||
[SSO Manager](https://theta42.github.io/sso-manager-node/) and
|
||||
[Proxy](https://theta42.github.io/proxy/), composable with one command via
|
||||
[theta-env](https://theta42.github.io/theta-env/).
|
||||
Theta Gateway is deployed as part of theta-suite, alongside
|
||||
[Theta Directory](../sso/) and [Theta Proxy](../proxy/) — it isn't installed
|
||||
or run on its own. See the [Quickstart](../quickstart.html) to stand up the
|
||||
whole stack with one command.
|
||||
|
||||
## Screenshots
|
||||
|
||||
@@ -30,8 +29,6 @@ Part of the theta42 self-hosted identity stack, alongside
|
||||
|
||||
*(click any screenshot to view full size)*
|
||||
|
||||
|
||||
|
||||
## Two ways to connect
|
||||
|
||||
**Direct (WinSCP/SFTP-friendly):**
|
||||
@@ -63,17 +60,18 @@ through a single audited entry point. What's usually painful is *authorization*
|
||||
and *credentials*: who may reach which host, and how the bastion authenticates
|
||||
onward without you copying keys everywhere.
|
||||
|
||||
This jump host answers both from your directory:
|
||||
Theta Gateway answers both from your directory:
|
||||
|
||||
- **Authorization is your directory graph.** The hosts you can reach are the
|
||||
union of your LDAP groups × the SSO's inventory (the `host_<name>_access`
|
||||
groups the directory already auto-creates). Add someone to a group; they can
|
||||
reach the host. No bastion-side allow-list to maintain.
|
||||
- **Onward auth is automatic.** The jump host holds one key and injects its
|
||||
union of your LDAP groups × Theta Directory's inventory (the
|
||||
`host_<name>_access` groups the directory already auto-creates). Add
|
||||
someone to a group; they can reach the host. No bastion-side allow-list to
|
||||
maintain.
|
||||
- **Onward auth is automatic.** Theta Gateway holds one key and injects its
|
||||
public half into your `sshPublicKey` on first use, then connects downstream
|
||||
**as you**. Downstream hosts already serve keys from LDAP (via
|
||||
[ldap-client](https://github.com/theta42/ldap-client)'s
|
||||
`AuthorizedKeysCommand`), so nothing downstream needs configuring.
|
||||
ldap-client's `AuthorizedKeysCommand`), so nothing downstream needs
|
||||
configuring.
|
||||
|
||||
## Features
|
||||
|
||||
@@ -82,35 +80,12 @@ This jump host answers both from your directory:
|
||||
- **Interactive TUI host picker** on plain login, scoped to your access
|
||||
- **LDAP inbound auth** — public key or password (keys-only policy recommended
|
||||
for a public host)
|
||||
- **Directory-driven access** — reachable hosts come from the SSO inventory, not
|
||||
a static list
|
||||
- **Directory-driven access** — reachable hosts come from the Theta Directory
|
||||
inventory, not a static list
|
||||
- **Per-user key injection** — no downstream changes, no key distribution
|
||||
- **Shell, exec, and SFTP** bridging
|
||||
- **WireGuard mesh routing** — cross-site network access alongside SSH
|
||||
- **Web UI + HTTP API** for auditing and metrics — active sessions, a searchable
|
||||
audit log, per-user/per-host counters
|
||||
- **Full audit trail** — who, target, method, result, bytes, duration, and the
|
||||
downstream host-key fingerprint
|
||||
|
||||
- Packaged like the rest of the stack: one-command Docker, idempotent bare-metal
|
||||
installer, or bundled in theta-env
|
||||
|
||||
## Get it
|
||||
|
||||
```bash
|
||||
git clone https://github.com/theta42/jump-host.git
|
||||
cd jump-host
|
||||
cp secrets.js.example config/jump-secrets.js # then edit it
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
For bare-metal and the bundled theta-env
|
||||
option, see **[Installation](installation.html)**.
|
||||
|
||||
## Related projects
|
||||
|
||||
- **[SSO Manager](https://theta42.github.io/sso-manager-node/)** — the OpenLDAP
|
||||
directory + OIDC provider + the inventory graph this jump host reads.
|
||||
- **[Proxy](https://theta42.github.io/proxy/)** — puts your web apps behind the
|
||||
same identity; fronts this jump host's web UI.
|
||||
- **[theta-env](https://theta42.github.io/theta-env/)** — runs the whole stack,
|
||||
jump host included, with one command.
|
||||
|
||||
@@ -1,39 +0,0 @@
|
||||
# Documentation
|
||||
|
||||
This directory contains the GitHub Pages documentation site for the Proxy project.
|
||||
|
||||
**Live site:** https://theta42.github.io/proxy/
|
||||
|
||||
## Pages
|
||||
|
||||
- `index.md` - Home page with project overview
|
||||
- `installation.md` - Installation and setup guide
|
||||
- `api.md` - Complete API reference
|
||||
- `architecture.md` - System architecture and design
|
||||
- `contributing.md` - Development and contribution guide
|
||||
|
||||
## Local Preview
|
||||
|
||||
To preview the site locally:
|
||||
|
||||
```bash
|
||||
# Install Jekyll (one-time setup)
|
||||
gem install jekyll bundler
|
||||
|
||||
# Run local server
|
||||
cd docs
|
||||
jekyll serve
|
||||
|
||||
# View at http://localhost:4000/proxy/
|
||||
```
|
||||
|
||||
## Theme
|
||||
|
||||
The site uses the Cayman theme (`jekyll-theme-cayman`). Configuration is in `_config.yml`.
|
||||
|
||||
## Updating Documentation
|
||||
|
||||
1. Edit markdown files in this directory
|
||||
2. Commit and push to master branch
|
||||
3. GitHub Pages automatically rebuilds (may take 1-2 minutes)
|
||||
4. Changes visible at https://theta42.github.io/proxy/
|
||||
@@ -22,7 +22,7 @@ There are two ways someone gets into the proxy's own management UI:
|
||||
|
||||
- **A local account**, created on the **Users** page — a username and
|
||||
password specific to this app.
|
||||
- **Single sign-on**, if you've connected this proxy to an SSO Manager (or
|
||||
- **Single sign-on**, if you've connected this proxy to Theta Directory (or
|
||||
another OIDC provider) — the same login your other connected apps use.
|
||||
|
||||
Either way, once logged in, what they're actually *allowed to do* here is
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 328 KiB After Width: | Height: | Size: 345 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 326 KiB After Width: | Height: | Size: 376 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 310 KiB After Width: | Height: | Size: 506 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 428 KiB After Width: | Height: | Size: 440 KiB |
+15
-42
@@ -1,24 +1,24 @@
|
||||
---
|
||||
layout: default
|
||||
title: Home
|
||||
description: A reverse proxy and HTTPS termination service built on OpenResty/nginx, with automatic Let's Encrypt certs, OIDC login, and direct LDAP access control per host.
|
||||
description: Theta Proxy — a reverse proxy and HTTPS termination service built on OpenResty/nginx, with automatic Let's Encrypt certs, OIDC login, and direct LDAP access control per host.
|
||||
---
|
||||
|
||||
# Proxy
|
||||
# Theta Proxy
|
||||
|
||||
A reverse proxy and HTTPS termination service built on OpenResty/nginx, with a
|
||||
management API and web GUI. It puts any of your apps behind single sign-on
|
||||
(OIDC) and can also look users up directly in LDAP — so the same people who
|
||||
log in to your SSO are the people allowed to reach your proxied apps.
|
||||
The reverse proxy and HTTPS termination component of [theta-suite](../), built
|
||||
on OpenResty/nginx. It puts any of your apps behind single sign-on (OIDC) and
|
||||
can also look users up directly in LDAP — so the same people who log in to
|
||||
[Theta Directory](../sso/) are the people allowed to reach your proxied apps.
|
||||
|
||||
Automatic HTTPS from Let's Encrypt (including wildcards), routing by hostname,
|
||||
and per-host access control tied to your identity provider — managed from a
|
||||
web UI or a REST API, with no downtime on config changes.
|
||||
|
||||
Part of the theta42 self-hosted identity stack, alongside
|
||||
[SSO Manager](https://theta42.github.io/sso-manager-node/) and
|
||||
[theta-env](https://theta42.github.io/theta-env/) (the two composed with one
|
||||
command).
|
||||
Theta Proxy is deployed as part of theta-suite, alongside
|
||||
[Theta Directory](../sso/) and [Theta Gateway](../jump-host/) — it isn't
|
||||
installed or run on its own. See the [Quickstart](../quickstart.html) to stand
|
||||
up the whole stack with one command.
|
||||
|
||||
## Screenshots
|
||||
|
||||
@@ -30,49 +30,22 @@ management once basic auth is enabled:
|
||||
|
||||
<a href="images/host-auth-basic.png" target="_blank"><img src="images/host-auth-basic.png" alt="Per-host basic auth" width="60%"></a>
|
||||
|
||||
Multiple backend targets per host, load balanced round-robin:
|
||||
|
||||
<a href="images/load-balancing.png" target="_blank"><img src="images/load-balancing.png" alt="Load balancing" width="60%"></a>
|
||||
|
||||
*(click any screenshot to view full size)*
|
||||
|
||||
## Why this over the alternatives
|
||||
|
||||
Nginx Proxy Manager, Traefik, and Caddy are all good reverse proxies with
|
||||
auto-HTTPS. This one is built around identity: it is both an **OIDC client**
|
||||
of an SSO provider (for browser login) **and** a direct **LDAP client** (for
|
||||
user lookups and per-host access control), so access decisions come from your
|
||||
real user directory, not a static allow-list or a separate auth proxy bolted
|
||||
on top. The trade-off is that it expects an OIDC/LDAP identity source to point
|
||||
at — it is not an auth server on its own. Pair it with
|
||||
[SSO Manager](https://theta42.github.io/sso-manager-node/) (bundled OpenLDAP +
|
||||
OIDC) for a self-hosted SSO + proxy stack, or point it at any OIDC provider +
|
||||
LDAP directory you already run.
|
||||
|
||||
## Features
|
||||
|
||||
- Automated HTTPS via Let's Encrypt — HTTP-01 and DNS-01 (wildcard) challenges
|
||||
- Multiple DNS providers (Cloudflare, DigitalOcean, PorkBun, DuckDNS — free)
|
||||
- Dynamic host routing with wildcard domain matching (`*`, `**`)
|
||||
- **Multi-target load balancing** — configure multiple backend targets per host with built-in round-robin load balancing
|
||||
- **OIDC login** and **direct LDAP lookups**, independently of each other
|
||||
- **OIDC login** and **direct LDAP lookups**, independently of each other, against [Theta Directory](../sso/)
|
||||
- Per-host **basic auth** as an alternative to SSO (mutually exclusive, so
|
||||
it's never ambiguous which one gated a request)
|
||||
- **Role-based access control** — global admins, local groups, and
|
||||
per-domain permissions (viewer/manager)
|
||||
- Self-service API tokens for scripting/CI without a browser session
|
||||
- Web UI and a full REST API
|
||||
|
||||
## Get it
|
||||
|
||||
```bash
|
||||
git clone https://github.com/theta42/proxy.git
|
||||
cd proxy && docker compose up -d --build
|
||||
```
|
||||
|
||||
For the full set of install options (Docker, bare-metal, or as part of the combined
|
||||
SSO + proxy stack), configuration reference, and API docs, see the
|
||||
**[GitHub repository](https://github.com/theta42/proxy)**.
|
||||
|
||||
## Related projects
|
||||
|
||||
- **[SSO Manager](https://theta42.github.io/sso-manager-node/)** — the OIDC
|
||||
provider + LDAP directory this proxy is designed to sit in front of.
|
||||
- **[theta-env](https://theta42.github.io/theta-env/)** — runs this proxy and
|
||||
SSO Manager together with one command.
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@ nav_order: 5
|
||||
|
||||
# Discovery Agents
|
||||
|
||||
The SSO Manager supports a robust agent architecture for auto-discovering devices, hosts, and services across your home lab or data center. Agents run on a scheduled cron and feed their data into a central **Reconciliation Engine** that smartly merges information based on MAC addresses and IPs.
|
||||
Theta Directory supports a robust agent architecture for auto-discovering devices, hosts, and services across your home lab or data center. Agents run on a scheduled cron and feed their data into a central **Reconciliation Engine** that smartly merges information based on MAC addresses and IPs.
|
||||
|
||||
## Writing a Custom Agent
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Accounts, Groups & Managers
|
||||
description: A plain-language guide to users, service accounts, personal groups, and managers in SSO Manager.
|
||||
description: A plain-language guide to users, service accounts, personal groups, and managers in Theta Directory.
|
||||
---
|
||||
|
||||
# Accounts, Groups & Managers
|
||||
@@ -12,7 +12,7 @@ see the [LDAP reference](ldap.html).
|
||||
|
||||
## What's an account?
|
||||
|
||||
Every person (or app) that can sign in through this SSO Manager has an
|
||||
Every person (or app) that can sign in through Theta Directory has an
|
||||
**account** — a username, a display name, maybe an email address, and a
|
||||
password (or, for service accounts, no password at all — see below).
|
||||
Accounts live in the directory this app manages, and any other app you've
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: API Tokens
|
||||
description: A plain-language guide to personal access tokens in SSO Manager.
|
||||
description: A plain-language guide to personal access tokens in Theta Directory.
|
||||
---
|
||||
|
||||
# API Tokens
|
||||
|
||||
@@ -1,20 +1,20 @@
|
||||
---
|
||||
layout: default
|
||||
title: Connecting Apps (Single Sign-On)
|
||||
description: A plain-language guide to OAuth/OIDC clients and single sign-on in SSO Manager.
|
||||
description: A plain-language guide to OAuth/OIDC clients and single sign-on in Theta Directory.
|
||||
---
|
||||
|
||||
# Connecting Apps (Single Sign-On)
|
||||
|
||||
This page explains, in plain language, what happens when you "connect" an
|
||||
app to your SSO Manager so people can log into it with their existing
|
||||
app to Theta Directory so people can log into it with their existing
|
||||
account. For the technical endpoint/token detail, see the
|
||||
[OAuth reference](oauth.html).
|
||||
|
||||
## What does "single sign-on" actually mean?
|
||||
|
||||
Instead of every app you run having its own separate list of usernames and
|
||||
passwords, they all check with this SSO Manager instead. You log in once,
|
||||
passwords, they all check with Theta Directory instead. You log in once,
|
||||
here, and any connected app trusts that login — no separate password to
|
||||
remember or manage for each one. If you ever need to lock someone out
|
||||
everywhere at once, you do it in one place (deactivate their account here)
|
||||
@@ -33,11 +33,11 @@ gives you a **Client ID** and **Client Secret**: think of these like a
|
||||
username and password, but for the *app itself* rather than for a person.
|
||||
You paste them into the other app's own "Single Sign-On" or "OIDC" setup
|
||||
screen, along with the discovery URL shown at the top of this page, and
|
||||
that app is now able to ask this SSO Manager to authenticate people on its
|
||||
that app is now able to ask Theta Directory to authenticate people on its
|
||||
behalf.
|
||||
|
||||
**Treat the Client Secret like a password** — anyone who has it can
|
||||
impersonate that app when talking to your SSO Manager. If you ever suspect
|
||||
impersonate that app when talking to Theta Directory. If you ever suspect
|
||||
it's leaked, rotate it from the client's card.
|
||||
|
||||
## What are "scopes"?
|
||||
@@ -50,13 +50,13 @@ setup instructions; when in doubt, the default set (`openid`, `profile`,
|
||||
|
||||
## "Restrict to Groups"
|
||||
|
||||
By default, *any* account with an SSO Manager login can sign into a
|
||||
By default, *any* account with a Theta Directory login can sign into a
|
||||
connected app. If that's not what you want — say, a home automation
|
||||
dashboard that only certain family members should reach — set **Restrict
|
||||
to Groups** on that client to one of your [groups](concepts-accounts.html).
|
||||
Only members of that group will be allowed to log into that particular
|
||||
app; everyone else gets turned away at the login step, even though their
|
||||
SSO Manager account still works everywhere else.
|
||||
Theta Directory account still works everywhere else.
|
||||
|
||||
## Redirect URIs
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Configuration
|
||||
description: SSO Manager's config layers — conf/base.js defaults, secrets.js overrides, and app_* environment variables.
|
||||
description: Theta Directory's config layers — conf/base.js defaults, secrets.js overrides, and app_* environment variables.
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
@@ -6,7 +6,7 @@ description: Managing your Home-Lab infrastructure, services, and LDAP access re
|
||||
|
||||
# Directory Management
|
||||
|
||||
The SSO Manager ships with a built-in **Directory & Inventory Management** feature. Instead of just managing bare LDAP groups for your homelab, the Directory allows you to map out your infrastructure graph and assign rich metadata to your services.
|
||||
Theta Directory ships with a built-in **Directory & Inventory Management** feature. Instead of just managing bare LDAP groups for your homelab, the Directory allows you to map out your infrastructure graph and assign rich metadata to your services.
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -18,11 +18,11 @@ There are three primary **Kinds** of resources you can define:
|
||||
- **Service (App)**: An application, web service. A Service **must** have a parent Host or another Service.
|
||||
- **OAuth Integration**: An OAuth 2.0 / OpenID Connect client application. An OAuth integration **must** have a parent Service.
|
||||
|
||||
By defining this hierarchy, the SSO Manager builds a queryable graph of your infrastructure.
|
||||
By defining this hierarchy, Theta Directory builds a queryable graph of your infrastructure.
|
||||
|
||||
## Automatic LDAP Group Creation
|
||||
|
||||
When you create a new **Host** or **Service** in the Directory via the web UI (or API), the SSO Manager will automatically provision two LDAP groups in your directory to govern access to that resource:
|
||||
When you create a new **Host** or **Service** in the Directory via the web UI (or API), Theta Directory will automatically provision two LDAP groups in your directory to govern access to that resource:
|
||||
|
||||
1. `<slug>_access` (Member level access)
|
||||
2. `<slug>_admin` (Owner level access)
|
||||
@@ -84,7 +84,7 @@ The Directory Management interface provides a **Tree View** toggle that visually
|
||||
|
||||
## Slug conventions
|
||||
|
||||
Slugs are the stable identifiers automation keys off, so the tooling around the SSO Manager follows a shared convention:
|
||||
Slugs are the stable identifiers automation keys off, so the tooling around Theta Directory follows a shared convention:
|
||||
|
||||
- **Sites**: `site_<name>` — e.g. `site_local`, `site_us-east`
|
||||
- **Hosts**: `host_<hostname>` — e.g. `host_pve1`, `host_web01`
|
||||
@@ -102,7 +102,7 @@ You don't have to build the graph by hand — the theta42 tooling registers itse
|
||||
|
||||
- a **site** (name from `CFG_SITE_NAME` in `setup.env`, default `local` → slug `site_local`) marked as the current site
|
||||
- the **host** the stack runs on (`host_<hostname>`), with IP, MAC address, OS, and kernel collected from the machine
|
||||
- the **services** it composes — SSO Manager, Proxy (management UI), OpenLDAP Directory (the LDAPS endpoint Linux hosts and LDAP-native apps bind to), and OpenResty Edge (the 80/443 data plane) — each with its address, internal port, and git repo
|
||||
- the **services** it composes — Theta Directory, Proxy (management UI), OpenLDAP Directory (the LDAPS endpoint Linux hosts and LDAP-native apps bind to), and OpenResty Edge (the 80/443 data plane) — each with its address, internal port, and git repo
|
||||
- the proxy's auto-registered **OAuth client**, linked under its service
|
||||
|
||||
The seed is idempotent and non-destructive: a resource whose slug already exists is considered operator-owned — the seed only fills in metadata fields you haven't set, and never overwrites your values.
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 401 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 430 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 141 KiB After Width: | Height: | Size: 332 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 392 KiB After Width: | Height: | Size: 503 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 430 KiB After Width: | Height: | Size: 119 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 313 KiB After Width: | Height: | Size: 358 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 221 KiB After Width: | Height: | Size: 320 KiB |
+18
-52
@@ -1,24 +1,25 @@
|
||||
---
|
||||
layout: default
|
||||
title: Home
|
||||
description: A self-hosted OpenID Connect provider with a bundled OpenLDAP directory and a web management UI. One login for your modern apps, one LDAP directory for the rest, no phone-home.
|
||||
description: Theta Directory — the OpenID Connect provider, bundled OpenLDAP directory, and resource inventory at the core of theta-suite. One login for your modern apps, one LDAP directory for the rest, no phone-home.
|
||||
---
|
||||
|
||||
# SSO Manager
|
||||
# Theta Directory
|
||||
|
||||
A self-hosted **OpenID Connect provider** with a bundled **OpenLDAP directory**
|
||||
and a web management UI — for home labs and small businesses that want their
|
||||
own identity provider instead of a hosted one.
|
||||
The identity and directory component of [theta-suite](../): an **OpenID
|
||||
Connect provider**, a bundled **OpenLDAP directory**, and a **resource
|
||||
inventory & IAM engine**, all behind one web console.
|
||||
|
||||
One place to manage your users and groups, one login (OIDC) your modern apps
|
||||
can use, and one LDAP directory your older or odder apps can bind to directly.
|
||||
Everything runs on your own hardware; no phone-home, no hosted control plane,
|
||||
no per-user pricing.
|
||||
can use, and one LDAP directory your older or odder apps can bind to directly
|
||||
— plus a graph of every site, host, and service you run, with auto-provisioned
|
||||
access groups. Everything runs on your own hardware; no phone-home, no hosted
|
||||
control plane, no per-user pricing.
|
||||
|
||||
Part of the theta42 self-hosted identity stack, alongside
|
||||
[Proxy](https://theta42.github.io/proxy/) (an OIDC + LDAP-aware reverse proxy)
|
||||
and [theta-env](https://theta42.github.io/theta-env/) (the two composed with
|
||||
one command).
|
||||
Theta Directory is deployed as part of theta-suite, alongside
|
||||
[Proxy](../proxy/) and [Jump Host](../jump-host/) — it isn't installed or run
|
||||
on its own. See the [Quickstart](../quickstart.html) to stand up the whole
|
||||
stack with one command.
|
||||
|
||||
## Screenshots
|
||||
|
||||
@@ -27,23 +28,11 @@ one command).
|
||||
<a href="images/groups.png" target="_blank"><img src="images/groups.png" alt="Groups" width="49%"></a>
|
||||
<a href="images/directory.png" target="_blank"><img src="images/directory.png" alt="Directory & inventory" width="49%"></a>
|
||||
<a href="images/oauth-clients.png" target="_blank"><img src="images/oauth-clients.png" alt="OAuth client (edit view)" width="49%"></a>
|
||||
<a href="images/agent-capabilities-metrics.png" target="_blank"><img src="images/agent-capabilities-metrics.png" alt="Agent capabilities & metrics" width="49%"></a>
|
||||
<a href="images/agent-install-join-key.png" target="_blank"><img src="images/agent-install-join-key.png" alt="Agent install with join key" width="49%"></a>
|
||||
|
||||
*(click any screenshot to view full size)*
|
||||
|
||||
## Why this over the alternatives
|
||||
|
||||
Tools like Keycloak, Authentik, Authelia, or Zitadel are OIDC providers, but
|
||||
LDAP is either a paid feature, a federation target you have to run
|
||||
separately, or absent. If your stack already has apps that speak LDAP
|
||||
directly — or you just want one real directory as the source of truth — you
|
||||
end up running *two* identity systems and keeping them in sync.
|
||||
|
||||
SSO Manager bundles the OpenLDAP directory with the OIDC provider, so OIDC
|
||||
apps and LDAP apps read from the same users and groups. The trade-off is
|
||||
scope: it's intentionally small and self-hosted, not an enterprise IAM suite.
|
||||
If you want a lightweight, self-contained identity provider with a real LDAP
|
||||
backend, that's the niche.
|
||||
|
||||
## Features
|
||||
|
||||
- **OpenID Connect / OAuth 2.0 provider** — your own access/refresh/ID
|
||||
@@ -56,30 +45,7 @@ backend, that's the niche.
|
||||
- **Direct LDAP binds** — anything that binds LDAP directly (Linux hosts
|
||||
via PAM/SSSD, Gitea, Emby, …) uses LDAPS/StartTLS against the same
|
||||
directory.
|
||||
- **All-in-one Docker image** — app + OpenLDAP + Redis in one container, or
|
||||
run the pieces separately via `app_*` env config.
|
||||
- **Geo-Location Scaling** — built-in support for N-Way Multi-Master OpenLDAP [replication](replication.html) across physical sites.
|
||||
- **[Directory & Inventory](directory.html)** — map sites, hosts, and services as a graph with rich metadata (IP/MAC, OS/kernel, ports, git repos), auto-provisioned access groups, and automatic registration from theta-env and ldap-client. Drives directory-aware tools like the [SSH jump host](https://theta42.github.io/jump-host/).
|
||||
|
||||
## Get it
|
||||
|
||||
```bash
|
||||
git clone https://github.com/theta42/sso-manager-node.git
|
||||
cd sso-manager-node
|
||||
cp secrets.js.example nodejs/conf/secrets.js # edit it, or use app_* env
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
For the full set of install options
|
||||
(Docker, bare-metal, or as part of the combined SSO + proxy stack), the
|
||||
`app_*` env reference, and the OAuth/LDAP internals, see the
|
||||
**[GitHub repository](https://github.com/theta42/sso-manager-node)**.
|
||||
|
||||
## Related projects
|
||||
|
||||
- **[Proxy](https://theta42.github.io/proxy/)** — an OIDC + LDAP-aware
|
||||
reverse proxy, designed to sit in front of this SSO.
|
||||
- **[Jump Host](https://theta42.github.io/jump-host/)** — an SSH jump host that
|
||||
uses this SSO's directory to decide who may reach which machine.
|
||||
- **[theta-env](https://theta42.github.io/theta-env/)** — runs this SSO
|
||||
Manager and the proxy together with one command.
|
||||
- **[Directory & Inventory](directory.html)** — map sites, hosts, and services as a graph with rich metadata (IP/MAC, OS/kernel, ports, git repos), auto-provisioned access groups, and automatic registration from theta-suite's agents and discovery plugins. Drives directory-aware tools like the [SSH jump host](../jump-host/).
|
||||
- **Subtype metrics & lifecycle drivers** — telemetry, log streaming, and remote control for resources tagged with a `subType` (`systemd`, `docker`, `proxmox`, `wireguard`, `postgresql`, `redis`, `k8s`, …).
|
||||
- **OpenBao-backed secrets** — per-resource and per-user secrets with explicit upward inheritance (`Resource → Host → Cluster → Site`).
|
||||
|
||||
+4
-4
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: LDAP
|
||||
description: SSO Manager's bundled OpenLDAP directory — schema, service accounts, TLS, and connecting third-party apps directly.
|
||||
description: Theta Directory's bundled OpenLDAP directory — schema, service accounts, TLS, and connecting third-party apps directly.
|
||||
---
|
||||
|
||||
# LDAP Directory
|
||||
@@ -12,7 +12,7 @@ description: SSO Manager's bundled OpenLDAP directory — schema, service accoun
|
||||
> instead of schema/attribute detail? See
|
||||
> [Accounts, Groups & Managers](concepts-accounts.html).
|
||||
|
||||
SSO Manager runs an OpenLDAP directory holding your users and groups. The app
|
||||
Theta Directory runs an OpenLDAP directory holding your users and groups. The app
|
||||
authenticates against it over `localhost:389` (inside the all-in-one container)
|
||||
and exposes **LDAPS** (`ldaps://…:636`, TLS) for anything that binds LDAP
|
||||
directly — Linux hosts (PAM/SSSD, sudo rules, SSH keys), Gitea, Emby, the
|
||||
@@ -167,8 +167,8 @@ internal-only patterns and set `conf.ldap.ldapsHost` (or
|
||||
|
||||
### 1. Same Docker / local network host (best for apps on this machine)
|
||||
|
||||
If the LDAP client runs on the same Docker network as the SSO Manager (for
|
||||
example, the bundled `theta-env` stack), use the internal service name:
|
||||
If the LDAP client runs on the same Docker network as Theta Directory (for
|
||||
example, the bundled `theta-suite` stack), use the internal service name:
|
||||
|
||||
```
|
||||
ldaps://sso-manager:636
|
||||
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: OAuth / OIDC
|
||||
description: SSO Manager's OpenID Connect / OAuth 2.0 provider — discovery document, client registration, and token endpoints.
|
||||
description: Theta Directory's OpenID Connect / OAuth 2.0 provider — discovery document, client registration, and token endpoints.
|
||||
---
|
||||
|
||||
# OAuth 2.0 / OpenID Connect
|
||||
@@ -12,7 +12,7 @@ description: SSO Manager's OpenID Connect / OAuth 2.0 provider — discovery doc
|
||||
> of endpoint-level detail? See
|
||||
> [Connecting Apps (Single Sign-On)](concepts-oauth-apps.html).
|
||||
|
||||
SSO Manager is an **OpenID Connect / OAuth 2.0 provider**: it issues its own
|
||||
Theta Directory is an **OpenID Connect / OAuth 2.0 provider**: it issues its own
|
||||
access, refresh, and ID tokens that your apps can consume to authenticate
|
||||
users and authorize API calls. It also runs a full OpenLDAP directory, so it
|
||||
can be both your SSO and your user directory at once.
|
||||
|
||||
@@ -5,7 +5,7 @@ title: Geo-Location Scaling (Replication)
|
||||
|
||||
# Geo-Location Scaling (Replication)
|
||||
|
||||
SSO Manager is built to be a self-contained identity provider, but if you have multiple physical sites, you may want a local copy of the directory at each site to ensure low latency and high availability.
|
||||
Theta Directory bundles its own identity provider, but if you have multiple physical sites, you may want a local copy of the directory at each site to ensure low latency and high availability.
|
||||
|
||||
## Why and when to use this?
|
||||
- **High Availability (HA)**: If your primary site goes completely offline, your other sites can still authenticate users locally without depending on a WAN link.
|
||||
|
||||
+7
-7
@@ -6,9 +6,9 @@ nav_order: 6
|
||||
|
||||
# Secrets Vault
|
||||
|
||||
SSO Manager integrates natively with **OpenBao** (a Vault fork) to securely manage and store sensitive data, configuration, and API keys.
|
||||
Theta Directory integrates natively with **OpenBao** (a Vault fork) to securely manage and store sensitive data, configuration, and API keys.
|
||||
|
||||
The Vault proxy endpoint is exposed directly through SSO Manager at `/api/vault/v1/`, which safely authenticates and authorizes requests before forwarding them to the internal OpenBao container.
|
||||
The Vault proxy endpoint is exposed directly through Theta Directory at `/api/vault/v1/`, which safely authenticates and authorizes requests before forwarding them to the internal OpenBao container.
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -18,10 +18,10 @@ When the environment is initialized via `setup.sh`, OpenBao is automatically uns
|
||||
|
||||
## Accessing the Vault
|
||||
|
||||
The SSO Manager Vault can be accessed in two ways:
|
||||
The Theta Directory Vault can be accessed in two ways:
|
||||
|
||||
1. **Via the SSO Manager UI**: Go to the **Admin Configuration** page (`/conf`) to edit the application's configuration secrets directly. SMTP and OAuth settings are edited through structured form fields (not a raw JSON blob) and saved to OpenBao at `secret/sso-manager/conf` at runtime, taking effect immediately. Secret fields — the SMTP password and the OAuth JWT secret — are returned masked (`********`); leave the field unchanged (or blank) to keep the stored value, or enter a new value to replace it.
|
||||
2. **Via the REST API**: Send requests to `/api/vault/v1/...` with your SSO Manager session or API Token.
|
||||
1. **Via the Theta Directory UI**: Go to the **Admin Configuration** page (`/conf`) to edit the application's configuration secrets directly. SMTP and OAuth settings are edited through structured form fields (not a raw JSON blob) and saved to OpenBao at `secret/sso-manager/conf` at runtime, taking effect immediately. Secret fields — the SMTP password and the OAuth JWT secret — are returned masked (`********`); leave the field unchanged (or blank) to keep the stored value, or enter a new value to replace it.
|
||||
2. **Via the REST API**: Send requests to `/api/vault/v1/...` with your Theta Directory session or API Token.
|
||||
|
||||
### API Example
|
||||
|
||||
@@ -32,14 +32,14 @@ Only administrators with `app_sso_admin` or `admin` permissions can query the va
|
||||
|
||||
## Namespaces and Paths
|
||||
|
||||
Currently, secrets are maintained at `/v1/secret/data/sso-manager/conf` using the `kv-v2` backend. When configurations are edited via the admin UI, SSO Manager performs a deep-merge so that partial updates don't overwrite unrelated keys (such as SMTP vs OAuth configurations).
|
||||
Currently, secrets are maintained at `/v1/secret/data/sso-manager/conf` using the `kv-v2` backend. When configurations are edited via the admin UI, Theta Directory performs a deep-merge so that partial updates don't overwrite unrelated keys (such as SMTP vs OAuth configurations).
|
||||
|
||||
## Plugin Integration
|
||||
|
||||
Plugin instances store their per-instance secrets in OpenBao at
|
||||
`secret/plugins/<instance-id>/conf` (configured, loaded/unloaded, and run from
|
||||
the **Plugins** page — see [Plugins](plugins.html)). The plugin process runs
|
||||
in-process, so the SSO Manager reads/writes those secrets server-side through
|
||||
in-process, so Theta Directory reads/writes those secrets server-side through
|
||||
the `sso-broker` token; the admin UI only ever sees masked values, and external
|
||||
apps can retrieve API tokens via the `/api/vault` proxy to keep permissions
|
||||
consistently enforced instead of hardcoding them.
|
||||
|
||||
Reference in New Issue
Block a user