Map between Azure AD groups and (itthinx) Groups

Use this guide if you want to configure mappings between Azure AD (security / Office 365 / distribution list) groups and (itthinx) Groups (see https://wordpress.org/plugins/groups/ for details) 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

Perform the following steps to navigate to the App registration for your WordPress website in Azure Active Directory.

Navigate to WP Admin > WPO365 > Single sign-on.
Scroll to the Application id and click View in Azure Portal.

If you do not see the "View in Azure Portal" link then please upgrade to v10.9 or higher. The link will only be visible when you entered a (valid) Application ID.

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 send the IDs of the groups the user is direct member plus the IDs of any nested group he / she is a member of.

API Permissions

The following API Permissions are only needed when you intend to synchronize users from Azure AD to WordPress.

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 since v9.5 it is recommended to register a second App in Azure AD with so-called Application permissions that are used by the user synchronization process instead. See https://www.wpo365.com/use-app-only-token/ for details.

Delete all tokens

Navigate to the plugin's wizard WP Admin > WPO365 and click Integration.
Click Delete 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

Perform the following steps to create mappings between Azure Active Directory and (itthinx) Groups.

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 Azure AD Group to (itthinx) Group mappings.
From the drop down list select the (itthinx) Group for which you would like to create the mapping for.
On the corresponding text input immediately below the (itthinx) Group paste the Object Id of the Azure AD Group that you copied before.

Click + to add the mapping.
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.