User Role Mapping - OAuth & OIDC Login

What is Role Mapping?

The role mapping feature allows you to map the Drupal roles and permissions to the users based on the attributes received from the OAuth or OpenID Connect Provider. This feature allows the assignment of roles to the user in Drupal after performing a successful SSO.

Prerequisite:

• Install and activate the OAuth & OpenID Connect Login - OAuth2 Client SSO Login module on your Drupal site. Follow these steps to install the module.

How to Configure Role Mapping

• Once you have configured the OAuth or OIDC Provider successfully, you can click on the Test Configuration button to verify whether the configurations are correct.
• If all the configurations are correct, you will receive a list of attributes from the OAuth or OIDC Provider.

• After you have received the attribute list, navigate to the Role Mapping tab.

  

Basic Role Mapping

It is the process of assigning roles to the users when they are created on the Drupal site after performing Single Sign-On. The user can be assigned one of the predefined roles, like Administrator, Authenticated user, and Content editor.

How to Configure Basic Role Mapping

• Now, navigate to the Edit tab, under the Client Configuration tab.

• In the Role Mapping section, check the Enable Role Mapping checkbox. It is mandatory for role mapping.

  

• Now, select the default role for the new user from the Select the default role for new users dropdown. This role will be assigned to the newly created user on their first login.

  

• Now, scroll down and click on the Save button.

Let's see how basic role mapping works

• Open a new incognito/private window and go to your Drupal site's login page.
• Click on the Login using the Provider link to initiate the SSO.
• Now, log in with a user who doesn't already have an account present in Drupal.
• Once you are successfully logged in to the Drupal site as a new user, navigate to another window where you already have an admin session.

• In that window, navigate to the People tab and check the roles of the newly created SSO user.

  

• As we have configured the Content editor as the default role for new users, the same role is assigned to the newly created SSO user.

Custom Role Mapping:

Custom Role mapping is the process where the roles are assigned to a user based on the user information or attributes received from the OAuth or OIDC Provider. To configure the Custom Role Mapping, we can also add a few more roles to the Drupal site.

How to Configure Custom Role Mapping

• As aforementioned, we need to select the checkbox of Enable Role Mapping to perform the custom role mapping.

• Under the Role Attribute text field, enter the attribute name in which you are receiving the roles/groups of a user from OAuth or OIDC Provider. In our case, we are receiving the user's roles under the Developer Groups attribute.

  Please note that if you are receiving the attributes in a nested format (for example - Developer Groups.0, Developer Groups.1, etc) then you only have to enter the first part of the attribute name i.e. in this case, we only have to enter Developer Groups in the text field.

  

• Scroll down a bit to the Role Attributes section.

• On the left side, we have a drop-down Drupal Role. In this drop-down, all the roles that are already present or created on the Drupal site are present. You have to select a role that you want a user to be assigned with a particular role value received from an OAuth or OIDC Provider. So, let's select an Administrator role from the Drupal Role drop-down.

  

• On the right side, we have the OAuth Server/Provider Role text field. In this text field, we have to enter the role that is received from the OAuth or OIDC Provider in the aforementioned Role Attribute. In our case, we have received 2 roles/groups from the provider, i.e. Drupal Developers and Test-Developers. Let's map Drupal Developers to the Administrator role.

  

• Now, if you want to map multiple user roles, you can select a number of rows and click on the Add and follow the same procedure again. For example, we will map another Role that we are receiving, Test-Developer.

  

• Once you have mapped all the required roles as per your use case, scroll down and click on the Save button.

Let’s see how this works:

• Open a new incognito window and go to your Drupal site's login page.
• Click on the Login using the Provider link to initiate the SSO.
• Once you are logged in to the Drupal site successfully, navigate to the People tab of the Drupal site (using any admin credentials) and check if the mapped roles have been assigned successfully.

How to keep existing roles and add new roles on SSO

If the user is already present in Drupal with some roles and permissions, and then after performing SSO, the user's existing roles should remain intact and only be assigned with the newly mapped roles. This can be done by the feature that we provide in the module - Check this option if you want to keep the existing roles.

In order to configure this feature, under the Role Mapping section, check the checkbox of Keep the existing roles and click on the Save button by scrolling down.

Let’s see how this works

• Open a new incognito window and go to your Drupal site's login page.
• Click on the Login using the Provider link to initiate the SSO.
• Now just for example, a TestUser has the Content editor role already assigned to it before performing the SSO. After successful SSO, TestUser will have the following roles:
  • Content editor
  • Administrator
  • Manager
• So, TestUser's Content editor role will be intact and the newly mapped roles will be added to that account.

 Back to top