5 Group and Role Based Access Control
vBlackOut edited this page 2026-08-26 07:48:04 +02:00

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_users on a vhosts: 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: leaving username/groups/roles empty here means "any authenticated account may use this route," while leaving allow_users/allow_groups/allow_roles empty 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 way user_roles still works) needs a mass UPDATE across 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/⚠ OPEN routes).
  • 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