OIDC Role Mapping

OIDC Role Mapping lets a Drupal site automatically assign Drupal roles to users based on information their login provider sends during Single Sign-On (SSO), instead of an administrator having to manually assign a role to every new user.

If your organization already logs users into Drupal through an external identity provider (such as Keycloak, Azure AD, or another OpenID Connect provider), that provider often already knows what "group" or "role" a person belongs to. For example, editor, manager, or student. This module reads that information from the login token and translates it into the matching Drupal role, automatically, every time the person logs in.

Features

- Adds a "roles claim" setting to a generic OIDC realm: the name of the token field (claim) that contains a user's role information from the identity provider.
- Lets an administrator map individual role values from that claim to specific Drupal roles, using a simple form, no code required.
- Automatically grants the mapped Drupal role(s) to a user's account the moment they log in via that OIDC realm, based on what the claim contains.
- Optionally, automatically removes a previously granted role again if the claim no longer contains the matching value on a later login, keeping Drupal roles in sync with the identity provider over time, rather than only ever adding roles.
- Works as a non-intrusive extension of the OIDC module's existing generic realm plugin, so it does not require patching or modifying that module.

Typical use case: your identity provider already manages who is an "Editor" or "Administrator" through its own groups, and you want Drupal to reflect that automatically, without staff having to separately manage Drupal permissions by hand.

Post-Installation

After enabling the module, go to the configuration of your OIDC realm, and edit the generic realm you want to enable this for. You will now see:

- A Roles claim field, where you enter the name of the claim/token field that carries role information (this depends on how your identity provider is set up).
- A Role mapping section listing your site's roles, where you fill in which claim value should grant each role.
- A Remove roles checkbox, to control whether roles should also be revoked automatically when no longer present in the claim.

Leave the "Roles claim" field empty to disable role mapping for that realm entirely.

Additional Requirements

- OIDC: this module extends OIDC's generic realm plugin and does not work without it.
- External Authentication: used to detect the login event that triggers role synchronization.

No additional libraries or external services beyond your existing OpenID Connect identity provider are required.