feat: Protocol v1.1.0 theta-agent C2 integration, agent install wizard, OpenBao 403 fix, nmap discovery fix, and restored documentation
This commit is contained in:
@@ -0,0 +1,55 @@
|
||||
title: SSO Manager
|
||||
description: 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.
|
||||
url: "https://theta42.github.io"
|
||||
baseurl: "/sso-manager-node"
|
||||
logo: /assets/img/theta42.svg
|
||||
lang: en_US
|
||||
|
||||
plugins:
|
||||
- jekyll-seo-tag
|
||||
- jekyll-sitemap
|
||||
|
||||
github:
|
||||
repository_url: https://github.com/theta42/sso-manager-node
|
||||
zip_url: https://github.com/theta42/sso-manager-node/archive/refs/heads/master.zip
|
||||
tar_url: https://github.com/theta42/sso-manager-node/archive/refs/heads/master.tar.gz
|
||||
repository_name: theta42/sso-manager-node
|
||||
|
||||
nav:
|
||||
- title: Home
|
||||
page: /
|
||||
icon: fa-house
|
||||
- title: Deployment
|
||||
page: /deployment.html
|
||||
icon: fa-server
|
||||
- title: Configuration
|
||||
page: /configuration.html
|
||||
icon: fa-gears
|
||||
- title: OAuth
|
||||
page: /oauth.html
|
||||
icon: fa-key
|
||||
- title: LDAP
|
||||
page: /ldap.html
|
||||
icon: fa-address-book
|
||||
- title: Directory
|
||||
page: /directory.html
|
||||
icon: fa-server
|
||||
- title: Plugins
|
||||
page: /plugins.html
|
||||
icon: fa-plug
|
||||
# API.md lives at the repo root, not under docs/, so Jekyll never renders an
|
||||
# api.html for it — link the source directly, same as the Changelog.
|
||||
- title: API
|
||||
url: https://github.com/theta42/sso-manager-node/blob/master/API.md
|
||||
icon: fa-code
|
||||
- title: Changelog
|
||||
url: https://github.com/theta42/sso-manager-node/blob/master/CHANGELOG.md
|
||||
icon: fa-list
|
||||
|
||||
defaults:
|
||||
- scope:
|
||||
path: ""
|
||||
type: "pages"
|
||||
values:
|
||||
layout: default
|
||||
image: /assets/img/theta42.svg
|
||||
@@ -0,0 +1,82 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
|
||||
<link rel="icon" type="image/svg+xml" href="{{ '/assets/img/theta42.svg' | relative_url }}">
|
||||
|
||||
{% seo title=false %}
|
||||
<title>{% if page.title %}{{ page.title }} · {% endif %}{{ site.title }}</title>
|
||||
|
||||
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css">
|
||||
<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
|
||||
</head>
|
||||
<body class="d-flex flex-column min-vh-100">
|
||||
|
||||
<nav class="navbar navbar-expand-md navbar-dark bg-dark fixed-top">
|
||||
<div class="container-fluid px-3">
|
||||
<a class="navbar-brand d-flex align-items-center" href="{{ '/' | relative_url }}">
|
||||
<img src="{{ '/assets/img/theta42.svg' | relative_url }}" height="28" class="me-2" alt="">
|
||||
{{ site.title }}
|
||||
</a>
|
||||
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navMain" aria-controls="navMain" aria-expanded="false" aria-label="Toggle navigation">
|
||||
<span class="navbar-toggler-icon"></span>
|
||||
</button>
|
||||
<div class="collapse navbar-collapse justify-content-end" id="navMain">
|
||||
<ul class="navbar-nav">
|
||||
{% for item in site.nav %}
|
||||
<li class="nav-item">
|
||||
{% if item.page %}
|
||||
<a class="nav-link{% if page.url == item.page %} active{% endif %}" href="{{ item.page | relative_url }}">
|
||||
{% if item.icon %}<i class="fa-solid {{ item.icon }}"></i>{% endif %} {{ item.title }}
|
||||
</a>
|
||||
{% else %}
|
||||
<a class="nav-link" href="{{ item.url }}" target="_blank" rel="noopener">
|
||||
{% if item.icon %}<i class="fa-solid {{ item.icon }}"></i>{% endif %} {{ item.title }}
|
||||
</a>
|
||||
{% endif %}
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<main class="flex-grow-1" style="margin-top: 4.5rem;">
|
||||
<div class="container-fluid py-4 py-md-5">
|
||||
<div class="row justify-content-center">
|
||||
<div class="col-12 col-lg-10 col-xl-8">
|
||||
<div class="card shadow-lg">
|
||||
<div class="card-body p-4 p-md-5 site-content">
|
||||
{{ content }}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
<footer class="py-3 bg-dark text-light mt-auto">
|
||||
<div class="container-fluid d-flex flex-wrap justify-content-between align-items-center small gap-2 px-3">
|
||||
<span class="d-flex align-items-center gap-2">
|
||||
<a href="https://theta42.com" target="_blank" rel="noopener">
|
||||
<img width="40" src="{{ '/assets/img/theta42.svg' | relative_url }}" alt="theta42">
|
||||
</a>
|
||||
© {{ 'now' | date: '%Y' }} theta42 ·
|
||||
<a href="{{ site.github.repository_url }}/blob/master/LICENSE" target="_blank" rel="noopener" class="text-light">MIT License</a>
|
||||
</span>
|
||||
<span class="d-flex align-items-center gap-3">
|
||||
<a href="{{ site.github.repository_url }}" target="_blank" rel="noopener" class="text-light text-decoration-none">
|
||||
<i class="fa-brands fa-github"></i> GitHub
|
||||
</a>
|
||||
<a href="{{ site.github.repository_url }}/blob/master/CHANGELOG.md" target="_blank" rel="noopener" class="text-light text-decoration-none">
|
||||
<i class="fa-solid fa-list"></i> Changelog
|
||||
</a>
|
||||
</span>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
layout: default
|
||||
title: Discovery Agents
|
||||
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.
|
||||
|
||||
## Writing a Custom Agent
|
||||
|
||||
Agents are simple JavaScript files placed in `nodejs/agents/discovery/`.
|
||||
|
||||
A agent must export a single `discover` async function that returns a standardized graph of `resources` and `edges`.
|
||||
|
||||
### Agent Skeleton
|
||||
|
||||
```javascript
|
||||
// nodejs/agents/discovery/my_custom_agent.js
|
||||
module.exports = {
|
||||
discover: async (config) => {
|
||||
const { url, apiKey } = config; // Provided by your configuration
|
||||
|
||||
const resources = [];
|
||||
const edges = [];
|
||||
|
||||
// 1. Fetch your data from an API
|
||||
// const data = await fetch(...);
|
||||
|
||||
// 2. Map data to Resources
|
||||
resources.push({
|
||||
kind: 'network_device', // 'host', 'service', 'network_device', 'unmanaged_device'
|
||||
name: 'My Switch',
|
||||
slug: 'my-switch-01',
|
||||
metadata: {
|
||||
make: 'Vendor',
|
||||
model: 'Model X',
|
||||
interfaces: [
|
||||
{ mac: '00:1A:2B:3C:4D:5E', ip: '10.0.0.5' }
|
||||
]
|
||||
}
|
||||
});
|
||||
|
||||
// 3. Map relations to Edges (optional)
|
||||
edges.push({
|
||||
parentSlug: 'my-switch-01',
|
||||
childSlug: 'some-connected-client-slug',
|
||||
relation: 'connected_to' // 'hosts', 'exposes', 'connected_to'
|
||||
});
|
||||
|
||||
return { resources, edges };
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Agents are automatically loaded and executed by the internal BullMQ job scheduler. You configure them in your `config/sso-secrets.js`:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
// ... existing config ...
|
||||
discovery: {
|
||||
agents: {
|
||||
my_custom_agent: {
|
||||
enabled: true,
|
||||
cron: '*/30 * * * *', // Run every 30 minutes
|
||||
url: 'https://api.example.com',
|
||||
apiKey: 'secret-key'
|
||||
},
|
||||
nmap: {
|
||||
enabled: true,
|
||||
cron: '0 * * * *',
|
||||
targetRange: '192.168.1.0/24'
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## The Reconciliation Engine
|
||||
|
||||
When your agent returns its graph, the Reconciliation Engine takes over:
|
||||
1. **Matching:** It tries to find an existing device in the database matching any MAC address provided in the `interfaces` array. If no MAC matches, it falls back to IP address, and then to `slug`.
|
||||
2. **Merging:** If it finds a match, it gracefully merges the metadata (so your agent can add CPU info to a host that NMAP previously found).
|
||||
3. **Source Tracking:** It records your agent's filename in the `discovery_sources` array on the resource, and updates the `last_seen` timestamp.
|
||||
4. **LDAP Spam Prevention:** Brand new devices are marked as `managed: false`. They will not pollute your LDAP directory until an admin explicitly promotes them.
|
||||
@@ -0,0 +1,116 @@
|
||||
/* theta42 docs site — shares the in-app dark navbar/footer + card look
|
||||
(Bootstrap 5 + Font Awesome, same as the running apps) rather than a
|
||||
generic Jekyll theme. */
|
||||
|
||||
body {
|
||||
background-color: #f4f5f6;
|
||||
}
|
||||
|
||||
.navbar-brand img {
|
||||
filter: drop-shadow(0 0 2px rgba(0, 0, 0, .4));
|
||||
}
|
||||
|
||||
.navbar-nav .nav-link.active {
|
||||
color: #fff;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
/* Markdown content typography, scoped to the card body so it doesn't leak
|
||||
into the nav/footer. */
|
||||
.site-content h1:first-child {
|
||||
margin-top: 0;
|
||||
}
|
||||
|
||||
.site-content h1,
|
||||
.site-content h2,
|
||||
.site-content h3 {
|
||||
font-weight: 700;
|
||||
}
|
||||
|
||||
.site-content h2 {
|
||||
margin-top: 2.5rem;
|
||||
padding-bottom: .4rem;
|
||||
border-bottom: 1px solid #e9ecef;
|
||||
}
|
||||
|
||||
.site-content h3 {
|
||||
margin-top: 1.75rem;
|
||||
}
|
||||
|
||||
.site-content a {
|
||||
color: #a3671f;
|
||||
text-decoration-color: rgba(163, 103, 31, .35);
|
||||
}
|
||||
|
||||
.site-content a:hover {
|
||||
color: #8a5a16;
|
||||
}
|
||||
|
||||
.site-content pre {
|
||||
background-color: #212529;
|
||||
color: #f8f9fa;
|
||||
padding: 1rem 1.25rem;
|
||||
border-radius: .375rem;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.site-content code {
|
||||
color: #a3671f;
|
||||
background-color: #f4f0e8;
|
||||
padding: .15em .4em;
|
||||
border-radius: .25rem;
|
||||
font-size: .875em;
|
||||
}
|
||||
|
||||
.site-content pre code {
|
||||
color: inherit;
|
||||
background: none;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.site-content table {
|
||||
display: block;
|
||||
overflow-x: auto;
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 1.25rem 0;
|
||||
}
|
||||
|
||||
.site-content table th,
|
||||
.site-content table td {
|
||||
border: 1px solid #dee2e6;
|
||||
padding: .5rem .75rem;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
.site-content table th {
|
||||
background-color: #f8f9fa;
|
||||
}
|
||||
|
||||
.site-content blockquote {
|
||||
border-left: 4px solid #C59341;
|
||||
padding: .5rem 1rem;
|
||||
margin: 1.25rem 0;
|
||||
background-color: #f8f6f1;
|
||||
color: #495057;
|
||||
}
|
||||
|
||||
.site-content img {
|
||||
max-width: 100%;
|
||||
height: auto;
|
||||
}
|
||||
|
||||
/* Screenshot grids in the markdown use width="49%" inline attrs for a
|
||||
two-up desktop layout -- stack them on narrow screens instead of
|
||||
squeezing to illegibility. */
|
||||
@media (max-width: 576px) {
|
||||
.site-content img[width] {
|
||||
width: 100% !important;
|
||||
margin-bottom: .75rem;
|
||||
}
|
||||
}
|
||||
|
||||
.site-content hr {
|
||||
margin: 2rem 0;
|
||||
border-top: 1px solid #e9ecef;
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="100%" height="100%">
|
||||
<defs>
|
||||
<linearGradient id="gold-grad" x1="0%" y1="0%" x2="100%" y2="100%">
|
||||
<stop offset="0%" stop-color="#C59341" />
|
||||
<stop offset="20%" stop-color="#E4B869" />
|
||||
<stop offset="40%" stop-color="#FBF0B9" />
|
||||
<stop offset="60%" stop-color="#DFB260" />
|
||||
<stop offset="80%" stop-color="#BC8837" />
|
||||
<stop offset="100%" stop-color="#A36F28" />
|
||||
</linearGradient>
|
||||
|
||||
<linearGradient id="text-grad" x1="0%" y1="100%" x2="100%" y2="0%">
|
||||
<stop offset="0%" stop-color="#FFFFFF" />
|
||||
<stop offset="40%" stop-color="#F5E3B5" />
|
||||
<stop offset="70%" stop-color="#D4A343" />
|
||||
<stop offset="100%" stop-color="#8A5A16" />
|
||||
</linearGradient>
|
||||
|
||||
<filter id="drop-shadow" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="8" stdDeviation="6" flood-color="#000000" flood-opacity="0.4"/>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<g filter="url(#drop-shadow)">
|
||||
<g fill="url(#gold-grad)">
|
||||
<path d="M 200,40
|
||||
C 290,40 350,110 350,200
|
||||
C 350,290 290,360 200,360
|
||||
C 110,360 50,290 50,200
|
||||
C 50,110 110,40 200,40 Z
|
||||
M 200,75
|
||||
C 130,75 88,130 88,200
|
||||
C 88,270 130,325 200,325
|
||||
C 270,325 312,270 312,200
|
||||
C 312,130 270,75 200,75 Z"
|
||||
fill-rule="evenodd" />
|
||||
|
||||
<path d="M 88,190 L 140,190 C 140,190 142,210 140,210 L 88,210 Z" />
|
||||
|
||||
<path d="M 260,190 L 312,190 C 312,190 310,210 260,210 Z" />
|
||||
</g>
|
||||
|
||||
<text x="200" y="222"
|
||||
font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"
|
||||
font-size="78"
|
||||
font-weight="900"
|
||||
fill="url(#text-grad)"
|
||||
text-anchor="middle"
|
||||
letter-spacing="-2">42</text>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.9 KiB |
@@ -0,0 +1,125 @@
|
||||
---
|
||||
layout: default
|
||||
title: Accounts, Groups & Managers
|
||||
description: A plain-language guide to users, service accounts, personal groups, and managers in SSO Manager.
|
||||
---
|
||||
|
||||
# Accounts, Groups & Managers
|
||||
|
||||
This page explains the concepts behind the Users and Groups pages in plain
|
||||
language. If you want the technical schema/attribute-level detail instead,
|
||||
see the [LDAP reference](ldap.html).
|
||||
|
||||
## What's an account?
|
||||
|
||||
Every person (or app) that can sign in through this SSO Manager 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
|
||||
connected (Gitea, Home Assistant, your Wi-Fi, whatever) checks against these
|
||||
same accounts instead of keeping its own separate list of users and
|
||||
passwords.
|
||||
|
||||
## Two kinds of account: people and service accounts
|
||||
|
||||
Most accounts belong to an actual person — check **Users → People** to see
|
||||
them. But sometimes you need an account for something that *isn't* a
|
||||
person: a media server, a backup script, a bind account another app uses to
|
||||
look people up. These are **service accounts**, listed separately under
|
||||
**Users → Service Accounts**, and they're different from a person's account
|
||||
in two ways that matter:
|
||||
|
||||
- **No email required.** A service account doesn't need a mailbox, so the
|
||||
form doesn't ask for one.
|
||||
- **A password is optional.** If you leave it blank, nobody can log in as
|
||||
that account — which is exactly what you want for something that only
|
||||
ever gets used programmatically (a script authenticating with an API
|
||||
token, or another app binding with a fixed, separately-configured
|
||||
password you set yourself). Only give it a password if the account
|
||||
genuinely needs to log in or bind somewhere as itself.
|
||||
|
||||
Aside from those two differences, a service account is a completely normal
|
||||
account under the hood — it can belong to groups, have a manager, and so
|
||||
on, just like anyone else's.
|
||||
|
||||
## Groups: who can do what
|
||||
|
||||
A **group** is just a named list of accounts, used to control access. This
|
||||
app has a handful of built-in groups that grant admin powers (e.g. only
|
||||
people in the `app_sso_admin` group can see the Users/Groups/Directory/Overview
|
||||
pages at all), but you can also make your own groups for any app you
|
||||
connect — say, a group listing everyone who should be allowed into your
|
||||
photo server. Once a group exists, add or remove members from the
|
||||
**Groups** page, and point the other app's "who's allowed in" setting at
|
||||
that group's name.
|
||||
|
||||
### Groups inside groups
|
||||
|
||||
A group can contain another group, not just people — the *Nested* tab on any
|
||||
group card. Everyone in the inner group counts as a member of the outer one,
|
||||
however many levels deep it goes.
|
||||
|
||||
This is mostly a way to stop repeating yourself. Make one `developers` group,
|
||||
nest it into the handful of things developers should reach, and adding a new
|
||||
developer to that one group grants all of them at once — instead of adding them
|
||||
to each individually and slowly drifting out of sync. The app already does this
|
||||
for itself: super admins are nested into every resource's admin group, and each
|
||||
admin group into its access group, so "can administer it" always implies "can
|
||||
use it".
|
||||
|
||||
Two things it won't let you do: put a group inside itself (directly or round a
|
||||
longer loop), and empty a group completely — every group must keep at least one
|
||||
member.
|
||||
|
||||
A note if you also manage the directory by hand: a group's member list shows
|
||||
what is *directly* listed on it. Someone who gets in through a nested group is
|
||||
a real member but won't appear there — the **Nested** tab shows what is nested,
|
||||
and the API's `effective` view lists everyone who actually gets in.
|
||||
|
||||
## Every account's personal group
|
||||
|
||||
Separately from the groups above, every single account — person or
|
||||
service account — automatically gets its own small, personal group when
|
||||
it's created, named after the account itself. Most of the time you'll
|
||||
never think about this; it exists so that, on a Linux system connected to
|
||||
this directory, each account "owns" its own files by default the same way
|
||||
a normal Unix user account would.
|
||||
|
||||
Occasionally you'll want to share that ownership with someone else — for
|
||||
example, letting a second account also have write access to files a
|
||||
service account owns. That's what the **"Members of `<uid>`'s group"**
|
||||
section on a profile page is for: add another account there, and the
|
||||
underlying Linux permissions treat them as if they belong to that same
|
||||
personal group too.
|
||||
|
||||
## What's a "manager"?
|
||||
|
||||
Every account has one or more **managers** — the people allowed to edit
|
||||
that account's profile (phone number, SSH key, home directory, and so on)
|
||||
without needing full admin rights. By default, whoever created an account
|
||||
(the admin who added it, or whoever sent the invite) becomes its first
|
||||
manager, but you can add or remove managers later from the account's Edit
|
||||
form.
|
||||
|
||||
This is useful for service accounts especially: if a service account
|
||||
belongs to a particular project or person, make them its manager so they
|
||||
can maintain it — rotate its SSH key, adjust its description — without
|
||||
needing to be a full SSO administrator.
|
||||
|
||||
## Inviting someone vs. adding them yourself
|
||||
|
||||
From the Users page you can either fill in someone's details yourself
|
||||
("Add new user"), or send them an **invite** — an email (or a link you copy
|
||||
and send however you like) that lets them pick their own username and
|
||||
password. Either way, the resulting account is identical; invites are just
|
||||
a convenience so you don't have to know someone's preferred username or
|
||||
handle their password directly.
|
||||
|
||||
## Want more detail?
|
||||
|
||||
This page deliberately leaves out LDAP schema names, attribute types, and
|
||||
protocol-level detail. If you're connecting a third-party app directly to
|
||||
the LDAP directory, or you just want to know exactly what's stored where,
|
||||
see the [LDAP reference](ldap.html).
|
||||
|
||||
[← Back to Home](index.html)
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
layout: default
|
||||
title: API Tokens
|
||||
description: A plain-language guide to personal access tokens in SSO Manager.
|
||||
---
|
||||
|
||||
# API Tokens
|
||||
|
||||
This page explains what an API token is and when you'd want one. For the
|
||||
full list of API endpoints a token can call, see the
|
||||
[API reference](https://github.com/theta42/sso-manager-node/blob/master/API.md).
|
||||
|
||||
## What's an API token, in plain terms?
|
||||
|
||||
Normally, you interact with this app by logging in through a web browser.
|
||||
An **API token** (also called a personal access token, or PAT) is an
|
||||
alternative way in — a long, random string that a script, a scheduled job,
|
||||
or another program can use instead of a username and password, to act on
|
||||
your behalf without a human typing a login in each time.
|
||||
|
||||
If you've ever set up a script to talk to GitHub, GitLab, or a similar
|
||||
service using a "token" instead of your real password, this is the same
|
||||
idea.
|
||||
|
||||
## When would you actually need one?
|
||||
|
||||
Most people never need to create one of these — you'll only want a token
|
||||
if you're automating something, for example:
|
||||
|
||||
- A script that syncs users or groups from somewhere else into this SSO
|
||||
Manager on a schedule.
|
||||
- A backup or monitoring job that checks this app's health via its API.
|
||||
- A CI/CD pipeline that needs to register or update an OAuth client
|
||||
automatically.
|
||||
|
||||
If you're not doing any of that, you don't need an API token — just log in
|
||||
normally through the web UI.
|
||||
|
||||
## How it works
|
||||
|
||||
Create a token from your Profile page, give it a name so you remember what
|
||||
it's for later, and optionally an expiry. You'll be shown the token's
|
||||
value **exactly once** — copy it somewhere safe immediately, because it
|
||||
can't be viewed again afterward (only revoked or rotated). Whatever script
|
||||
or tool you're using it with sends it along with each request, the same
|
||||
way a browser sends your login session.
|
||||
|
||||
A token acts **as you**, with **your** permissions — if you're not an
|
||||
admin, a token you create can't do admin-only things either. If you ever
|
||||
suspect a token has leaked (ended up somewhere it shouldn't have, like a
|
||||
public script or log file), revoke it immediately from your Profile page;
|
||||
it stops working right away.
|
||||
|
||||
## Want more detail?
|
||||
|
||||
This page doesn't attempt to list every API endpoint or show request/
|
||||
response examples — for that, see the full [API reference](https://github.com/theta42/sso-manager-node/blob/master/API.md).
|
||||
|
||||
[← Back to Home](index.html)
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
layout: default
|
||||
title: Connecting Apps (Single Sign-On)
|
||||
description: A plain-language guide to OAuth/OIDC clients and single sign-on in SSO Manager.
|
||||
---
|
||||
|
||||
# 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
|
||||
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,
|
||||
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)
|
||||
instead of hunting down every app individually.
|
||||
|
||||
The technology behind this is called **OAuth 2.0** and **OpenID Connect
|
||||
(OIDC)** — you'll see both names used, often together, referring to the
|
||||
same thing. You don't need to understand the protocol to use this page;
|
||||
what matters practically is the handful of concepts below.
|
||||
|
||||
## What's a "client"?
|
||||
|
||||
Every app you connect is registered here as a **client** — a single entry
|
||||
in the Directory representing that one app. Registering a client
|
||||
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
|
||||
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
|
||||
it's leaked, rotate it from the client's card.
|
||||
|
||||
## What are "scopes"?
|
||||
|
||||
**Scopes** control what information a connected app is allowed to ask for
|
||||
about the person logging in — their username, email, group memberships,
|
||||
and so on. Most apps tell you exactly which scopes they need in their own
|
||||
setup instructions; when in doubt, the default set (`openid`, `profile`,
|
||||
`email`, `groups`) covers what nearly every app expects.
|
||||
|
||||
## "Restrict to Groups"
|
||||
|
||||
By default, *any* account with an SSO Manager 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.
|
||||
|
||||
## Redirect URIs
|
||||
|
||||
A **Redirect URI** is the exact web address the connected app wants people
|
||||
sent back to once they've logged in here — it's a security measure so an
|
||||
attacker can't trick the login flow into redirecting somewhere else. The
|
||||
app's own setup instructions will tell you this value; copy it in exactly
|
||||
as given. If the app is reachable via more than one hostname (for example,
|
||||
because it sits behind [theta42/proxy](https://theta42.github.io/proxy/)),
|
||||
this field supports wildcard patterns — see the inline help under the
|
||||
field itself for the exact syntax.
|
||||
|
||||
## Want more detail?
|
||||
|
||||
This page intentionally skips the protocol-level detail (exact endpoint
|
||||
URLs, token formats, claim names). If you're troubleshooting a connection
|
||||
or building something against the API directly, see the
|
||||
[OAuth reference](oauth.html).
|
||||
|
||||
[← Back to Home](index.html)
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
layout: default
|
||||
title: Configuration
|
||||
description: SSO Manager's config layers — conf/base.js defaults, secrets.js overrides, and app_* environment variables.
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
[← Back to Home](index.html)
|
||||
|
||||
The app loads configuration via
|
||||
[`@simpleworkjs/conf`](https://www.npmjs.com/package/@simpleworkjs/conf), which
|
||||
deep-merges, in order (later wins):
|
||||
|
||||
1. `conf/base.js` — committed, generic defaults (`dc=example,dc=com`,
|
||||
`localhost`, `SSO Manager`).
|
||||
2. `conf/<NODE_ENV>.js` — optional, environment-specific.
|
||||
3. `conf/secrets.js` — gitignored; secrets + per-deployment values.
|
||||
4. **`app_*` environment variables** — the highest-precedence layer.
|
||||
|
||||
Any env var whose name starts with `app_` overrides the merged config. The rest
|
||||
of the name splits on **double-underscore** (`__`) into a nested path. Values are
|
||||
`JSON.parse`-coerced when possible (numbers, booleans, null, JSON) and kept as
|
||||
raw strings otherwise.
|
||||
|
||||
## Examples
|
||||
|
||||
| Env var | Sets | Type |
|
||||
|---------|------|------|
|
||||
| `app_ldap__url=ldap://host:389` | `conf.ldap.url` | string |
|
||||
| `app_ldap__bindPassword=secret` | `conf.ldap.bindPassword` | string |
|
||||
| `app_ldap__userBase=ou=people,dc=…` | `conf.ldap.userBase` | string |
|
||||
| `app_ldap__uidGidMin=1500` | `conf.ldap.uidGidMin` | number (new-user id floor) |
|
||||
| `app_ldap__uidGidReservedFloor=9000` | `conf.ldap.uidGidReservedFloor` | number (ids at/above this are ignored when allocating) |
|
||||
| `app_ldap__ldapsHost=ldap.internal.example.com` | `conf.ldap.ldapsHost` | string (hostname shown on `/integrations` for LDAPS binds; empty = derive from `oauth.issuer`) |
|
||||
| `app_ldap__ldapsPort=636` | `conf.ldap.ldapsPort` | number (port shown on `/integrations`) |
|
||||
| `app_oauth__jwtSecret=...` | `conf.oauth.jwtSecret` | string |
|
||||
| `app_oauth__issuer=https://sso.example.com` | `conf.oauth.issuer` | string |
|
||||
| `app_oauth__token_lifetime__access_token=3600` | `conf.oauth.token_lifetime.access_token` | number |
|
||||
| `app_smtp__secure=false` | `conf.smtp.secure` | boolean |
|
||||
| `app_smtp__host=smtp.example.com` | `conf.smtp.host` | string |
|
||||
| `app_name=My SSO` | `conf.name` | string |
|
||||
| `app_redis__host=redis.local` | `conf.redis.host` | string (external Redis) |
|
||||
|
||||
## The `app_*` env layer requires conf >= 1.1.0
|
||||
|
||||
The `app_*` environment-variable override layer was added in
|
||||
`@simpleworkjs/conf` **1.1.0**. On 1.0.0 the app ignores all `app_*` vars and only
|
||||
reads `base.js` / `<NODE_ENV>.js` / `secrets.js`. The Docker image will not honor
|
||||
`app_*` env on 1.0.0. Refresh the lock from the `nodejs/` directory:
|
||||
|
||||
```bash
|
||||
cd nodejs && npm install @simpleworkjs/conf@^1.1.0
|
||||
```
|
||||
|
||||
## Inspecting the merged config
|
||||
|
||||
From the `nodejs/` directory:
|
||||
|
||||
```bash
|
||||
node -e "console.log(require('@simpleworkjs/conf').ldap)"
|
||||
node -e "console.log(require('@simpleworkjs/conf').oauth)"
|
||||
node -e "console.log(require('@simpleworkjs/conf'))" # everything
|
||||
```
|
||||
|
||||
Or, inside the running container:
|
||||
|
||||
```bash
|
||||
docker compose exec sso-manager node -e "console.log(require('@simpleworkjs/conf').ldap)"
|
||||
```
|
||||
|
||||
`app_*` env vars override `secrets.js`, which overrides `base.js` — if a value
|
||||
isn't what you expect, check those layers in that order.
|
||||
|
||||
## Migrating an existing instance to the generic defaults
|
||||
|
||||
The committed `nodejs/conf/base.js` ships **generic** defaults
|
||||
(`dc=example,dc=com`, `localhost`, `SSO Manager`). Previously it carried
|
||||
Theta42-specific values (LDAP bind DN/bases, SMTP host/user/sender, OAuth
|
||||
issuer). If you run an existing instance off this repo:
|
||||
|
||||
- Move per-deployment, non-secret values (bind DN, user/group bases, SMTP
|
||||
host/user/sender, OAuth issuer, org name) from `base.js` into your gitignored
|
||||
`conf/secrets.js`, **or** set them as `app_*` env vars.
|
||||
- Secret values (LDAP bind password, SMTP password, JWT secret) already belong
|
||||
in `secrets.js`.
|
||||
|
||||
## Troubleshooting `app_*` env vars
|
||||
|
||||
### `app_*` vars seem to do nothing
|
||||
|
||||
You're on `@simpleworkjs/conf` 1.0.0. Bump to 1.1.0+ (above).
|
||||
|
||||
### LDAP operations 401 / "Invalid Credentials"
|
||||
|
||||
Check the merged LDAP config the app actually sees:
|
||||
|
||||
```bash
|
||||
cd nodejs && node -e "console.log(require('@simpleworkjs/conf').ldap)"
|
||||
```
|
||||
|
||||
Confirm `url` / `bindDN` / `bindPassword` / `userBase` match your directory.
|
||||
|
||||
[← Back to Home](index.html)
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
layout: default
|
||||
title: Deployment
|
||||
description: Deploying SSO Manager — the all-in-one Docker image, bare-metal install, config layers, and backups.
|
||||
---
|
||||
|
||||
# Deployment Guide
|
||||
|
||||
[← Back to Home](index.html)
|
||||
|
||||
The full deployment guide — Docker (all-in-one image), bare-metal install,
|
||||
the `app_*` env reference, backups, and the security notes (including why
|
||||
LDAPS shouldn't be port-forwarded to the internet) — lives in one place to
|
||||
avoid two copies drifting out of sync:
|
||||
|
||||
**[DEPLOYMENT.md on GitHub](https://github.com/theta42/sso-manager-node/blob/master/DEPLOYMENT.md)**
|
||||
|
||||
See also [Configuration](configuration.html) for the config layer merge
|
||||
order, and [LDAP](ldap.html) for the directory layout and connecting a
|
||||
3rd-party app.
|
||||
|
||||
[← Back to Home](index.html)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 392 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 430 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 313 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 123 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 221 KiB |
@@ -0,0 +1,85 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# SSO Manager
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
## Screenshots
|
||||
|
||||
<a href="images/dashboard.png" target="_blank"><img src="images/dashboard.png" alt="Overview dashboard" width="49%"></a>
|
||||
<a href="images/users.png" target="_blank"><img src="images/users.png" alt="User list" width="49%"></a>
|
||||
<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>
|
||||
|
||||
*(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
|
||||
tokens; standard discovery document at `/.well-known/openid-configuration`.
|
||||
- **Bundled OpenLDAP directory** — users, groups, POSIX accounts, SSH public
|
||||
keys, and sudo roles, with `memberOf` + referential-integrity overlays.
|
||||
- **Web management UI** — users, groups, and OAuth clients from a browser;
|
||||
invite and password-reset flows over email; self-service profile + API
|
||||
tokens.
|
||||
- **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
|
||||
```
|
||||
|
||||
That's the standalone quick start. 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.
|
||||
+432
@@ -0,0 +1,432 @@
|
||||
---
|
||||
layout: default
|
||||
title: LDAP
|
||||
description: SSO Manager's bundled OpenLDAP directory — schema, service accounts, TLS, and connecting third-party apps directly.
|
||||
---
|
||||
|
||||
# LDAP Directory
|
||||
|
||||
[← Back to Home](index.html)
|
||||
|
||||
> Looking for a plainer explanation of accounts, groups, and managers
|
||||
> 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
|
||||
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
|
||||
theta42/proxy, etc.
|
||||
|
||||
## Directory layout
|
||||
|
||||
```
|
||||
dc=yourdomain,dc=com
|
||||
├── ou=people users (inetOrgPerson + posixAccount + …)
|
||||
├── ou=groups groups (groupOfNames)
|
||||
└── ou=policies password policies (pwdPolicy)
|
||||
└── cn=ppolicy default policy
|
||||
```
|
||||
|
||||
### Users
|
||||
|
||||
User entries are `cn=<uid>,ou=people,<base>` and carry the objectClasses:
|
||||
|
||||
- `inetOrgPerson` (cn, sn, mail, …) — identity / contact attrs.
|
||||
- `posixAccount` (uid, uidNumber, gidNumber, homeDirectory) — the SSO's
|
||||
`userFilter` is `(objectClass=posixAccount)`, so a user is "a real account"
|
||||
iff it has `posixAccount`.
|
||||
- `ldapPublicKey` — SSH public keys (`sshPublicKey`).
|
||||
- `sudoRole` — per-user sudo rules (`sudoCommand`, `sudoHost`, `sudoUser`).
|
||||
- `theta42Person` (custom auxiliary; `dateOfBirth`).
|
||||
|
||||
Every user (person or service account) also carries a `manager` attribute
|
||||
(the standard COSINE `manager`, `SUP distinguishedName`) — one or more DNs of
|
||||
the people who created/administer that account. Set automatically to the
|
||||
creator's DN on signup (whoever an admin was logged in as, or whoever sent
|
||||
the invite), and reassignable later from the account's Edit form. Anyone
|
||||
listed as a `manager` can edit that account (same fields an admin can:
|
||||
mobile, description, SSH key, date of birth, home directory, login shell,
|
||||
and the manager list itself) without needing `app_sso_admin`.
|
||||
|
||||
Passwords are stored as `{SSHA512}` (8-byte salt, sha512(pass+salt), base64),
|
||||
verified by the `pw-sha2` module. The app's `hashPasswordSSHA512` is the
|
||||
canonical hasher; if you provision users out-of-band, hash passwords the same
|
||||
way or use `slappasswd -h '{SSHA512}'`.
|
||||
|
||||
### Groups
|
||||
|
||||
Groups are `cn=<name>,ou=groups,<base>` (`groupOfNames`) with a `member`
|
||||
attribute listing member DNs. The `memberOf` overlay populates reverse
|
||||
membership (`memberOf` on the user); `refint` keeps it consistent on
|
||||
add/remove.
|
||||
|
||||
Note that `groupOfNames` requires **at least one member**, which has two
|
||||
consequences worth knowing: whoever creates a group is automatically seeded
|
||||
into it, and removing the last member (user *or* nested group) is refused with
|
||||
a 409 rather than leaving an invalid entry behind.
|
||||
|
||||
### Nested groups
|
||||
|
||||
A `member` DN may be another group's, not just a user's — that is how nesting
|
||||
is stored, with no extra schema. Everyone in the nested group is a member of
|
||||
the outer one, at any depth. Manage it on the **Groups** page under each
|
||||
group's *Nested* tab, or via the API:
|
||||
|
||||
```
|
||||
PUT /api/group/:group/nested/:child nest :child inside :group
|
||||
DELETE /api/group/:group/nested/:child un-nest
|
||||
GET /api/group/:group/effective direct users, nested groups, and the
|
||||
full transitive set of users
|
||||
```
|
||||
|
||||
Cycles are refused (409) rather than truncated — a loop makes "who is in this
|
||||
group" unanswerable. Two standing relationships are wired automatically: the
|
||||
cross-app `app_super_admin` is nested into every resource's `<slug>_admin`
|
||||
group, and each `<slug>_admin` into its `<slug>_access` group, so administering
|
||||
something implies being able to use it.
|
||||
|
||||
**Resolving nesting is a client-side job on stock OpenLDAP.** No 2.6.x release
|
||||
can evaluate nested groups; `memberOf` and a `(member=X)` filter both return
|
||||
direct membership only. The bundled slapd is therefore built from source with
|
||||
the `nestgroup` overlay (see *Modules + overlays* below), and the app is told so
|
||||
via `ldap.nestedGroupsServerSide`. Against any other server the app computes the
|
||||
closure itself — same answers, more queries. Either way, **never read `memberOf`
|
||||
directly to make an access decision**; use `utils/user_groups.js`'s `groupCns()`,
|
||||
which is correct in both modes.
|
||||
|
||||
### Personal groups
|
||||
|
||||
Every user (person or service account) also gets a **personal Unix group**
|
||||
at creation — `cn=<uid>,ou=groups,<base>`, `objectClass: posixGroup` (RFC
|
||||
2307), holding just `cn` and `gidNumber` (the user's primary GID). This is a
|
||||
different schema than the `groupOfNames` groups above — its membership
|
||||
attribute is `memberUid` (a bare username, not a DN), and unlike
|
||||
`groupOfNames` it's valid with zero members. It's excluded from the
|
||||
`/groups` page (which filters on `objectClass=groupOfNames`) and managed
|
||||
instead from the owning user's own profile page ("Members of `<uid>`'s
|
||||
group", admin-only) — add other accounts as supplementary members, e.g. to
|
||||
share write access to files owned by this group.
|
||||
|
||||
The SSO seeds these groups automatically (entrypoint / `install.sh`):
|
||||
|
||||
| Group | Grants |
|
||||
|-------|--------|
|
||||
| `app_super_admin` | cross-app super admin. Nested into the three below, so its members hold those rights transitively rather than by a special case in app code — and the privilege is visible to LDAP-native consumers (SSSD, sudo) too. |
|
||||
| `app_sso_admin` | full admin (users, groups, settings) |
|
||||
| `app_sso_oauth_admin` | OAuth client management |
|
||||
| `app_sso_invite` | invitation management |
|
||||
| `app_sso_service_account` | not a permission — marks a `posixAccount` as a non-person service account (see *Service accounts* below). Deliberately **not** nested into, since it changes how an account is displayed rather than what it may do. |
|
||||
|
||||
## TLS (LDAPS / StartTLS)
|
||||
|
||||
The bundled slapd generates a **self-signed cert** on first start (CN =
|
||||
`LDAP_CERT_CN`, valid 10y, SAN = CN + `localhost` + `127.0.0.1`) and listens on:
|
||||
|
||||
- `ldaps:///` — **636**, TLS (the port to expose for direct-LDAP clients).
|
||||
- `ldap:///` — **389**, plain + StartTLS (not mapped to the host by default).
|
||||
|
||||
The cert lives on the `ldap-certs` volume so it persists across container
|
||||
recreation.
|
||||
|
||||
### Trusting the self-signed cert
|
||||
|
||||
Copy it out and add it to the client's CA store:
|
||||
|
||||
```bash
|
||||
docker compose cp sso-manager:/etc/openldap/certs/ldap.crt ./ldap.crt
|
||||
```
|
||||
|
||||
…or, for quick LAN use, set `TLS_REQCERT never` on the client (the theta42/proxy
|
||||
sets `app_ldap__tlsOptions__rejectUnauthorized=false` for the same effect).
|
||||
|
||||
### Using your own cert
|
||||
|
||||
Replace the `ldap-certs` named volume with a bind mount containing your own
|
||||
`ldap.crt` + `ldap.key`:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./certs:/etc/openldap/certs # must contain ldap.crt + ldap.key
|
||||
```
|
||||
|
||||
The entrypoint leaves existing certs untouched (idempotent).
|
||||
|
||||
## Choosing the LDAPS hostname
|
||||
|
||||
The `/integrations` page advertises an **LDAPS URL** for direct LDAP binds. By
|
||||
default it derives that URL from the public OAuth issuer (e.g.
|
||||
`https://sso.example.com` → `ldaps://sso.example.com:636`). That is convenient,
|
||||
but it implies LDAP clients reach your directory through the same public
|
||||
hostname — which usually means port-forwarding 636 through your router.
|
||||
|
||||
**Do not port-forward LDAPS (636) to the public internet.** LDAP simple binds
|
||||
have no rate limiting and are a brute-force target. Instead, use one of these
|
||||
internal-only patterns and set `conf.ldap.ldapsHost` (or
|
||||
`app_ldap__ldapsHost`) so the `/integrations` page shows the right URL.
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
ldaps://sso-manager:636
|
||||
```
|
||||
|
||||
In `conf/secrets.js`:
|
||||
|
||||
```javascript
|
||||
ldap: {
|
||||
ldapsHost: 'sso-manager',
|
||||
ldapsPort: 636,
|
||||
}
|
||||
```
|
||||
|
||||
The proxy in theta-env already uses this internally. The bundled slapd cert
|
||||
includes `sso-manager` in its SAN when `LDAP_CERT_CN` is left at its default,
|
||||
so hostname verification works without extra setup.
|
||||
|
||||
### 2. LAN host behind your router (best for separate home-lan machines)
|
||||
|
||||
Create an internal-only DNS record — e.g. `ldap.internal.example.com` →
|
||||
`192.168.1.10` — using your router, Pi-hole, or a local `hosts` file. Then get
|
||||
or generate a cert whose SAN/CN matches that internal name:
|
||||
|
||||
- **Let's Encrypt wildcard** (`*.internal.example.com`) works if you own the
|
||||
public domain and can complete DNS-01 challenge; the record itself can stay
|
||||
private/routable only inside your LAN.
|
||||
- **Internal CA** is fine for a pure LAN: run a small CA, issue a cert for
|
||||
`ldap.internal.example.com`, and distribute the CA cert to clients.
|
||||
- **Self-signed** with `LDAP_CERT_CN=ldap.internal.example.com` also works; copy
|
||||
the generated `ldap.crt` to each client and trust it.
|
||||
|
||||
In `conf/secrets.js`:
|
||||
|
||||
```javascript
|
||||
ldap: {
|
||||
ldapsHost: 'ldap.internal.example.com',
|
||||
ldapsPort: 636,
|
||||
}
|
||||
```
|
||||
|
||||
The URL on `/integrations` becomes `ldaps://ldap.internal.example.com:636`.
|
||||
|
||||
### 3. Public hostname (acceptable only behind a VPN/firewall)
|
||||
|
||||
If a remote host must bind LDAP, put it behind a VPN (Tailscale, WireGuard,
|
||||
etc.) or a tightly locked-down firewall rule. In that case the public hostname
|
||||
may be appropriate, but the LDAPS port should still not be reachable from the
|
||||
open internet.
|
||||
|
||||
### Why not just use the LDAP server's IP address?
|
||||
|
||||
TLS clients verify the server name against the certificate. Connecting to
|
||||
`ldaps://192.168.1.10:636` with a cert issued for `*.internal.example.com`
|
||||
will fail hostname verification unless you disable cert checks — which removes
|
||||
most of the security benefit of LDAPS. Always use a hostname that matches the
|
||||
cert.
|
||||
|
||||
## Service accounts
|
||||
|
||||
A service account is a normal `posixAccount` for something that isn't a
|
||||
person: a media manager, a torrent client, a service like Emby, or a
|
||||
read-only bind account an app uses to look users up — anything that needs a
|
||||
real `uidNumber`/`gidNumber` to own files, or that other accounts join via a
|
||||
group for write access (e.g. a `stuff_manager` group granting write rights
|
||||
to a media library). There's only one kind — every account, person or
|
||||
service, is a real `posixAccount` with a UID.
|
||||
|
||||
Create one from the **Users → Service Accounts** tab's "Add new user" form
|
||||
with **This is a service account** checked — it skips the birthday/
|
||||
Terms-of-Service fields a real person's account needs and asks for just an
|
||||
account name. It's flagged (via membership in the `app_sso_service_account`
|
||||
group) so it's listed separately from real people and excluded from "all
|
||||
users" notification broadcasts.
|
||||
|
||||
Email and password are both optional for a service account:
|
||||
|
||||
- No `mail` is set unless you give it one (it never needs a mailbox).
|
||||
- Leaving the password blank is fine — no `userPassword` attribute is set at
|
||||
all, and an entry with no `userPassword` simply can't bind with any
|
||||
password (standard LDAP simple-bind behavior). Only set a password if the
|
||||
account actually needs to authenticate as itself (e.g. a bind-only account
|
||||
an app uses to look users up).
|
||||
|
||||
theta-env's bootstrap creates its own `cn=ldapclient` bind account directly
|
||||
against LDAP (independent of this app), and the proxy binds as it — that
|
||||
account won't show up in the Service Accounts tab since it isn't managed
|
||||
through this app, but it keeps working unchanged.
|
||||
|
||||
Either way: don't reuse the admin DN, and give a service account only the
|
||||
group memberships and `manager`s it actually needs.
|
||||
|
||||
Example bind test (a service account with a password set):
|
||||
|
||||
```bash
|
||||
ldapsearch -x -H ldaps://sso.example.com:636 \
|
||||
-D "cn=ldapclient,ou=people,dc=yourdomain,dc=com" -W \
|
||||
-b "ou=people,dc=yourdomain,dc=com" '(objectClass=posixAccount)' cn mail
|
||||
```
|
||||
|
||||
## Connecting a 3rd-party app or container
|
||||
|
||||
Most self-hosted apps with an "LDAP authentication" settings page — Gitea,
|
||||
Nextcloud, Grafana, Emby, Jenkins, etc. — or containers configured via
|
||||
`LDAP_*` env vars, all ask for the same handful of values. These are the
|
||||
`conf.ldap` values from [Configuration](configuration.html), applied to
|
||||
*your* domain:
|
||||
|
||||
| Field the app asks for | Value |
|
||||
|---|---|
|
||||
| Host / URL | `ldaps://<your-sso-host>:636` (preferred), or `ldap://<host>:389` + StartTLS |
|
||||
| Bind DN | a dedicated service account — e.g. `cn=ldapclient,ou=people,<base>` (see above) |
|
||||
| Bind password | that service account's password |
|
||||
| User search base | `ou=people,<base>` |
|
||||
| User search filter | `(objectClass=posixAccount)` |
|
||||
| Username attribute | `uid` |
|
||||
| Email attribute | `mail` |
|
||||
| Group search base | `ou=groups,<base>` |
|
||||
| Group membership attribute | `memberOf` (on the user entry — populated by the `memberof` overlay) |
|
||||
| TLS | required for 636 (LDAPS); if using the bundled self-signed cert, either trust it (see *TLS* above) or set the app's "don't verify cert" option for LAN-only use |
|
||||
|
||||
### Worked example: Gitea
|
||||
|
||||
Gitea's **Admin → Authentication Sources → Add Authentication Source** (type
|
||||
LDAP, "Bind DN/Password") maps directly:
|
||||
|
||||
- Security Protocol: `LDAPS`
|
||||
- Host / Port: your SSO host / `636`
|
||||
- Bind DN: `cn=ldapclient,ou=people,dc=yourdomain,dc=com`
|
||||
- Bind Password: the service account's password
|
||||
- User Search Base: `ou=people,dc=yourdomain,dc=com`
|
||||
- User Filter: `(&(objectClass=posixAccount)(uid=%s))`
|
||||
- Username Attribute: `uid`
|
||||
- E-mail Attribute: `mail`
|
||||
|
||||
Other apps with an LDAP settings UI follow the same shape — the field names
|
||||
above are the constants; only the base DN and hostname change per deployment.
|
||||
|
||||
### Generic Docker container (`LDAP_*` env vars)
|
||||
|
||||
For images that take a flat env-var LDAP config (there's no single standard,
|
||||
but most look like this):
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
LDAP_URL: ldaps://sso.example.com:636
|
||||
LDAP_BIND_DN: cn=ldapclient,ou=people,dc=yourdomain,dc=com
|
||||
LDAP_BIND_PASSWORD: <service-account-password>
|
||||
LDAP_USER_BASE: ou=people,dc=yourdomain,dc=com
|
||||
LDAP_USER_FILTER: (objectClass=posixAccount)
|
||||
LDAP_GROUP_BASE: ou=groups,dc=yourdomain,dc=com
|
||||
```
|
||||
|
||||
Check the specific image's docs for its actual variable names — the values
|
||||
you plug in are still the ones from the table above.
|
||||
|
||||
### Full Linux host auth (SSH, sudo, login) instead of a single app
|
||||
|
||||
If you want a *host* (not just one app) to authenticate logins, SSH keys, and
|
||||
sudo against this LDAP directory — not just one application — that's a
|
||||
different integration (SSSD + PAM + NSS, not a single bind). See
|
||||
[theta42/ldap-client](https://github.com/theta42/ldap-client): a script that
|
||||
configures SSSD on Ubuntu/Debian hosts against this directory, including
|
||||
group-based access control and SSH public key retrieval from LDAP.
|
||||
|
||||
## Modules + overlays (external LDAP servers)
|
||||
|
||||
If you point the app at your own LDAP server instead of the bundled slapd, it
|
||||
needs:
|
||||
|
||||
- **Modules:** `pw-sha2` (the app stores user passwords as `{SSHA512}`),
|
||||
`ppolicy`, `memberof`, `refint`.
|
||||
- **Optional — `nestgroup`:** server-side nested-group evaluation. Not in any
|
||||
released OpenLDAP (added to master as ITS#10161 in March 2024; 2.7 is still
|
||||
unreleased), so the bundled image builds slapd from a pinned upstream commit.
|
||||
Without it the app resolves nesting itself and everything still works — leave
|
||||
`ldap.nestedGroupsServerSide` at `false`. With it, set that to `true` and
|
||||
configure:
|
||||
|
||||
```
|
||||
overlay nestgroup
|
||||
nestgroup-base ou=groups,<base>
|
||||
nestgroup-flags member-filter memberof-filter memberof-values
|
||||
```
|
||||
|
||||
Flags are **space-separated**; the comma form the man page's `{a, b, c}`
|
||||
notation suggests is rejected. `member-values` is deliberately omitted — it
|
||||
expands the `member` attribute when reading a group, which destroys the
|
||||
distinction between "listed here" and "reachable through a nested group", and
|
||||
the raw values are then unrecoverable. Transitive answers come from the filter
|
||||
flags and from `GET /api/group/:group/effective`.
|
||||
|
||||
One more consequence of building from master: it ships **LMDB 1.0.0**, whose
|
||||
on-disk format is mutually unreadable with the 0.9.x in 2.6.x
|
||||
(`MDB_INVALID: File is not an LMDB file`). Moving a directory between the two
|
||||
is a `slapcat` → `slapadd` reload, not a restart.
|
||||
- **Custom schema:** the `theta42Person` auxiliary objectClass with
|
||||
`dateOfBirth` — see `ops/ldap-setup.sh` for the LDIF.
|
||||
- **Directory tree:** `ou=people`, `ou=groups`, `ou=policies` under the base DN,
|
||||
a default `pwdPolicy` at `cn=ppolicy,ou=policies,<base>`.
|
||||
- **Required groups:** `app_sso_admin`, `app_sso_invite`, `app_sso_oauth_admin`,
|
||||
and `app_super_admin` (the cross-app super-admin group; the bundled entrypoint
|
||||
also nests it into the first three).
|
||||
|
||||
`ops/ldap-setup.sh -p <admin-password>` configures all of the above
|
||||
idempotently against a running slapd (auto-detects the database holding your
|
||||
base DN, and verifies `pwdAccountLockedTime` is live — the attribute the app's
|
||||
active/inactive toggle depends on).
|
||||
|
||||
## Backups and restore
|
||||
|
||||
`ops/backup.sh` automates this (LDAP + Redis + `./config/`, with retention)
|
||||
for standalone deployments — see the *Backups and restore* section of
|
||||
`DEPLOYMENT.md`. The manual LDAP-only steps below are what it does under the
|
||||
hood, useful if you want just the directory without Redis/config.
|
||||
|
||||
**Backup** (while slapd is running):
|
||||
|
||||
```bash
|
||||
docker compose exec sso-manager slapcat -f /etc/openldap/slapd.conf \
|
||||
-b "dc=yourdomain,dc=com" > ldap-backup-$(date +%F).ldif
|
||||
```
|
||||
|
||||
Store the `.ldif` off the host — it contains every user's password hash.
|
||||
|
||||
**Restore** into a stopped directory. The SSO image uses a static `slapd.conf`
|
||||
(slapd starts with `-f`, not cn=config `-F`), so restore uses `slapadd -f`:
|
||||
|
||||
```bash
|
||||
docker compose stop sso-manager
|
||||
docker compose run --rm --no-deps --entrypoint sh sso-manager -c \
|
||||
'rm -f /var/lib/ldap/* && slapadd -f /etc/openldap/slapd.conf -l /dev/stdin' \
|
||||
< ldap-backup-<date>.ldif
|
||||
docker compose start sso-manager
|
||||
```
|
||||
|
||||
Verify: `docker compose exec sso-manager ldapsearch -x -b "dc=yourdomain,dc=com"`.
|
||||
|
||||
Redis state (OAuth clients, tokens) and `./config/` secrets are backed up
|
||||
separately — see the *Backups and restore* section of `DEPLOYMENT.md` for the
|
||||
full (LDAP + Redis + secrets) runbook.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `503 OpenLDAP ppolicy overlay is not configured`
|
||||
|
||||
The ppolicy overlay isn't attached to the database holding your users, so the
|
||||
active/inactive toggle can't set `pwdAccountLockedTime`:
|
||||
|
||||
```bash
|
||||
sudo ./ops/ldap-setup.sh -p 'admin-password' -b dc=yourdomain,dc=com
|
||||
```
|
||||
|
||||
### LDAP connection refused
|
||||
|
||||
```bash
|
||||
docker compose exec sso-manager sh -c 'ldapsearch -x -H ldap://localhost:389 -b "" -s base'
|
||||
systemctl status slapd # bare metal
|
||||
```
|
||||
|
||||
[← Back to Home](index.html)
|
||||
+112
@@ -0,0 +1,112 @@
|
||||
---
|
||||
layout: default
|
||||
title: OAuth / OIDC
|
||||
description: SSO Manager's OpenID Connect / OAuth 2.0 provider — discovery document, client registration, and token endpoints.
|
||||
---
|
||||
|
||||
# OAuth 2.0 / OpenID Connect
|
||||
|
||||
[← Back to Home](index.html)
|
||||
|
||||
> Looking for a plainer explanation of clients/scopes/redirect URIs instead
|
||||
> 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
|
||||
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.
|
||||
|
||||
## Discovery
|
||||
|
||||
The provider publishes a standards-compliant discovery document:
|
||||
|
||||
```
|
||||
GET https://<sso-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
It advertises the `issuer`, `authorization_endpoint`, `token_endpoint`,
|
||||
`userinfo_endpoint`, `end_session_endpoint`, supported scopes, and token
|
||||
lifetimes. OIDC clients (e.g. the theta42/proxy) can read their endpoint URLs
|
||||
from here rather than configuring each one.
|
||||
|
||||
The `issuer` advertised is `conf.oauth.issuer` — set it to the **browser-facing**
|
||||
HTTPS URL the SSO is served at (e.g. `https://sso.example.com`), either in
|
||||
`conf/secrets.js` or via `app_oauth__issuer` / `OAUTH_ISSUER`.
|
||||
|
||||
## OAuth clients
|
||||
|
||||
An OAuth client represents an app that authenticates against the SSO. Each has:
|
||||
|
||||
- `client_id` (UUID) + `client_secret` (bcrypt-hashed; the **raw secret is
|
||||
shown once** when the client is created or rotated — save it immediately).
|
||||
- `name`, `description`, `created_by` (the admin uid that created it).
|
||||
- `redirect_uris` — allowed callback URLs. Each entry matches exactly, or may
|
||||
use `*` (one hostname label) / `**` (any number of labels) as a wildcard —
|
||||
e.g. `https://*.example.com/__proxy_auth/callback` covers every host
|
||||
theta42/proxy fronts under `example.com`, so you don't have to register
|
||||
each proxied host's callback individually.
|
||||
- `scopes` — requested scopes (default `openid profile email groups`).
|
||||
- `allowed_groups` — restrict the client to members of specific SSO groups
|
||||
(empty = any valid user).
|
||||
- `token_lifetime` — `access_token` / `refresh_token` lifetimes (seconds).
|
||||
|
||||
### Managing clients
|
||||
|
||||
Clients are managed directly from the **Directory** tab in the web UI. They are modeled as resources of `kind: oauth` and must belong to a parent Service.
|
||||
|
||||
| Action | How to do it |
|
||||
|--------|--------------|
|
||||
| **Create** | Click the green **+** on a parent Service to add a child resource. Choose **OAuth Integration**. The raw `client_secret` is shown once upon creation. |
|
||||
| **Edit** | Click the edit pencil on the OAuth resource in the Directory list or tree. You can update redirect URIs, scopes, allowed groups, and token TTLs. |
|
||||
| **Delete** | Click the trash can on the OAuth resource in the Directory list. |
|
||||
| **Rotate Secret** | Open the edit modal for the OAuth resource and click **Rotate Client Secret**. The new raw secret is shown once. |
|
||||
|
||||
> All client-management actions use the standard Directory API (`/api/directory-admin/resources`) and are gated by the `app_sso_directory_admin` group.
|
||||
|
||||
<a href="images/oauth-clients.png" target="_blank"><img src="images/oauth-clients.png" alt="Editing an OAuth client resource" width="80%"></a>
|
||||
|
||||
## Scopes
|
||||
|
||||
| Scope | Claims / access |
|
||||
|-------|-----------------|
|
||||
| `openid` | OIDC ID token + discovery |
|
||||
| `profile` | `preferred_username`, display name, etc. |
|
||||
| `email` | the user's `mail` |
|
||||
| `groups` | the user's group memberships (the `groups` claim) |
|
||||
|
||||
The `groups` claim is what relying parties (e.g. the proxy's
|
||||
`app_auth__adminGroups`) use to map group membership to roles.
|
||||
|
||||
## Token lifetimes
|
||||
|
||||
Defaults (overridable per-client via `token_lifetime`, or globally via
|
||||
`app_oauth__token_lifetime__access_token` /
|
||||
`app_oauth__token_lifetime__refresh_token`):
|
||||
|
||||
- access token: 3600s (1 hour)
|
||||
- refresh token: 2592000s (30 days)
|
||||
|
||||
## Admin gating
|
||||
|
||||
SSO admin actions are gated by LDAP group membership (checked via the group's
|
||||
`member` list, not `memberOf` on the user):
|
||||
|
||||
- `app_sso_admin` — full admin (users, groups, settings).
|
||||
- `app_sso_oauth_admin` — OAuth client management.
|
||||
- `app_sso_invite` — invitation management.
|
||||
|
||||
The bootstrap in [theta-env](https://github.com/theta42/theta-env) creates your
|
||||
first admin and adds them to `app_sso_admin` + `app_sso_oauth_admin`
|
||||
automatically; for a standalone install, add the admin's DN to those groups
|
||||
manually (or via `ops/ldap-setup.sh`).
|
||||
|
||||
## JWT signing
|
||||
|
||||
Tokens are signed with `conf.oauth.jwtSecret` (`app_oauth__jwtSecret` /
|
||||
`JWT_SECRET`). **Persist this secret** — if it changes, every issued token
|
||||
stops validating. The all-in-one Docker image auto-generates one if none is set,
|
||||
but that generated value does not survive container recreation unless you
|
||||
persist it (set `JWT_SECRET` in your `.env`).
|
||||
|
||||
[← Back to Home](index.html)
|
||||
+132
@@ -0,0 +1,132 @@
|
||||
# Plugins
|
||||
|
||||
The SSO Manager runs **plugins** as scheduled background tasks. A plugin
|
||||
**type** is an installed module; a plugin **instance** is a configured, loadable
|
||||
copy of a type. You can create, edit, load/unload, run, and delete instances
|
||||
from the **Plugins** page (or the `/api/plugins` API), and you can run several
|
||||
instances of the same type — e.g. two Proxmox endpoints, each with its own URL
|
||||
and token on its own schedule.
|
||||
|
||||
Per-instance **secrets** are stored in [OpenBao](https://openbao.org/) at
|
||||
`secret/plugins/<instance-id>/conf`, not in `sso-secrets.js`. The admin UI only
|
||||
ever shows them masked (`********`); the plugin reads them at run time. This
|
||||
needs theta-suite ≥ v1.30.1 (which grants the `sso-broker` OpenBao policy
|
||||
`secret/plugins/*`); re-run `./setup.sh` after upgrading.
|
||||
|
||||
## Plugin types
|
||||
|
||||
A plugin type is a module under `nodejs/plugins/<category>/<type>.js`. The
|
||||
filename basename (without `.js`) is the `type`; the parent directory is the
|
||||
`category`. The built-ins ship under `plugins/discovery/`:
|
||||
|
||||
- `proxmox` — Proxmox VE (URL + API token)
|
||||
- `unifi` — UniFi Network controller (URL + username/password)
|
||||
- `nmap` — nmap OS + port scan (a target range; no credentials)
|
||||
|
||||
A module exports a **manifest**:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
// Identity — `type`/`category` default to the file/dir name but can be set
|
||||
// explicitly. `name`/`description` show up in the UI.
|
||||
type: 'proxmox',
|
||||
category: 'discovery',
|
||||
name: 'Proxmox VE',
|
||||
description: 'Discover VMs, containers, and nodes from a PVE endpoint.',
|
||||
|
||||
// Drives the admin UI form, API validation, and secret masking. Fields with
|
||||
// `secret: true` are stored in OpenBao; the rest live in the DB row.
|
||||
configSchema: [
|
||||
{ key: 'url', label: 'API URL', type: 'url', required: true },
|
||||
{ key: 'tokenId', label: 'Token ID', type: 'text', required: true },
|
||||
{ key: 'tokenSecret', label: 'Token Secret', type: 'password', required: true, secret: true }
|
||||
],
|
||||
|
||||
// "Test" button: validate the config (don't do the work). Return
|
||||
// { ok: true } or { ok: false, error: '...' }. Optional.
|
||||
validate: async (config) => { … },
|
||||
|
||||
// The work. `run` is the generalized contract name; the discovery plugins
|
||||
// also keep `discover` as an alias for back-compat. For `category:
|
||||
// 'discovery'`, the scheduler passes the result to the discovery reconciler.
|
||||
run: async (config) => { return { resources, edges }; },
|
||||
discover: async (config) => { return { resources, edges }; }
|
||||
};
|
||||
```
|
||||
|
||||
`run(config)` receives the merged non-secret config + secret values as one flat
|
||||
object (e.g. `{ url, tokenId, tokenSecret }`). For a discovery plugin it
|
||||
returns `{ resources, edges }`; the reconciler upserts them into the resource
|
||||
graph attributed to the instance's **slug** (the `discovery_sources` name).
|
||||
|
||||
### Writing a custom plugin type
|
||||
|
||||
Drop a `.js` file under `nodejs/plugins/discovery/` (or a new category directory)
|
||||
following the manifest above. New types are picked up at boot, so restart the
|
||||
SSO Manager after adding one. Runtime load/unload is per-**instance** only —
|
||||
adding a new type still needs a restart.
|
||||
|
||||
## The Plugins page
|
||||
|
||||
Under **Plugins** (nav, admin-only — `app_sso_admin` / `app_sso_directory_admin`
|
||||
/ `app_super_admin`):
|
||||
|
||||
- **New Plugin** — pick a type, name it, choose a unique slug (the discovery
|
||||
source name + the URL the resource graph attributes results to), set a cron
|
||||
schedule, and fill in the config form (secret fields are password inputs).
|
||||
Creating it schedules it and kicks one immediate run.
|
||||
- **Edit** — name, cron, and non-secret config.
|
||||
- **Edit Secrets** (key icon) — password fields, prefilled masked. Leave a
|
||||
field blank to keep its current value.
|
||||
- **Test** (vial icon) — runs the plugin's `validate`.
|
||||
- **Run now** (play icon) — enqueues one immediate run regardless of state.
|
||||
- **Load / Unload** — enable/disable the schedule without deleting the instance.
|
||||
- **Delete** — removes the schedule, the OpenBao secret namespace, and the row.
|
||||
|
||||
## API
|
||||
|
||||
All endpoints are mounted at `/api/plugins`, require an authenticated admin
|
||||
(`app_sso_admin` / `app_sso_directory_admin` / `app_super_admin`), and return
|
||||
secret values masked.
|
||||
|
||||
| Method + path | Purpose |
|
||||
|---|---|
|
||||
| `GET /api/plugins/types` | list installed plugin types + their `configSchema` |
|
||||
| `GET /api/plugins` | list instances (with masked secrets + last-run state) |
|
||||
| `GET /api/plugins/:id` | one instance |
|
||||
| `POST /api/plugins` | create — body `{ pluginType, name, slug, cron, config }` where `config` is a flat object of all field values; secret fields are split into OpenBao |
|
||||
| `PUT /api/plugins/:id` | update name/cron/enabled + non-secret config |
|
||||
| `PUT /api/plugins/:id/secrets` | update secret fields (blank = keep) |
|
||||
| `POST /api/plugins/:id/test` | run `validate` → `{ ok }` or `{ ok:false, error }` |
|
||||
| `POST /api/plugins/:id/load` | enable + schedule + run now |
|
||||
| `POST /api/plugins/:id/unload` | unschedule + disable |
|
||||
| `POST /api/plugins/:id/run` | enqueue one immediate run |
|
||||
| `DELETE /api/plugins/:id` | unschedule + remove OpenBao secrets + delete row |
|
||||
| `GET /api/plugins/:id/runs` | `{ lastRunAt, lastStatus, lastError }` |
|
||||
|
||||
## Scheduler internals
|
||||
|
||||
The scheduler ([BullMQ](https://docs.bullmq.io/) over Redis) gives each instance
|
||||
a stable JobScheduler id (`plugin:<instanceId>`); load/unload upsert/remove
|
||||
that one schedule without disturbing the others. A daily `garbage_collect` job
|
||||
prunes discovery resources not seen in > 7 days.
|
||||
|
||||
### Legacy migration
|
||||
|
||||
Before this system, plugins were configured statically in `sso-secrets.js`:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
discovery: {
|
||||
plugins: {
|
||||
proxmox: { enabled: true, cron: '0 * * * *', url: '…', tokenId: '…', tokenSecret: '…' }
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
On the first boot of SSO Manager ≥ v1.17.0, if the `PluginInstance` table is
|
||||
empty **and** `conf.discovery.plugins` has entries, one instance per configured
|
||||
type is seeded automatically (secret fields copied into OpenBao). After that the
|
||||
table is non-empty and the static config is ignored — manage plugins from the
|
||||
UI/API instead. The migration is idempotent (guarded by the empty-table check).
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
layout: default
|
||||
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.
|
||||
|
||||
## 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.
|
||||
- **Low Latency**: Applications at a remote site can bind directly to their local LDAP server (`localhost` or LAN IP) instead of traversing the internet to query the primary site, making logins blazing fast.
|
||||
- **Independent Failure Domains**: By replicating only the LDAP directory (the source of truth) and keeping session state (Redis) independent, you prevent complex "split-brain" scenarios in the web UI. A failure at Site A won't bring down Site B.
|
||||
|
||||
By default, the `sso-manager` Docker container runs a single, independent OpenLDAP instance. However, you can enable **N-Way Multi-Master Replication** via environment variables.
|
||||
|
||||
## How it works
|
||||
|
||||
In an N-Way Multi-Master setup, every site runs a fully active OpenLDAP server (`slapd`).
|
||||
- **Reads and Writes anywhere**: A user can change their password or update their profile at Site A, Site B, or Site C.
|
||||
- **Conflict Resolution**: OpenLDAP's `syncrepl` engine uses Context Sequence Numbers (CSN) to track changes. If Site A goes offline and a user changes their password at Site B, Site A will automatically pull the newest changes the moment it rejoins the cluster.
|
||||
- **Independent Redis**: Session data, API Tokens, and OAuth Clients are stored in Redis. By design, Redis is NOT replicated in this geographic setup. This ensures that a failure at Site A never causes Site B's Redis to become read-only, which would break the web UI at Site B. OAuth clients must be configured per-site.
|
||||
|
||||
## Configuration
|
||||
|
||||
To enable replication, you must pass two environment variables to the `sso-manager` container:
|
||||
|
||||
1. `LDAP_SERVER_ID`: A unique integer for this node (e.g., `1`, `2`, `3`). This MUST be unique across the cluster.
|
||||
2. `LDAP_REPLICATION_HOSTS`: A space-separated list of the LDAP URLs of all **other** nodes in the cluster.
|
||||
|
||||
### Example using `theta-env` / Docker Compose
|
||||
|
||||
**Site 1 (`setup.env` or `docker-compose.yml`)**
|
||||
```env
|
||||
LDAP_SERVER_ID=1
|
||||
LDAP_REPLICATION_HOSTS="ldaps://sso.site2.com:636 ldaps://sso.site3.com:636"
|
||||
```
|
||||
|
||||
**Site 2 (`setup.env` or `docker-compose.yml`)**
|
||||
```env
|
||||
LDAP_SERVER_ID=2
|
||||
LDAP_REPLICATION_HOSTS="ldaps://sso.site1.com:636 ldaps://sso.site3.com:636"
|
||||
```
|
||||
|
||||
**Site 3 (`setup.env` or `docker-compose.yml`)**
|
||||
```env
|
||||
LDAP_SERVER_ID=3
|
||||
LDAP_REPLICATION_HOSTS="ldaps://sso.site1.com:636 ldaps://sso.site2.com:636"
|
||||
```
|
||||
|
||||
Once configured, the container's entrypoint will automatically load the `syncprov` module, enable `mirrormode`, and generate the necessary `syncrepl` blocks in `/etc/openldap/slapd.conf`.
|
||||
|
||||
## User Locations
|
||||
|
||||
When creating or editing a user, you can specify their **Location (Site)**. This maps directly to the standard LDAP `l` (localityName) attribute, allowing you to track which physical site a user belongs to natively within the directory.
|
||||
@@ -0,0 +1,4 @@
|
||||
User-agent: *
|
||||
Allow: /
|
||||
|
||||
Sitemap: https://theta42.github.io/sso-manager-node/sitemap.xml
|
||||
@@ -0,0 +1,38 @@
|
||||
# Vault Secrets Management
|
||||
|
||||
The Vault Secrets feature integrates with OpenBao to provide a secure key-value store for your environment. It allows you to store sensitive information like passwords, API keys, and credentials, ensuring they are encrypted and access-controlled.
|
||||
|
||||
## Usage
|
||||
|
||||
You can access the Vault UI from the application's top navigation bar.
|
||||
|
||||
### Creating Secrets
|
||||
|
||||
1. Click on the **New Secret** button.
|
||||
2. Enter a **Secret Path**. This acts as the name/identifier of your secret (e.g., `db-credentials`).
|
||||
3. Enter the **Secret Data** in JSON format. For example:
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "supersecretpassword123"
|
||||
}
|
||||
```
|
||||
4. Click **Save Secret**.
|
||||
|
||||
### Reading and Editing Secrets
|
||||
|
||||
* To view a secret, click on its name in the **Secrets List**.
|
||||
* To update an existing secret, select it and click the **Edit** button. You can then modify the JSON data and save your changes.
|
||||
|
||||
### OpenBao Integration
|
||||
|
||||
The secrets are stored in an OpenBao backend configured in development mode. The default KV (Key-Value) version 2 engine is mounted at `secret/`. The built-in UI uses the `/api/vault/secret/` API endpoints to interact with OpenBao.
|
||||
|
||||
## API Access
|
||||
|
||||
If you need to programmatically access the secrets, you can interact directly with the OpenBao API using the root token (in dev mode):
|
||||
|
||||
```bash
|
||||
# Example: Read a secret via the API
|
||||
curl -H "X-Vault-Token: root" -H "Authorization: Bearer <your-sso-token>" http://<your-sso-host>/api/vault/secret/data/<your-secret-path>
|
||||
```
|
||||
Reference in New Issue
Block a user