Description
Filtered Group Membership Mapper is a Keycloak Protocol Mapper that extends the built-in Group Membership Mapper by adding regex-based filtering to exclude groups from tokens.
It allows fine-grained control over which groups are exposed to clients without modifying the underlying Keycloak group structure.
Repository: https://github.com/byteworks-ch/keycloak-filtered-group-membership-mapper
Features:
- Regex-based exclusion filtering for group paths
- Drop-in replacement for Keycloak’s built-in Group Membership Mapper
- Works with OpenID Connect and SAML tokens
- Reduces token size by excluding unnecessary or sensitive groups
- Supports full group path matching (e.g.
/app/team/admin)
- Per-client / per-client-scope configuration
Discussion
No response
Motivation
Keycloak’s default Group Membership Mapper always includes all user groups in issued tokens. In real-world environments, users often belong to many groups across different applications or domains.
This creates several challenges:
- Tokens may expose internal or unrelated group structures
- Clients receive more data than they actually need
- Multi-tenant setups lack per-client group filtering
- Sensitive or administrative groups may unintentionally leak into tokens
There is currently no built-in mechanism in Keycloak to exclude groups based on patterns or rules at the mapper level. This extension introduces a simple and flexible regex-based exclusion mechanism that integrates directly into the existing mapper architecture.
Details
The mapper behaves exactly like the standard Keycloak Group Membership Mapper, with one additional step:
Before a group is added to the token, it is checked against a configured regex exclusion filter:
- If the group matches the regex → it is excluded from the token
- If it does not match → it is included
This makes it possible to define rules such as:
- Exclude all internal groups (
^/internal/.*$)
- Exclude admin roles (
.*admin.*)
- Exclude specific application namespaces (
^/app1/.*$)
The extension is fully compatible with Keycloak Quarkus distributions and requires no changes to existing group structures or authentication flows.
Description
Filtered Group Membership Mapper is a Keycloak Protocol Mapper that extends the built-in Group Membership Mapper by adding regex-based filtering to exclude groups from tokens.
It allows fine-grained control over which groups are exposed to clients without modifying the underlying Keycloak group structure.
Repository: https://github.com/byteworks-ch/keycloak-filtered-group-membership-mapper
Features:
/app/team/admin)Discussion
No response
Motivation
Keycloak’s default Group Membership Mapper always includes all user groups in issued tokens. In real-world environments, users often belong to many groups across different applications or domains.
This creates several challenges:
There is currently no built-in mechanism in Keycloak to exclude groups based on patterns or rules at the mapper level. This extension introduces a simple and flexible regex-based exclusion mechanism that integrates directly into the existing mapper architecture.
Details
The mapper behaves exactly like the standard Keycloak Group Membership Mapper, with one additional step:
Before a group is added to the token, it is checked against a configured regex exclusion filter:
This makes it possible to define rules such as:
^/internal/.*$).*admin.*)^/app1/.*$)The extension is fully compatible with Keycloak Quarkus distributions and requires no changes to existing group structures or authentication flows.