OAuth2-Proxy Group Authorization#

Group authorization in oauth2-proxy controls which authenticated users gain access based on group membership or role assignment. The core logic lives in Authorize() in providers/provider_default.go, and applies to all providers uniformly.

Authorization Logic: OR-Based Membership#

Authorize() does a simple set lookup 1:

• If AllowedGroups is empty, every authenticated user passes — authorization is effectively disabled.
• If AllowedGroups is non-empty, the user's session.Groups slice is iterated; the first match against any allowed group grants access (OR semantics). A user needs membership in only one of the listed groups/roles.
• Matching is exact string equality — no wildcards, no prefix matching, no regex. The group string stored in the session must exactly match the string in AllowedGroups.

AllowedGroups is a map[string]struct{} built at startup from the --allowed-group flag (and, for Keycloak OIDC, --allowed-role) via setAllowedGroups. Empty strings are silently dropped during initialization.

Keycloak OIDC: Two Sources Feeding session.Groups#

For --provider=keycloak-oidc (providers/keycloak_oidc.go), session.Groups is populated from two distinct sources:

Role extraction is performed by extractRoles(), called from EnrichSession, RefreshSession, and CreateSessionFromToken so roles stay in sync with the session at all lifecycle points. Roles get the role: prefix via formatRole() before being appended to session.Groups; this prefix is what distinguishes roles from OIDC groups and makes them route through the same Authorize() check.

Allowed roles declared via --allowed-role are registered (with the same role: prefix) into AllowedGroups at startup by addAllowedRoles().

OIDC groups flow through the standard OIDC path in buildSessionFromClaims, reading the claim named by --oidc-groups-claim from the ID token. They are stored verbatim — no prefix is added.

Group Path Prefixes and Exact Matching (Keycloak)#

Keycloak's "Full group path" mapper option controls whether groups are emitted as /groupname (full path) or groupname (short name) 2.

The string used in --allowed-group must exactly match what Keycloak puts in the token 3:

• If "Full group path" is enabled in the Keycloak Group Membership mapper → use --allowed-group=/groupname (leading / required) or --allowed-group=/groupname/child_group for nested groups.
• If "Full group path" is disabled → use --allowed-group=groupname (no /).

A mismatch here (e.g., using groupname when the token contains /groupname) will silently fail — the user is denied because no string equality match is found.

Configuration Reference#

For Keycloak group authorization to work, a "groups" client scope with a Group Membership mapper must be created in Keycloak and attached to the OIDC client 4. Role authorization requires no extra Keycloak setup since the standard "roles" client scope ships with realm/client role mappers enabled by default 5.

Key Source Files#