Map between Azure AD user properties and WordPress roles

Use this guide if you want to configure mappings between Azure AD user properties (see https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-beta#properties for a list of available (default) properties) and WordPress roles using the WPO365 | SYNC or WPO365 | INTRANET edition of the WordPress + Office 365 plugin.

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 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.

API Permissions

Click API permissions from the 'App registration' menu on the left
Click + Add permission.
Select Microsoft Graph > Delegated permissions.
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’.

Please note that it can take up to several minutes before the consent button becomes available and can be clicked. And even after that you may see a red warning that consent could not be granted. If you see this warning, please repeat the sequence and click to gran consent for all users in your tenant again.

After you clicked to grant consent please wait until any spinner has disappeared to ensure that consent has been granted.

Even after waiting for several minutes and all indicators showing you that consent has been granted, it may take a few more minutes before the App registration becomes fully functional.

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 (SSO).

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.

Alternatively, you can configure a 2nd App registration with app-only permissions. See https://docs.wpo365.com/article/101-app-only-integration for details.

Create a mapping

Navigate to the plugin's wizard WP Admin > WPO365 and click User registration.
Scroll down to Azure AD User property to WP Role mappings.
Enter the Azure AD User property with the value that should trigger the mapping being applied in the form of userPropertyName:value e.g. department:Communications and please be aware that the values that you enter are case sensitve.
Select the WordPress role that the Azure AD User property / value should be mapped to.
Click "+" to add the mapping.
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.