# RFE: external auth via reverse-proxy headers + group-to-role mapping (prototype branch attached)

**URL:** <https://forum.genieacs.com/t/rfe-external-auth-via-reverse-proxy-headers-group-to-role-mapping-prototype-branch-attached/7373>\
**Category:** Uncategorized\
**Created:** [April 21, 2026, 6:52pm UTC](https://forum.genieacs.com/t/rfe-external-auth-via-reverse-proxy-headers-group-to-role-mapping-prototype-branch-attached/7373 "2026-04-21T18:52:36Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![ggiesen](https://avatars.discourse-cdn.com/v4/letter/g/f07891/32.png) [@ggiesen](https://forum.genieacs.com/u/ggiesen)\
**Post date:** [April 21, 2026, 6:52pm UTC](https://forum.genieacs.com/t/rfe-external-auth-via-reverse-proxy-headers-group-to-role-mapping-prototype-branch-attached/7373/1 "2026-04-21T18:52:36Z")

</div>

Hi, following up on @zhivkod’s thread, [SSO or User Provisioning](https://forum.genieacs.com/t/5966), with a concrete proposal and a working prototype.

@zaidka - I’ve implemented this against current `master` and would value your input on a few design choices before I polish it into a PR.

Branch here: [GitHub - ggiesen/genieacs at auth/proxy-headers · GitHub](https://github.com/ggiesen/genieacs/tree/auth/proxy-headers)

## What and why

For deployments that need GenieACS to fit into a centralized identity stack (Keycloak, Okta, Entra, FreeIPA, Authelia, etc.), the proposal is to let GenieACS trust authenticated identity + group membership asserted by an upstream reverse proxy, derive roles from groups via a configurable mapping, and JIT-provision the local `users` record with role re-sync on every login. Behaviour is unchanged for deployments that don’t turn the feature on.

## What already works in your code

Reading `lib/ui.ts`, `lib/auth.ts`, and `lib/common/authorizer.ts`, the architecture is already most of the way there:

- The JWT payload carries `{ username, authMethod }` and `lib/ui.ts` explicitly rejects any `authMethod !== "local"`, which suggests the field was designed with other methods in mind.
- The per-request `Authorizer` is built from a role list and has no coupling to the `users` collection - where roles come from is opaque to downstream handlers.
- The `permissions` collection is keyed on role, not user, so only the user-\>role resolution needs an alternate path.

In other words, the change is localized: one new middleware, one small mapping lookup, a relaxed `authMethod` check, and a small schema addition. The authorization pipeline doesn’t move.

Explicit non-goal: native OIDC inside GenieACS. Header-based trust from a proxy is the right level of abstraction; OIDC discovery / JWKS / auth code flow / refresh is what oauth2-proxy, Authelia, and  
Pomerium already do well.

## What the prototype does

### Configuration (five new options, all fail-closed by default)

```auto
UI_AUTH_PROXY_ENABLED = false                                                                                               
UI_AUTH_PROXY_TRUSTED_PROXIES = "" # CIDR list; empty = disabled                                                         
UI_AUTH_PROXY_USER_HEADER = X-Remote-User                                                                                       
UI_AUTH_PROXY_GROUPS_HEADER = X-Remote-Groups                                                                                     
UI_AUTH_PROXY_GROUPS_SEPARATOR = ,                                                                                                   

```

### Middleware behaviour

A new middleware runs after `koa-jwt` (with `passthrough: true`). If the feature is enabled and the request origin IP matches a trusted CIDR and the user header is present, the header is accepted as the authenticated identity. Groups from the groups header are mapped to GenieACS roles through a new `group_roles` MongoDB collection. The user’s `users` row is upserted with `authMethod: "proxy"` (no password/salt) and the resolved role list.

An existing `authMethod: "local"` row is explicitly protected — if a local user with that username exists, the proxy header is ignored for that user, so local accounts can’t be hijacked by proxy headers.

### Schema changes

- `User.authMethod` becomes optional (`"local"` | `"proxy"`; missing values default to `"local"`, so no migration needed for existing rows).
- `User.password` and `User.salt` become optional (proxy users have neither).
- New `group_roles` collection: `{ _id: <group>, roles: <csv> }`, cached via the existing `localCache` snapshot pattern.

### User lifecycle

Each proxy-authenticated user gets a real row in `users` with `authMethod: "proxy"`. The row’s roles are overwritten from the current group claim on every login, so group changes in the IdP propagate at next login and user offboarding in the IdP flows through naturally (removed from IdP → can’t auth to proxy → can’t reach GenieACS). Admins retain visibility of these users in the  
existing user-management UI and can set `disabled: true` on a specific user for emergency lockout independent of IdP state.

## Open design questions

These are all things I had to pick a side on in the prototype and I’d rather have your opinion before PR polish:

1. **Are you open to this in principle?** If not, the rest of the questions are moot.

2. **Group-mapping storage - MongoDB or `config.json`?** I went with a Mongo `group_roles` collection in the prototype, which fits the existing idioms (matches `users` / `permissions`) and is editable without redeploy, but needs a CRUD API and a new admin UI screen. `config.json` is ~60% less code and no UI work, at the cost of a redeploy to change the mapping. Both are workable — want your preference before I build out the UI.

3. **PR staging - one or two?** The prototype is backend only (~150 LoC). The UI admin screen + CRUD for `group_roles` would be another ~200 LoC matching the existing `users-page.ts` /  
`permissions-page.ts` patterns, plus tests and docs. One bundled PR, or stage backend first and UI in a follow-up?

4. **Local-account protection.** I chose silent fallthrough - if a row with `authMethod: "local"` exists, proxy headers are ignored for that user (they log in with their password as normal). The  
alternative is rejecting the request, which is stricter but disruptive to existing deployments the moment the feature is turned on. I’d like your security instinct here.

5. **Upsert cadence.** The prototype writes to MongoDB on _every_ proxy-authenticated request - simple and correct, but one write per request could be heavy for large admin teams. Should I  
read-compare-write only when roles actually change, or is every-request fine?

Smaller things (reuse of `FORWARDED_HEADER` vs a separate trusted list, session model for proxy users, logout URL for the proxy session) I’d prefer to sort out in PR review rather than litigate  
here.

## Happy to finish the work

Prototype is functional (lint + build pass). If the shape is acceptable I’ll iterate on whichever of the choices above you call, add the UI admin screen, the CRUD API, `docs/roles-and-permissions.rst` updates, and tests, and open a PR.

Thanks
