docs(3083): getting into the SSO provider the first time
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
mara
parent
67a20d387f
commit
660629a7c6
3 changed files with 38 additions and 1 deletions
|
|
@ -14,6 +14,9 @@ Single nginx in front of every hyperhive web surface. Runs on the **host**, next
|
|||
| `matrix.<hive>/_matrix/*` | `matrix.<hive>` | tuwunel (`8008`) | `matrix.gatewayHost != null` |
|
||||
| `matrix.<hive>/` | `matrix.<hive>` | fluffychat-web static | `matrix.gui.enable` |
|
||||
| `matrix.<hive>/config.json` | `matrix.<hive>` | inline JSON (FluffyChat boot config) | `matrix.gui.enable && domain != null` |
|
||||
| `auth.<swarm>/` | `auth.<swarm>` | authelia (`9091`) | `swarm.authelia.enable` |
|
||||
|
||||
The authelia vhost is declared only by the host that **runs** authelia, not by every hive that uses it — a client hive knows the swarm's `authelia.url` but must not answer for a name it doesn't serve. Its server name is exactly `swarm.authelia.domain`: authelia validates `authelia_url ⊂ session cookie domain` at startup, so a near-miss is a container that refuses to boot. It carries no `auth_basic` — the login page must not sit behind the login mechanism it replaces — and sets the four `X-Forwarded-{Proto,Host,Uri,For}` headers, since authelia decides by the *original* request rather than the hop it sees.
|
||||
|
||||
Per-agent UIs stay sub-path because they're hyperhive-internal and base-path-aware. External standard apps (forge / matrix) get sub-domains because their defaults work cleanly at sub-domain root + per-origin cookies / storage isolation matters.
|
||||
|
||||
|
|
@ -57,6 +60,7 @@ Each location carries a duplicated `auth_basic` block (separate locations don't
|
|||
- `<hive-domain>` → `127.0.0.1`
|
||||
- `forge.<hive>` → `127.0.0.1` (when forge.behindGateway)
|
||||
- `matrix.<hive>` → `127.0.0.1` (when matrix.gatewayHost set)
|
||||
- `auth.<swarm>` → `127.0.0.1` (when swarm.authelia.enable)
|
||||
|
||||
`lib.unique` de-dupes if any sub-domain happens to equal another entry. Operators with real DNS leave it off.
|
||||
|
||||
|
|
|
|||
|
|
@ -113,7 +113,8 @@ schemes pick their own.
|
|||
## Resolver behaviour
|
||||
|
||||
dnsmasq is **authoritative** for the hive's own zones — answers
|
||||
`<hive-domain>`, `forge.<hive-domain>`, `matrix.<hive-domain>`
|
||||
`<hive-domain>`, `forge.<hive-domain>`, `matrix.<hive-domain>` and —
|
||||
on the host running it — the swarm's `auth.<swarm-domain>`
|
||||
queries with the bridge IP (where nginx is reachable). Everything
|
||||
else is forwarded to the host's own resolvers: dnsmasq runs on the host
|
||||
and reads the host's `/etc/resolv.conf` directly. Containers don't need
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
Loading…
Reference in a new issue