From c75604aa426ddb294a882233292874db76e301ee Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 05:20:57 +0200 Subject: [PATCH] docs: clear write-good.Passive hits in docs/swarm/sso.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 6 genuine passive-voice rewrites (actor named — the operator, secrets.md, swarm-authelia.nix, the person who introduced the split, swarmctl); 1 false positive left untouched — a quoted phrase + predicate adjective ('presenting as "the forge is broken"'). --- docs/swarm/sso.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/swarm/sso.md b/docs/swarm/sso.md index 4054d120..991471ad 100644 --- a/docs/swarm/sso.md +++ b/docs/swarm/sso.md @@ -1,9 +1,9 @@ # Swarm SSO The swarm runs one authelia, and it's 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: the forge and the matrix homeserver. +provider** every protected vhost checks (`auth_request`), and — once an +operator declares any client — an **OIDC provider** issuing tokens to +relying parties: the forge and the matrix homeserver. The second role derives rather than switches: `services.hyperhive.swarm.authelia.oidc.clients` being non-empty turns it @@ -28,7 +28,7 @@ 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 +It then exits 1 and systemd restarts it, so a swarm the operator has 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 isn't up. @@ -95,8 +95,8 @@ an attribute edit can invalidate a login by accident. ## What secrets exist, and where each one lives -Every secret in the swarm, with its generator and its path, is tabulated -in one place: [`secrets.md`](secrets.md), including authelia's own keys +[`secrets.md`](secrets.md) tabulates every secret in the swarm, with its +generator and its path, in one place — including authelia's own keys (session, JWT, storage-encryption, OIDC HMAC, OIDC issuer) and the two halves of each client secret. That page's two rules — a secret is always a path, never a value, and the generator and the reader typically live in @@ -115,9 +115,11 @@ authelia's first boot to mint that client's secret and copies it into the service's container, and the service's own module contributes its client entry — callback URL included — to authelia's client list. -The callback is built once and read twice, so the redirect URI authelia -accepts and the one the service actually sends can't drift apart. A -mismatch there is a rejected login with no error text worth reading. +Each relying service's own glue module builds its callback once, and +both authelia's client list and the service's own OIDC client config +read that same value, so the redirect URI authelia accepts and the one +the service actually sends can't 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 @@ -238,7 +240,7 @@ upstream and compare three requests, not one: All three matter. A change that silently deleted the browser page would pass a deny-only check, and one that quietly stopped denying would pass a -page-only check. This was verified that way when the split was introduced. +page-only check. The person who introduced the split verified it this way. ## What this doesn't do @@ -254,6 +256,6 @@ page-only check. This was verified that way when the split was introduced. door, and a dead provider locks everyone out, the built-in admin included. That's why `swarm.grafana.oidc.role` defaults to `Admin`; see [`services.md`](services.md#metrics-victoriametrics--grafana). -- **It doesn't 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`. +- **It doesn't provision users.** `swarmctl` creates and destroys agents + continuously today, so the subject set belongs to a program rather + than to a config file.