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

docs(swarm): one page saying where every secret goes

Browse source 
Per mara on the CA question: outside all-local this is an ops problem,
and what is missing is documentation rather than machinery.

One row per secret, read against three topologies, because the same
credential is generated in place on one and handed over by an operator on
another. sso.md's table is replaced by a pointer -- two tables listing the
same secrets would drift, and its prose about why a secret is generated
in-container is the half worth keeping there.

States the constraint the whole thing rests on: a hive CA is name-
constrained to the hive domain and a swarm service name is a sibling of
it, so a hive CA cannot issue a swarm-service certificate at all. That is
why placing the swarm root is an operations decision.
This commit is contained in:
atlas 2026-08-14 12:04:20 +02:00 • committed by mara
commit c39e94758e
3 changed files with 105 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/swarm/sso.md
View file

@ -90,17 +90,16 @@ 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** |
Every secret in the swarm, with its generator and its path, is tabulated
in one place: [`secrets.md`](secrets.md). The rows relevant here are
authelia's own keys (session, JWT, storage-encryption, OIDC HMAC, OIDC
issuer) plus the two halves of each client secret.
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
What matters for this page is the shape rather than the paths. Authelia's
own keys are generated **in-container**, because nothing outside that
container ever reads them — that is the test worth applying to any secret
added here. The plaintext half of a client secret is the one that fails
it: its reader lives in a different container, and that is the entire
reason a delivery step exists.
**None of it is ever written into a nix expression.** authelia's