Synchronize Microsoft 365 / Azure AD profile fields

Use this guide if you want to synchronize additional Microsoft 365 / Azure AD profile fields e.g. job title, department or employee number to WordPress / BuddyPress. This is a one-way synchronization that will pull the latest values from Microsoft 365 / Azure AD when the user logs into WordPress. Any values that were updated in WordPress will not be pushed back into Microsoft 365 / Azure AD.

Before you start

You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.
You must also 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.

Decide what source should be used for custom user fields

The WPO365 plugin and its extensions can look for Azure AD user attributes in various sources:

(Claims in the) ID token
(Claims in the) SAML response
(User resource from) Microsoft Graph

You can configure your preferred source for additional user attributes when you go to WP Admin > WPO365 > User sync (in the section for Custom user fields, as shown above).

If you configured OpenID Connect based single sign-on, then you can configure the WPO365 plugin to look in the ID token for (custom) claims that contain (custom) user attributes. This is the recommend approach, when you configured Azure AD B2C as your Identity Provider. You can find an article on how add custom user attributes to an Azure AD B2C ID token on the WPO365 website.

If you configured SAML 2.0 based single sign-on, then the recommend strategy is to configure the WPO365 plugin to look in the SAML response for additional claims containing user attributes.

In all cases, however, you can also configure the plugin, to retrieve a so-called User resource from Microsoft Graph.

This may be especially of interest, when you do not have the skills or the knowledge to add custom claims to an ID token or a SAML response.

To retrieve data from Microsoft's unified API, the WPO365 plugin will make a quick synchronous request to Microsoft Graph, whenever a (new) user (first registers or) successfully signs into your website with Microsoft. Please check the online documentation of Microsoft Graph's User Resource for a list of available properties.

Important If you would like to use Microsoft Graph as the source for additional user attributes, then it is recommended to change the Microsoft Graph version to beta. That version returns a lot more user attributes e.g. department. Please also note, that Microsoft Graph properties always start with a lowercase character e.g. department (and not Department).

If you need to retrieve properties that are not returned by Microsoft Graph by default then you must explicitly define additional $select properties.

Custom security attributes

Custom security attributes is a feature that requires additional configuration in Azure AD, for which you must create separate attribute sets and grant specific permissions to assign, read and define attribute sets and their values. You must - for example - assign the App registration (that you created for application-level access in Azure AD) the role of Attribute Assignment Reader. Please refer to this article for an example of how you can use custom security attributes.

App registration

Only perform this step, if you selected Microsoft Graph as your preferred source for custom user fields / attributes.

To go to the App registration in Azure AD, navigate to WP Admin > WPO365 > Single sign-on and click the link View in Azure Portal for the Application (client) ID.
A new browser tab opens and loads the App registration in Azure AD.

API Permissions

Only perform this step, if you selected Microsoft Graph as your preferred source for custom user fields / attributes.

Switch to the newly opened tab and to edit the permissions of the App registration.
Click API permissions from the 'App registration' menu on the left
Click + Add permission.
Select Microsoft Graph > Application 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 these permissions when they sign into this app.

Please note Alternatively, you can configure Microsoft Graph > Delegated permissions.

Plugin configuration

Switch back to the previous tab and the plugin's configuration pages.
Go WP Admin > WPO365 > User sync.
Scroll down to Azure AD user attribute to WordPress user meta mappings and per row enter first the technical name for the field you want to retrieve e.g. jobTitle, mobilePhone or officeLocation followed by the title that is be used when the field is shown in the user’s profile e.g. Job title, Mobile phone or Office location. Make sure to click “+” each time after you entered a new combined field.

Please note

Starting from v17.0 the plugin will always attempt to synchronize the mapped fields in this list. For older version you needed to check the option to Show Azure AD user attributes in a WordPress user profile (show O365 user profile fields).

Show Azure AD user attributes in a WordPress user profile

Checking the option to Show Azure AD user attributes in a WordPress user profile will add a new section labeled Office 365 Profile Information to a user's WordPress profile and display the fields as shown in the following

Retrieving array / child properties

Sometimes you may want to reference complex user profile properties when synchronizing WordPress user profiles with Microsoft Graph e.g. the first entry of the array of businessPhones or the sub property extensionAttribute1 of user profile property onPremisesExtensionAttributes. To achieve that you can write businessPhones.0 (to retrieve the first business phone of an array of possible entries by using the zero based array indexer) or onPremisesExtensionAttributes.extensionAttribute1 (to retrieve a named child property).

For Developers

Developers can retrieve this user meta in the familiar way using get_user_meta where the key that is used corresponds to the Microsoft Graph User Resource property name e.g.

get_user_meta( get_current_user_id(), 'jobTitle', true );

When using BuddyPress it is possible to update the so-called extended fields (see https://docs.wpo365.com/article/73-update-matching-buddypress-extended-profile-fields for details).

Please note

Additional profile fields including the user's profile picture will be updated whenever the user signs into your WordPress website (but only if you did not check the Express login option) or whenever the administrator runs User synchronization.