WordPress user provisioning with Azure AD (SCIM)
Use this guide if you want to configure user provisioning from Azure Active Directory to your WordPress website using the System for Cross-Domain Identity Management (SCIM) standard. To enable automatic provisioning of users between your WordPress website and Azure AD, WordPress + Office 365 plugin offers a custom SCIM endpoint that you can connect to Azure AD using the non-gallery application feature in the Azure AD application gallery. Once connected, Azure AD runs a synchronization process every 40 minutes where it queries the SCIM endpoint for assigned users and creates or modifies them according to the assignment details.
Important Even though SCIM does also supports the (de-)provisioning of groups, the WPO365 implementation of a custom SCIM endpoint does not. Instead you can assign WordPress users to roles based on their Azure AD group memberships (see https://docs.wpo365.com/article/39-map-between-azure-ad-groups-and-wordpress-roles for details).
Before you start
- Navigate to Azure Portal > Azure Active Directory > Licenses > All Products and ensure that your company has licensed Azure Active Directory Premium P2 (see https://azure.microsoft.com/en-us/pricing/details/active-directory/ for details). User Provisioning may otherwise not be available to you.
- You are a Global Administrator for your company’s Office 365 tenant / Azure AD directory (or have at least the ability to register an Azure Active Directory Enterprise App.
- You are an Administrator for your WordPress website and can make changes to the WordPress configuration file wp-config.php.
Enabling and configuring the plugin's custom SCIM endpoint
- Navigate to WP Admin > WPO365 > User sync (if you don't see this option then please make sure you installed the correct edition (PREMIUM or INTRANET) and version (v10.1 or higher) of the plugin.
- Select User provisioning (SCIM) as your preferred way to synchronize users between Azure AD and WordPress.
- The option Express login will appear and is automatically checked (but needs to be saved to take effect). Since Azure AD User provisioning can also synchronize a set of additional (Office 365) user fields e.g. department and job title there is no need for the plugin to refresh these fields each time a user sign in with Microsoft. So basically, with Express login checked the performance of the plugin should improve.
- The second option that appears is Deactivate users (instead of delete). When checked it will instruct the plugin to never hard-delete users from WordPress. Instead, the plugin will earmark such users as de-activated and will deny these users access to your website. If a de-activated user tries to sign in he / she will see an error that his / her account has been de-activated.
Please note that Azure AD User provisioning only will hard-delete a user 30 days after that user was initially deleted in Azure AD. During this 30 days period the user is earmarked as soft-deleted. Whenever a user is deleted, Azure AD will initially inform all SCIM endpoints that the user is no longer active. Based on this information that the SCIM endpoint receives from Azure AD, the plugin will then try to de-activate the user. Only after 30 days Azure AD will eventually hard-delete the user and inform all SCIM endpoints that the user is deleted. Only then will the plugin try to delete the WordPress user, unless you checked the option Deactivate users (instead of delete). Please bear in mind that whenever a WordPress user is deleted, his / her posts are also deleted.
Allow access to the WP REST API
You will need to ensure that Azure AD is able to access your WordPress REST API or else it cannot push SCIM compliant messages to the custom SCIM endpoint that the plugin provides.
- Please make sure that you disable any plugins that may block access to the WordPress REST API and double check your firewall configuration.
- Navigate to WP Admin > WPO365 > Single Sign-on and add /wp-json/wpo365/v1 to the Pages Blacklist. Make sure to click + to add the new line and then save your changes.
Create a secret token
- Create a random secret token e.g. using https://passwordsgenerator.net/ and ensure its strength by requiring a minimal length of 16 (better 32) characters and the use of symbols.
- Temporarily paste the secret token in a notepad as it is needed in the next step.
- Modify your WordPress website's configuration file wp-config.php (see https://wordpress.org/support/article/editing-wp-config-php/ for details) and just below the line
/* That's all, stop editing! Happy blogging. */
define( 'WPO_SCIM_TOKEN', '%YOUR-SECRET-TOKEN%' );
Connect you website's SCIM endpoint to Azure AD
- Sign in to the Azure Active Directory portal. Note that you can get access a free trial for Azure Active Directory with P2 licenses by signing up for the developer program
- Select Enterprise applications from the left pane. A list of all configured apps is shown, including apps that were added from the gallery.
- Select + New application > All > Non-gallery application.
- Enter a name for your application, and select Add to create an app object. The new app is added to the list of enterprise applications and opens to its app management screen.
- In the app management screen, select Provisioning in the left panel.
- In the Provisioning Mode menu, select Automatic.
Configuring provisioning in the Azure portal
- In the Tenant URL field, enter the URL of the application's SCIM endpoint. Example:
- Now copy the required secret token that you generated in the previous step into the optional Secret Token field.
- Select Test Connection to have Azure Active Directory attempt to connect to the SCIM endpoint. If the attempt fails, error information is displayed.
Please note Test Connection queries the SCIM endpoint for a user that doesn't exist, using a random GUID as the matching property selected in the Azure AD configuration. The expected correct response is HTTP 200 OK with an empty SCIM ListResponse message.
- If the attempts to connect to the application succeed, then select Save to save the admin credentials.
- In the Mappings section, there are two selectable sets of attribute mappings: one for user objects and one for group objects. The attributes selected as Matching properties are used to match the users and groups in your app for update operations. Select Save to commit any changes.
- You must disable syncing of group objects by disabling the groups mapping because syncing groups is currently not supported.
- In the Mappings section you must leave at least the following mandatory attribute mappings or else the plugin will not be able to create new users for you:
- userPrincipalName (Azure AD) to userName (SCIM)
- Not([IsSoftDeleted]) (Azure AD) to active (SCIM)
- mail (Azure AD) to emails[type eq "work"].value (SCIM)
- givenName (Azure AD) to name.givenName (SCIM)
- surname (Azure AD) to name.familyName (SCIM)
- Join(" ", [givenName], [surname]) (Azure AD) to name.formatted (SCIM)
- All other mappings e.g. department (Azure AD) to urn:iets:params:scim:schema:extension:enterprise:2.0:User:department (SCIM) are considered optional mappings and need additional administration by you.
- First you need to add the mapping to the list of attribute mappings on the Provisioning page of your Enterprise Application in Azure AD. Please note that for starters it's recommended to start with the default mappings.
- Second you must add for each optional mapping a counterpart to the Optional SCIM attribute mappings on the WP Admin > WPO365 > User sync page of the plugin's wizard. This will create a mapping for the customappsso attribute to a WordPress user meta field. Please note that the customappsso attributes are the ones that are exported by Azure AD and are sent to the plugin. It is strongly recommended that you map those customappsso attributes to the corresponding Microsoft Graph user resource property name e.g. urn:iets:params:scim:schema:extension:enterprise:2.0:User:department (SCIM) to department (Microsoft Graph User resource, see https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-beta#properties). Please note that failing to add an optional mapping here will result in the plugin simply dropping the information.
- Third if you enable Show O365 user fields and use the exact Microsoft Graph User resource property name when adding optional mappings then these properties will automatically surface on the user's WordPress / BuddyPress profile.
- Under Settings, the Scope field defines which users and groups are synchronized. Select Sync only assigned users and groups (recommended) to only sync users and groups assigned in the Users and groups tab.
Please note If syncing only assigned users and groups (recommended), be sure to select the Users and groups tab and assign the users or groups you want to sync.
- Once your configuration is complete, set the Provisioning Status to On.
- Select Save to start the Azure AD provisioning service.
Starting the next (incremental) synchronization cycle
It is more than likely that when you start with the configuration of the custom WordPress SCIM endpoint for Azure AD User provisioning that you are impatience and cannot wait 40 minutes each time for the next (incremental) synchronization cycle to complete. To manually start the next cycle immediately you can choose to use Microsoft Graph Explorer.
- Navigate to https://developer.microsoft.com/en-us/graph/graph-explorer.
- Sign in with Microsoft.
- Type the following query (GET) https://graph.microsoft.com/beta/servicePrincipals?$filter=startswith(displayName, 'WPO365 User Provisioning') in the query editor but replace WPO365 User Provisioning with the name you entered for your Enterprise Application instead.
- Optionally you may need to grant the Directory.ReadWrite.All permission.
- From the response, copy the ID from the Service Principal that is your Enterprise Application.
- Now type the following query (GET) https://graph.microsoft.com/beta/servicePrincipals/2356cea2-3374-4ef2-9249-3e997dec563d/synchronization/jobs in the query editor but replace the ID 2356cea2-3374-4ef2-9249-3e997dec563d with the ID you copied during the previous step.
- From the response, copy the ID from the Synchronization Job that is your current one.
- Now type the following query (POST) https://graph.microsoft.com/beta/servicePrincipals/2356cea2-3374-4ef2-9249-3e997dec563d/synchronization/jobs/scim.8ab34e846f8543659a48974d7f31cf78.42d510f8-3a52-413e-948a-377d6c76eece/start in the query editor to start the synchronization cycle immediately but replace the ID 2356cea2-3374-4ef2-9249-3e997dec563d with the service principal ID and scim.8ab34e846f8543659a48974d7f31cf78.42d510f8-3a52-413e-948a-377d6c76eece with the synchronization job ID that you copied during the previous steps.
- Once the query executed successfully you can navigate back to the Enterprise Application and check the audit log for results.
Please note The audit log runs asynchronously and you may need a bit of patience before the results of the last cycle are visible.
To help troubleshoot the custom SCIM endpoint you can configure remote logging with Microsoft ApplicationInsights. To do so please read the following article [link to be provided].