hyperhive/swarm-authelia-bridge

swarm-authelia-bridge

The only thing allowed to write swarm-authelia's users database.

Why this exists

swarm-controller's CreateIdentity job needs to add an agent as an authelia subject, but swarm-controller runs unprivileged and does not own users.yml — a different uid does (authelia-swarm, the user services.authelia.instances.swarm runs as). Root/CAP_CHOWN/a shared group were all examined and rejected during this crate's design thread — see swarmctl/README.md's identical analysis of this same file, written before this crate existed.

The fix: run this process as User = "authelia-swarm"; instead — inside the swarm-authelia container, alongside authelia itself — so it simply owns the file it writes. No elevated privilege anywhere.

Shape

• One endpoint, POST /requests, body = swarm-authelia-bridge-sock's BridgeRequest verbatim — EnsureAgentIdentity (idempotently ensure an agent exists as an authelia subject), ListAgentIdentities (the roster: the subjects carrying the agent marker group, names only) and ListOperators (the operator group's usernames).
• Bearer-authenticated via authelia's own OIDC token introspection (RFC 7662), against swarm-controller's existing machine-client identity (already minted for the queue connection) — no new credential. The two agent verbs admit any active token. ⚠️ ListOperators admits only the client named by SWARM_AUTHELIA_BRIDGE_OPERATOR_READER_CLIENT_ID (swarm-controller's) and answers every other active token 403: authelia issues machine tokens to every hive and its agents too.
• No restart of authelia after a write — relies on authentication_backend.file.watch, confirmed working against the pinned 4.39.20 build during this design work.
• Network-facing rather than unix-socket-only: swarm-authelia's container shares the host netns, so the same listener serves both a co-located swarm-controller (loopback) and a split-host one (bind wider + firewall) with no separate transport.

One store, two writers

This bridge and swarmctl both read and write authelia's users.yml directly. That is the whole arrangement — neither keeps a private copy it considers canonical.

It used to be otherwise, and the seam was real: each side had its own users.json treated as authoritative, rendering the same physical users.yml. A writer whose own JSON was missing could not tell "nothing here yet" from "someone else's users", so it refused to write at all — which is exactly what a hive with existing users hit.

What still has to hold, since two processes share the file:

• Read before write. Both do, so neither can drop a user the other added between operations.
• Unknown keys survive. Both carry unmodelled top-level and per-user fields through a round-trip, or whichever writes second would silently delete what the first added.
• Every user gets an email. A relying party asking for the claim fails rather than degrades, so both write paths fill in a synthetic address when none was supplied.

Neither restarts authelia: it watches the file. swarmctl could (it is root); this bridge deliberately cannot, and a reload that depends on which process wrote is not a reload.