vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(3083): getting into the SSO provider the first time

Browse source 
The vhost half of this change is only useful with an account behind it,
and the provider is generated with an empty user set on purpose. Document
the `swarmctl user add` step rather than automating it: bootstrapping an
IdP non-interactively means a secret arriving from a file, an env var or a
nix expression, all worse than one command typed once.

The gateway and network pages gain the rows they would otherwise be
missing — vhost map, local-dev hosts entry, and the resolver's
authoritative-name list.
This commit is contained in:
atlas 2026-08-11 22:41:41 +02:00 • committed by mara
commit 660629a7c6
3 changed files with 38 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/swarm/sso.md
View file

@ -10,6 +10,38 @@ The second role is derived rather than switched:
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).)
Reachable is not the same as usable: the provider is generated with an
empty user set, deliberately. A provider with nobody in it yet is the
correct state for a fresh swarm — it is not a half-finished install, and
seeding a default account would be a credential in a config file.
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.
## What secrets exist, and where each one lives
| secret | generated by | rests in | read by |