Map between app roles and WordPress roles

This article will guide you through configuring WPO365 to dynamically assign WordPress roles based on app roles, whereby app roles are defined during the App registration process. Once declared, Microsoft Entra ID emits a roles claim for each role assigned to a user or group whenever a user signs into the application. Please refer to this article for guidance on adding app roles to your registered application and subsequently assigning to users (and groups).

Please note If you're uncertain about whether to utilize app roles or standard Azure AD (security) groups for dynamic assignment of WP roles to users, consider reviewing this Microsoft article that outlines the key differences between the two options.

Before you start

You must already have configured the OpenID Connect based single sign-on capability of the WPO365 | LOGIN 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 Microsoft 365 and Microsoft Entra ID tenant (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.

Add an app role to your App registration

In Microsoft Entra Admin Center click to expand the Identity menu.
Navigate to Applications > App registrations.
Select the App registration that you created when you configured OpenID Connect based Single Sign-on (SSO).
From the App registration's menu, select App roles, as depicted below.

Click + Create app role.
Create a new app role and specify:
- Display name
- Allowed member types WPO365 only supports Users/Groups
- Value This will later be used to configure rules to map between app roles and WP roles
- Description
- Enable this app role Make sure to enable this option
Click Apply to save the new app role.

Assign users to a new app role

Navigate to your App registration's Overview page and click the link Managed application in local directory. This will open the corresponding Enterprise application for this App registration.
Click Edit assignment on the Enterprise application's Users and groups page for a select user (or click + Add user/group to add users first).

Add rules to map between app roles and WP roles

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 the WPO365 Configuration pages by going to WP Admin > WPO365.
Select the User Registration tab and scroll to the section for Roles + Access.
Create a new mapping rule by entering the app role's value in the input field and selecting the WP role that users with the selected app role should receive.
Click + to add the new mapping rule.
Scroll to the bottom of the page and click Save configuration.

Replace or add user roles

Each time a user signs into your website, the plugin will verify whether mappings between app roles 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:

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.