Introduction to Mapping

• Mapping involves the process of mapping user attributes between an Identity Provider (IdP) and a Service Provider (SP) in the SAML Single sign-on (SSO) process. When a user performs SSO to log into the SP (Drupal site), the IdP provides a SAML assertion containing user attributes, and the Mapping tab will allow you to map those attributes to the Drupal user profile attributes. The miniOrange SAML SP Module offers options for
  1. Attribute mapping
  2. Custom Attribute Mapping
  3. Role Mapping
  4. Profile Module Mapping
  5. Group Module Mapping

Prerequisite:

• To map Identity Provider (IdP) attributes, we need to know the attributes we receive from the IdP. To obtain a list of all the attributes received, please follow the steps below:
  • Navigate to the Service Provider Setup tab of the module. Scroll down to the bottom and click on the Test Configuration button.
  • You will get a popup window with attributes received from your Identity Provider (IdP).
  • Note down the attribute name for further mapping.

Configure Attribute Mapping:

• This mapping allows you to map Identity Provider attributes to the username and email fields of the Drupal user profile during SSO login. If the user already exists in Drupal, their username and email will be updated based on the mapping. The default attribute for Drupal username and email is NameID.

Steps for attribute mapping:

• Go to the Mapping tab → Attribute Mapping.
• Enter the attribute name you want to use as the Drupal user’s username from the IdP response in the Username Attribute textbox.
• Enter the attribute name you want to use as the Drupal user’s email from the IdP response in the Email Attribute textbox.
• Scroll down and click on the Save Configuration button.

Note: Be careful when using this mapping. Incorrect mapping can lead to errors such as "The username is already taken" or "The email address is already taken."This mapping allows you to map Identity Provider attributes to the username and email fields of the Drupal user profile during SSO login. If the user already exists in Drupal, their username and email will be updated based on the mapping. The default attribute for Drupal username and email is NameID.

Custom Attribute Mapping:

• Custom attribute mapping involves mapping extra attributes like first name, last name, and phone from Identity Providers (IdPs) to a custom Drupal user field. Similar to attribute mapping, this mapping also updates the custom attributes upon each Single Sign-On (SSO) login.

Steps for custom attribute mapping:

• Go to the Mapping tab > Custom Attribute Mapping.
• In the Custom Attributes Mapping table, enter the following information
  • Drupal Field Machine Name → Machine name of Drupal user field.
  • IDP Attribute Name → Attribute name from IdP that you want to map.
  • Separator → Leave it blank if the attribute value is a regular string from the IdP. If the attribute value is in array format, use a comma (,) as the separator. If you receive multiple attributes in string format, use the appropriate separator. For example, if the value of the attribute is like "manager-admin-user," use a dash (-) as the separator.
• Click on the Add button if you want to add more attributes.
• Scroll down and click on the Save Configuration button.

Profile Module Mapping:

• This feature enables the mapping of attributes received from the Identity Provider (IdP) during Single Sign-On (SSO) to a custom user profile created using the Profile module. By mapping attributes from the IdP to the custom user profile, you can ensure that the user profile information stays synchronized and up-to-date. This eliminates the need for manual data entry and helps maintain consistency across different systems.

Prerequisite:

• Ensure that the Profile module is installed on your Drupal site and you have created at least one profile type.

Procedure:

• Go to the Mapping tab → Profile Module Mapping.
• Enable the Enable profile mapping checkbox.
• In the Profile Module Mapping table, enter the following information
  • SP Profile field → Field name of the Drupal user profile.
  • IdP Attribute Name → Attribute name from IdP that you want to map.
• Click on the Add button if you want to add more attributes.
• Scroll down and click on the Save Configuration button.

Role Mapping:

• Role mapping is a useful feature that allows you to assign user roles in Drupal based on attribute values from the Identity Provider (IdP) during SSO authentication. With role mapping, you can dynamically assign Drupal user roles based on specific attribute values provided by the IdP.

Steps for role mapping:

• Go to the Mapping tab and then click the Edit button for your desired IdP.
• Then, expand the Role Mapping section and check the box for Enable Role Mapping.
• Select the default role for new users from the dropdown menu labelled Select default role for new users. The chosen role will be assigned to the user after the user logs in for the first time using SSO.
• Enter the IdP attribute name in the Role Key text box that decides the user's role in Drupal.
• In the Role Attributes Mapping table, enter the following information:
  • SP Role → User’s role in Drupal.
  • IdP Role → Actual attribute value will be received in SAML response.
• Click on the Add button if you want to map more roles.
• Scroll down and click on the Save Configuration button.

Example:

• Let's consider an example where the IdP sends the attribute "role" in the SAML response during SSO.
• In the Role Mapping configuration, we define the following mapping:
  • Role Key: role
  • IdP Role: manager
  • SP Role: Administrator
• When a user with the "manager" role logs in through SSO, the module will assign the "Administrator" role to the corresponding Drupal user.

Role Assignment Logic:

• During SSO, the module retrieves the attribute values from the IdP response.
• The attribute values are compared against the configured attribute mappings.
• If a match is found, the corresponding Drupal role is assigned to the user.
• If no match is found, the default role is assigned to the user.

Dynamic Role Updates:

• The module ensures that role assignments stay synchronized with any changes in the attribute values provided by the IdP.
• If an attribute value changes during subsequent SSO attempts, the corresponding Drupal user's role is automatically updated.
• The role mapping feature also offers the choice to disable role revocation during SSO when there is no valid mapping found for the user's attribute. To prevent the Drupal user's role from being revoked if it is removed from IdP, you can check the box labeled Do not update user role if roles are not mapped under Mapping > Role Mapping.

Group Module Mapping

• This mapping is related to the groups created using the contrib module - Group. Using this feature, you can map roles/groups received from your Identity Provider to your existing groups in Drupal during SSO. Based on the group attributes in the SAML response, users are automatically added to the corresponding Drupal groups at login, ensuring proper access control and group-based permissions without manual assignment.

Prerequisite

• Ensure that the Group module is installed on your Drupal site.

Procedure

• Go to the Mapping tab and then click the Edit button for your desired IdP.
• Then, expand the Group Mapping section and check the box for Enable Group Mapping.
• Check Keep existing groups check box to keep the existing group as it is, and do not want to update the groups.
• Enter the attribute name in the Group Attribute text box to map it to an existing Drupal group.
• Now, select the Drupal group from the dropdown that you have created.
• Then, enter the value of the attribute that you have entered in the Server Group Name/ID text field. You can add multiple values, separating them with ; (semicolon).
• Then, click the Save button.

Example

• Let's consider an example where the Identity Provider (IdP) sends the attribute memberOf in the SAML response during SSO. Our goal is to automatically add users to the appropriate Drupal group based on this attribute.
• In the configuration, we set up the following mapping: 
  • Group Attribute Name: memberOf  
  • Drupal Group: Drupal Developers 
  • Server Group Name/ID: developers (value of Group Attribute)
• With this setup, when a user logs in via SSO and the SAML response contains memberOf = developer, the user is automatically added to the Drupal Developers ​​​​​​group in Drupal. If the attribute value does not match, the user will not be added to that group.

 Back to top