Table of contents
Group- and Role-Based Access Control (groups, roles)
This page explains ProxyAuth's group and role mechanisms for route access — alternatives to enumerating individual usernames on every route, for when the same set of people needs access to many routes and maintaining a per-route username list by hand doesn't scale.
A user reaches a route if any of three conditions hold: their username is explicitly listed, they belong to an allowed group, or they hold an allowed role. All three live on routes.yml; groups/roles are checked against fields on the User object in config.json (or the equivalent database columns — see Database-Backed Users).
roles predates this page and originally did something different — see Roles vs. groups below for what changed and what didn't.
Not to be confused with vhost login authorization. This page is about route access — what an already-logged-in visitor can reach. A separate, earlier mechanism —
allow_users/allow_groups/allow_roles/exclude_userson avhosts:group — decides whether someone can log in on a given vhost at all, before any route access is even relevant. The two use the same underlying group/role lookups, but the empty-list default is opposite: leavingusername/groups/rolesempty here means "any authenticated account may use this route," while leavingallow_users/allow_groups/allow_rolesempty on a vhost means "nobody can log in here." See routes.yml Reference § Vhost login authorization.
Configuring it
On the account:
{
"username": "alice",
"password": "...",
"roles": ["admin"],
"groups": ["ops", "admins"]
}
On the route, in routes.yml:
routes:
- prefix: /admin
target: http://backend:3000
username: ["dave"]
groups: ["admins"]
roles: ["superadmin"]
| Key | Where | Type | Default | Description |
|---|---|---|---|---|
username |
RouteRule (routes.yml) |
array of strings | [] |
Usernames allowed to access this route. |
groups |
User (config.json) |
array of strings | none | Which groups this account belongs to. |
groups |
RouteRule (routes.yml) |
array of strings | [] |
Which groups may access this route. |
roles |
User (config.json) |
array of strings | none | Which roles this account holds. |
roles |
RouteRule (routes.yml) |
array of strings | [] |
Which roles may access this route. |
dave above reaches /admin because he's listed by name — but so does anyone in the admins group, and so does anyone holding the superadmin role, without their username needing to appear on this route at all.
How the check works
For a route with required_login: true, once the session token is validated:
allowed = rule.username.contains(user)
OR rule.groups.intersects(user.groups)
OR rule.roles.intersects(user.roles)
If none of the three hold, the request is rejected (403 Forbidden on a normal request, 401 Unauthorized with the session cookie cleared on a token-validation failure).
The "all empty" gotcha — read this before relying on it
If username, groups, and roles are all left empty on a route, that's read as a deliberate choice — "any authenticated account may use this route" — not a misconfiguration to fail closed on. required_login still applies regardless (a valid session is mandatory either way); this only concerns which authenticated accounts get through.
The moment even one of the three is non-empty, the route goes back to being allow-listed: only requests matching username/groups/roles get through, same as always. So a route secured only by groups: ["ops"] still rejects everyone not in ops — leaving username/roles empty doesn't loosen it further.
This is the opposite of what an empty allow-list usually means in most systems, so it's worth internalizing: on this specific route, "nothing configured" and "wide open" are the same thing. Use proxyauth routes-audit to see, at a glance, every route currently in that state across your whole route table.
Both usernames/groups/roles resolution happen through the same lookup path (AppConfig::groups_for_username/roles_for_username — O(1) average-case HashMap lookups, not a scan over every account), so adding groups/roles checks costs nothing measurable on the request path over the username-only check that existed before.
Roles vs. groups
Before route-level roles existed, roles did exactly one thing: get forwarded to the backend as the X-User-Roles header, for the backend to make its own authorization decisions with. ProxyAuth itself never looked at it.
That's still true — X-User-Roles is forwarded on every request that gets through, regardless of whether roles was why it got through. What changed is that a route can now also use roles the same way it uses groups: as a ProxyAuth-enforced gate, not just backend-facing metadata.
groups was deliberately kept as its own separate mechanism rather than folding everything into roles, specifically so a role could keep meaning "informational, backend's call" on routes that don't list it, while still being promotable to "ProxyAuth-enforced" on routes that do — without overloading a single field with two different semantics depending on context.
What the backend sees
Every proxied request carries both headers, comma-separated, independent of which mechanism (if any) actually granted access:
X-User: alice
X-User-Roles: admin
X-Groups: ops,admins
Useful if the backend wants its own authorization logic on top of what ProxyAuth already allowed through, without a second round-trip back to ProxyAuth to ask. As with X-User, an incoming request can't spoof either header — any client-supplied X-User-Roles/X-Groups is stripped before the request is forwarded; the value ProxyAuth computes always wins.
Storage
JSON mode (no databases configured)
groups/roles live directly on the User object in config.json. Nothing else to set up.
Database mode
roles is a simple one-row-per-relationship child table (user_roles, role TEXT) — a role name repeated as text on every row that holds it, same as user_allow.
groups goes one step further: user_groups.group_id is a genuine foreign key into a groups table, not a free-text column:
erDiagram
users ||--o{ user_groups : "membership"
groups ||--o{ user_groups : "membership"
users {
bigint id PK
string username
}
groups {
bigint id PK
string name "UNIQUE"
}
user_groups {
bigint id PK
bigint user_id FK
bigint group_id FK
}
Two practical reasons this matters:
- A typo can't create a phantom group. Misspelling a group name on one account doesn't silently create a group nothing — and no route — will ever match against; it either resolves to the existing group or creates a new, genuinely distinct one, visible as its own row in
groups. - Renaming a group is a one-row
UPDATE. With a shared parent table, renaming affects every member instantly. A free-text-per-row design (the wayuser_rolesstill works) needs a massUPDATEacross every membership row instead.
Assigning a user to a group that doesn't exist yet creates it automatically — an atomic upsert (ensure_group_id in databases/db.rs), not a separate check-then-create with a race between them. Deleting a user cascades to their user_roles/user_groups membership rows; the groups row itself is untouched, since a group definition outlives any one member.
The local LMDB fallback cache needs no special handling for either field — it serializes the whole User object generically, so both ride along automatically the same way every other field does.
Auditing who can reach what
Three CLI commands answer this without needing to poke the running server with real requests — full detail on CLI Reference:
proxyauth routes-audit— every route, what secures it (including flagging⚠ PUBLIC/⚠ OPENroutes).proxyauth check-access --username alice— one account, every route, allowed or denied and why.proxyauth check-routes— the combined view: every route resolved down to the concrete accounts that currently reach it, flagging any route nobody can currently reach at all (almost always a typo in a group/role name).proxyauth users/proxyauth groups/proxyauth roles— inventory: every known account/group/role, one small box-drawing diagram each, showing (respectively) reachable routes, current members, or current holders.
All three call the exact same AppConfig::route_access_decision function the live proxy check calls — not a re-implementation of the same logic that could quietly drift from it over time.
Summary
| Property | Value |
|---|---|
| Config keys | RouteRule.username/groups/roles (routes.yml); User.groups/roles (config.json) |
| Access rule | Allowed if matched by any of the three — logical OR, not AND |
| All three empty | Route is open to any authenticated account — not closed (the one gotcha to remember) |
| Backend visibility | X-User-Roles and X-Groups, comma-separated, both spoof-proof |
| Lookup cost | O(1) average-case HashMap lookup per field, same cost class as the pre-existing username check |
roles database schema |
Free-text column per membership row (user_roles.role) |
groups database schema |
Real FK (groups + user_groups), not a free-text column |
| LMDB cache | No special handling needed — generic User serialization already covers both |
| Audit tooling | routes-audit / check-access / check-routes — same decision logic as production, guaranteed |
See also
- routes.yml Reference — the full
RouteRulefield table. - config.json Reference — the full
Userfield table. - Database-Backed Users — the rest of the account schema (
allow,email) this follows the same conventions as. - CLI Reference —
routes-audit/check-access/check-routesin full detail. - Passing User Identity to Your Backend (X-User/X-User-Roles) — the pre-existing headers
X-Groupsnow sits alongside. - Anti-Replay Protection — a separate, request-signing mechanism; unrelated to this page beyond both being opt-in security layers on top of the base session/token model.
- routes.yml Reference § Vhost login authorization — the earlier, login-time counterpart to this page's route-time access control.
📖 Wiki Home · 💻 Source Code · 🐛 Report an Issue · 📜 License
Found an error or something outdated on this page? Open an issue or submit a PR against the wiki repository.