Map between Entra user properties and WordPress roles

Use this guide if you want to configure mappings between Entra user properties and WordPress roles WPO365.

Please note Rules that you implement using this guide may refer to ID token claims, claims received in a SAML 2.0 response, attributes received from Entra's SCIM based User Provisioning Service and Microsoft Graph User Resource properties. These rules will then be applied on one or more of the following occasions:

When a user signs into WordPress with Microsoft (claims in an ID token or SAML 2.0 response).
When a user is synchronized to WordPress (properties received from Microsoft Graph or Entra's SCIM based Provisioning Service.

Before you start

You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.
Optionally, you may also have configured WPO365 User synchronization or support for Entra's SCIM based User Provisioning Service.
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.

Decide whether WPO365 should retrieve user attributes from Microsoft Graph

When a user signs in with Microsoft, WPO365 can attempt to retrieve user attributes for the user currently signing in from Microsoft Graph. Retrieving user attributes from Microsoft Graph is a convenient way to have access to all possible user attributes in Entra, without the need to customize the claims in the ID token or SAML response. However, it also means that you must give WPO365 sufficient permissions to access Microsoft Graph, either on behalf of the logged-in user or using application-level permissions.

Please note In the earlier versions of WPO365, retrieving user attributes was enabled by default.

Please note If you enable WPO365 to retrieve user attributes from Microsoft Graph, you may need to update the API Permissions in Entra for your App registration. For instructions, scroll down to the paragraph Update API Permissions for Microsoft Graph.

Dynamically assign a WordPress role

Before you continue, you you must select a WP role(s) update scenario e.g. Add or Replace on the plugin's User Registration configuration page.

Navigate to the plugin's wizard WP Admin > WPO365 and click User Registration.

Scroll down to WP role(s) update scenario and decide whether WPO365 should either only Add new or Replace existing WP role assignments.
Scroll down to Mappings to assign WP role(s) based on user claims / properties.
Enter the a claim / property with the value that should trigger the mapping being applied in the form of name:value and please be aware that the values that you enter are case sensitive.
Select the WordPress role that the Azure AD User property / value should be mapped to.
Click "+" to add the mapping.

In the previous example, the following rules have been entered:
- SAML 2.0 claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department:Communications
- SCIM attribute urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department:Communications
- Graph property department:Communications
Click Save configuration.

Replace or add user roles

Each time a user signs into your website, the plugin will verify whether mappings between Azure AD groups and WordPress roles have been configured. If this is the case, the plugin will update the user’s WordPress role(s) in one of the following two ways:

Deleting all existing roles and then add the new ones
Add any possible new roles (default behavior)

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.

Update API Permissions for Microsoft Graph

App registration

Only perform this step, if you checked the option to retrieve user attributes Microsoft Graph as your preferred source for custom user fields / attributes.

To go to the App registration in Azure AD, navigate to WP Admin > WPO365 > Single sign-on and click the link View in Azure Portal for the Application (client) ID.
A new browser tab opens and loads the App registration in Azure AD.

API Permissions

Only perform this step, if you selected Microsoft Graph as your preferred source for custom user fields / attributes.

Switch to the newly opened tab and to edit the permissions of the App registration.
Click API permissions from the 'App registration' menu on the left
Click + Add permission.
Select Microsoft Graph > Application permissions.
Scroll down to Users and check
- User.Read.All
Click Add permissions.
Click Grant admin consent for <tenant>.

Please note If you are not planning on synchronizing users from Azure AD to WordPress on a regular basis using WPO365 User synchronization then you can - alternatively - select delegated permissions instead of application permissions. The plugin will then only update a user's WordPress profile whenever that user interactively signs in with Microsoft.