Map between Azure AD groups and WordPress roles

Use this guide if you want to configure mappings between Azure AD (security / Office 365 / distribution list) groups and WordPress roles using the PREMIUM or 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.
  • If you also plan to synchronize users from Azure AD to WordPress and you would like the mappings you are about to configure to be applied whenever you synchronize users, then 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.

Token configuration

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

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
    • Groups.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’.
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 and the ID token contains the upn, email, given and family name. If the Plugin self-test later on fails but you are convinced that you did everything right, then wait a few more minutes and repeat the self-test.

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

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

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.

  • Scroll down to User role(s) update scenario.
    • 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.
    • 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).
  • Scroll down to Default role as fallback and check this option if you want the plugin only to add the Default role (main site / subsite) when no other WordPress roles are otherwise assigned to a user.
  • Click Save configuration.

Test and Troubleshoot

To test your mapping you can log on with a (test) user that is a member of the Azure AD group for which you created a mapping and sign in.

If the mapping has not been applied you can verify your configuration as follows.

  • Enable the plugin's Debug log (see https://docs.wpo365.com/article/19-enable-debug-log).
  • Navigate to the plugin's wizard WP Admin > WPO365 and click ... > Debug.
  • Check Log ID token.
  • Sign out of your WordPress website.
  • Sign back in with Microsoft.
  • Navigate back to WP Admin > WPO365 > ... > Debug and click Show all.
  • Search for the ID token in the log and check to see if the group IDs were indeed sent as expected.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.