Map between Azure AD groups and WordPress roles

Preview notice

We are working hard on a new WPO365 tutorials site and we are very happy to invite you to visit instead the tutorial to dynamically assign WordPress roles to users based on their Azure AD group memberships.

Use this guide if you want to configure WPO365 to dynamically assign WordPress roles based on a user's Azure AD group membership(s).

Before you start

• You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.
• You must also already have configured the integration capability of the plugin.
• You have purchased a premium extension, for example WPO365 | ROLES + ACCESS to be able create mapping rules to dynamically assign WordPress roles based on a user's Azure AD group membership(s) or any of the bundles WPO365 | CUSTOMERS, WPO365 | SYNC or WPO365 | INTRANET.
• You are a Global Administrator for your company’s Office 365 tenant / Azure AD directory (or have at least the ability to edit the Azure Active Directory App registration that was created previously when the single sign-on capability was configured).
• You are an Administrator for your WordPress website.

App registration

• In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
• Navigate to Azure Active Directory > App registrations.
• Select the App registration that you created when you configured the single sign-on capability of the plugin.

Token configuration

Please note that the information below only applies to older versions of the BASIC edition of the plugin. Since version 11.0 premium the premium extensions LOGIN+, SYNC and INTRANET will also  try to retrieve all the (Azure AD / Office / Distribution list) groups a user is member of from Microsoft Graph (because of the ID token's limited capacity of max. 200 groups). For the plugin to be able to retrieve all groups the user is a member of, you must configure the Integration portion of the plugin (see https://docs.wpo365.com/article/23-integration for the necessary configuration and below for the required permissions).

• Click Token configuration from the 'App registration' menu on the left.
• Click + Add groups claim.
• Select Security groups.
• Click Add.

Important There is limitation of the number of groups sent by Microsoft. If the user is member of a large number of groups, vital information may be truncated.

Please note Microsoft will not only send the IDs of the groups the user is direct member of but also the IDs of those groups that encapsulate groups he / she is a member of (nested groups).

API Permissions

• Click API permissions from the 'App registration' menu on the left
• Click + Add permission.
• Select Microsoft Graph > Delegated permissions.
• Scroll down to Groups and check
  • GroupMember.Read.All
• Scroll down to Users and check
  • User.Read.All
• Click  Add permissions.
• Wait until Grant admin consent for … has become available, then click to grant consent for all users in your tenant to use this ‘App registration’.

Delete all tokens

• Navigate to the plugin's wizard WP Admin > WPO365 and click Integration.
• Click Delete all tokens.
• Sign out of your WordPress website.
• Sign back in with Microsoft.

This step is needed to ensure that the plugin refreshes the access token previously retrieved so that the updated permissions are reflected in your personal access token that the plugin retrieves when you sign back into your website with Microsoft.

Create a mapping

Please note Before you can perform the steps below to create a mapping, you must select a WP role(s) update scenario e.g. Add or Replace on the plugin's User Registration configuration page.

• Open (in a new browser tab) Azure Portal and click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
• Navigate to Azure Active Directory > Groups. 
• Click the group you want to create a mapping for and from the Overview page copy the group's Object ID.
• Navigate to the plugin's wizard WP Admin > WPO365 and click User registration.
• Scroll down to (Group) Role mappings.
• Paste the Object ID of group on a new line and to left of it select the WordPress role that the group should map to.
• Click "+" to add the mapping.
• Click Save configuration.

The following video https://youtu.be/kL82s5opWnk has been created for an older version of the plugin but still covers the basics presented in this guide.

Replace or add user roles

• Replace (= delete) all existing roles and then add the new ones.
• Add any possible new roles (default behavior)
• Skip assign roles all together.

Perform the following steps to change this behavior.

• Still at WP Admin > WPO365 > User registration, scroll down to User role(s) update scenario.
• Select Add if you want the plugin (each time when the user logs in and mappings between Azure AD and WordPress roles are verified or when users are being synchronized) to add possible new WordPress roles but leave the old ones (recommended).
• Select Replace if you want the plugin (each time when the user logs in and mappings between Azure AD and WordPress roles are verified or when users are being synchronized) to delete existing WordPress roles for a user and add new ones.
• Click Save configuration.

Default role as fallback

The plugin is capable of assigning multiple WordPress roles to a user. By default it will try and add the Default role main site first and additionally try adding any role that maps to any of the Azure AD groups that the user is a member. So without any applicable mapping the user will at least receive the role that you configured as default one for the main site.

To change this default behavior and configure the plugin to only to add the  Default role (main site / subsite) when no other WordPress roles are otherwise assigned to a user, perform the following steps.

• Still at WP Admin > WPO365 > User registration, scroll down to Default role as fallback.
• Check this option.
• Click Save configuration.