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. ⚠️ Every request admits only the client named by SWARM_AUTHELIA_BRIDGE_CONTROLLER_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.
• Listens on loopback. The authelia vhost proxies /bridge/ to it with the prefix stripped, so swarm-controller on any host calls https://<swarm.authelia.domain>/bridge/requests.

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:

• One lock around read → write. Both take an exclusive flock on users.yml.lock, a sibling file in the same directory, before loading and hold it until the rename lands, waiting at most 10 seconds. Reading the file first is not enough: both writers spend about a second minting a password between load and write, and the second rename would drop the first writer's user. The lock file is opened O_NOFOLLOW, so a symlink cannot point either side at another file. swarmctl is root: it refuses an existing lock file with more than one hard link, and it changes the owner of a lock file only when it created that file in the same call, handing it to the directory's owner so the bridge can open it. The bridge opens the lock read-only, which is all flock needs.
• 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.