24ee0990a2
`user add` refuses on an existing name, so the `--group` flag it takes at creation time could not be added afterwards at all: repairing an account meant hand-editing both users.json and the rendered users.yml as root. mara, on #3167: "i will not edit those files by hand, we will have the same issues elsewhere". The merge rules live in users.rs as a pure function over a UserUpdate, so they are testable without a command line, a container or a running authelia — main.rs's arm only loads, applies, publishes and prints. Removals are strict and everything else is idempotent, which is the one asymmetry here and is deliberate: a --remove-group naming a group the user does not have fails, because a revocation that reports success without revoking is the outcome nobody re-checks; while refusing an already-satisfied set would make the multi-attribute call this verb exists for break whenever one of the values was already right. A command that changes nothing at all still fails — it would otherwise rewrite both files and restart the SSO provider to no effect. Passwords are out of scope: regenerating a credential is a different intent from editing an attribute, and folded together an attribute edit can invalidate a login by accident. Extracts publish() from user_add so both verbs share the render -> store -> users.yml -> restart ordering and the comment that explains why that order, rather than the second verb copying it.
170 lines
7.4 KiB
Markdown
170 lines
7.4 KiB
Markdown
# Swarm SSO
|
|
|
|
The swarm runs one authelia, and it is two things at once: the **session
|
|
provider** every protected vhost checks (`auth_request`), and — once any
|
|
client is declared — an **OIDC provider** issuing tokens to relying
|
|
parties like the forge.
|
|
|
|
The second role is derived rather than switched:
|
|
`services.hyperhive.swarm.authelia.oidc.clients` being non-empty turns it
|
|
on. authelia refuses to start with a provider that has no clients, so a
|
|
separate `enable` would be a second fact free to disagree with the first.
|
|
|
|
## Getting in the first time
|
|
|
|
authelia binds loopback only. The **gateway** on the host running it
|
|
publishes it as `auth.<swarm.domain>` — vhost, dnsmasq record and TLS
|
|
name all follow `swarm.authelia.enable`, so there is nothing to turn on
|
|
separately. (Details, including why a client hive must not declare that
|
|
vhost: [`../gateway.md`](../gateway.md).)
|
|
|
|
**Authelia does not start until at least one user exists.** The user
|
|
store is generated empty — deliberately, since seeding a default account
|
|
would put a credential in a config file — but authelia validates it at
|
|
startup and treats "no users" as fatal:
|
|
|
|
```
|
|
error reading the authentication database: could not validate the schema:
|
|
users: non zero value required
|
|
```
|
|
|
|
It then exits 1 and systemd restarts it, so a swarm that has been
|
|
enabled but not bootstrapped shows a **crash-looping unit** and `502 Bad
|
|
Gateway` from the vhost — not a login page with nobody able to use it.
|
|
The gateway is working in that state; the upstream is not up.
|
|
|
|
⚠️ So the step below is **required to finish the install**, not an
|
|
optional first-login convenience. Run it before concluding anything is
|
|
wrong with the proxy: a 502 here means "no users yet" far more often
|
|
than it means a routing fault.
|
|
|
|
Add the first subject on the host running authelia:
|
|
|
|
```console
|
|
# swarmctl user add mara --display-name Mara --email mara@example.com --group admins
|
|
added mara to /var/lib/authelia-swarm/users.yml
|
|
password: <generated>
|
|
this password is stored nowhere — record it now
|
|
```
|
|
|
|
The password is generated, hashed, and printed once; only the hash is
|
|
kept. `swarmctl` writes its canonical `users.json`, re-renders authelia's
|
|
`users.yml` from it, and restarts authelia. Full reference:
|
|
[`../tools/swarmctl-cli.md`](../tools/swarmctl-cli.md).
|
|
|
|
This step stays manual on purpose. Bootstrapping an identity provider
|
|
non-interactively means a secret arriving from somewhere — a file, an
|
|
env var, a nix expression — and every one of those is worse than an
|
|
operator typing one command once.
|
|
|
|
### Changing a subject afterwards
|
|
|
|
`user add` only ever adds: on a name that already exists it refuses,
|
|
rather than resurfacing as a second account or a silent overwrite.
|
|
Editing an existing subject is `user update`, and the flags compose, so
|
|
one call can change several things:
|
|
|
|
```console
|
|
# swarmctl user update mara --add-group admins --email mara@example.com
|
|
added to group "admins"
|
|
email: unset -> "mara@example.com"
|
|
mara is now in groups: admins
|
|
```
|
|
|
|
Two behaviours worth knowing before you rely on them:
|
|
|
|
- **`--remove-group` fails if the user is not in that group.** Every
|
|
other flag is idempotent — setting what is already set is fine, so a
|
|
"make these four things true" call does not break when one of them
|
|
already was. Revocation is the exception on purpose: a typo'd group
|
|
name that reported success would leave an account holding access you
|
|
believe you took away, and that is the one outcome nobody re-checks.
|
|
- **The resulting group list is printed** because group names have no
|
|
registry anywhere. A misspelled `--add-group` creates a real group that
|
|
no access-control rule mentions, so the user gains nothing and no error
|
|
is possible — reading the line back is the only check there is.
|
|
|
|
Passwords are deliberately out of scope here: regenerating a credential
|
|
is a different intent from editing an attribute, and folding them means
|
|
an attribute edit can invalidate a login by accident.
|
|
|
|
## What secrets exist, and where each one lives
|
|
|
|
| secret | generated by | rests in | read by |
|
|
|---|---|---|---|
|
|
| `jwt.key`, `session.key`, `storage-encryption.key` | authelia's first-boot unit | `/var/lib/authelia-swarm/` | authelia |
|
|
| `oidc-hmac.key` | same unit | same directory | authelia |
|
|
| `oidc-issuer.key` (RSA) | same unit | same directory | authelia signs with it; clients verify the **public** half at `/jwks.json` |
|
|
| `oidc-clients/<id>.digest` | same unit, via `authelia crypto hash generate` | same directory, merged in through `settingsFiles` | authelia |
|
|
| `oidc-clients/<id>.secret` | the same mint — this is its plaintext half | same directory | **the relying party, in another container** |
|
|
|
|
Everything above the last row is generated in-container because nothing
|
|
outside that container ever reads it. That is the test worth applying to
|
|
any secret added here. The last row fails it, and that is the entire
|
|
reason a delivery step exists.
|
|
|
|
**None of it is ever written into a nix expression.** authelia's
|
|
`settings` are rendered into the nix store, which is world-readable and
|
|
permanent, so the client digest reaches authelia through `settingsFiles`
|
|
(merged at runtime) and every other secret through a `*File` option
|
|
carrying a path rather than a value.
|
|
|
|
## Getting the plaintext to the relying party
|
|
|
|
Three cases, and they are genuinely different mechanisms rather than one
|
|
mechanism with flags.
|
|
|
|
### 1. All-local — one host runs both
|
|
|
|
Nothing to configure beyond `swarm.forge.sso.enable = true`. A host-side
|
|
unit waits for authelia's first boot to mint the secret and copies it
|
|
into the forge container, and the forge module contributes its own client
|
|
entry — callback URL included — to authelia's client list.
|
|
|
|
The callback is built from the same source name the registration uses, so
|
|
the redirect URI authelia is told to allow and the one forgejo actually
|
|
sends cannot drift apart. A mismatch there is a rejected login with no
|
|
error text worth reading.
|
|
|
|
⚠️ The delivery is a copy, not a `bindMounts` entry, and deliberately so:
|
|
nixos-container refuses to start a container whose bind source is
|
|
missing, and this secret does not exist until authelia's first boot has
|
|
run. Binding it would make the forge wait on a file that waits on a
|
|
container that starts after it — on a fresh hive, a permanent stall
|
|
presenting as "the forge is broken", several layers from its cause.
|
|
|
|
### 2. Swarm-managed services
|
|
|
|
The controller side owns provisioning: `swarmctl` writes both halves, the
|
|
same way it already owns authelia's user store (`users.json` canonical,
|
|
`users.yml` a rendered artifact).
|
|
|
|
### 3. A hive elsewhere
|
|
|
|
No shared host, so no automatic path. The operator provides the file and
|
|
names it:
|
|
|
|
```nix
|
|
services.hyperhive.swarm = {
|
|
authelia.url = "https://auth.example.com";
|
|
forge.sso = {
|
|
enable = true;
|
|
clientSecretFile = "/var/lib/hyperhive/forge-oidc-secret";
|
|
};
|
|
};
|
|
```
|
|
|
|
**Both are asserted at eval.** A hive that boots with SSO
|
|
half-configured shows a login button that always fails — a symptom
|
|
several layers from its cause, and far worse to diagnose than an
|
|
evaluation error.
|
|
|
|
## What this does not do
|
|
|
|
- **It does not disable local login.** The forge keeps its password
|
|
database and gains a second door. An identity provider that can take
|
|
the forge offline when it hiccups is a worse forge than one with two
|
|
ways in.
|
|
- **It does not provision users.** Agents are created and destroyed
|
|
continuously, so the subject set belongs to a program rather than to a
|
|
config file; today that program is `swarmctl`.
|