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 or when WPO365 synchronizes users from Azure AD to 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 have installed and activated any of the following premium WPO365 addons CUSTOM USER FIELDS, LOGIN+, SYNC or INTRANET.
  • 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 addons 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 below).

(Claims in the) ID token

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. For regular Azure AD, administrators can look up the Enterprise application equivalent for the App registration by navigating to Microsoft Entra Admin Center > Identity > Applications > Enterprise applications > [name of the App registration] > Single Sign-on > Attributes & Claims.

(Claims in the) SAML response

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. To add attributes to a SAML 2.0 response, navigate to Microsoft Entra Admin Center > Identity > Applications > Enterprise applications > [your enterprise application] > Single Sign-on > Attributes & Claims

(User resource from) Microsoft Graph

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, WPO365 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. 


Please note  It is recommended to change the Microsoft Graph version to beta (on the plugin's Integration configuration page). The beta 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 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.
  • Click Grant admin consent for <tenant>.

Please note If you are not planning on synchronizing users from Azure AD to WordPress on a regular basis using WPO365 User synchronization then you can - alternatively - select delegated permissions instead of application permissions. The plugin will then only update a user's WordPress profile whenever that user interactively signs in with Microsoft.

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 enter the following information:
    • First row Here you must enter the technical name of the attribute you want to retrieve. For example, to retrieve the department attribute from Microsoft Graph, enter department. If you have a custom claim added to the SAML response, you must enter the full name incl. namespace e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilePhone
    • Second row Here you must enter the name that WPO365 shall give to the usermeta record that it creates for each user in the wp_usermeta table e.g. graphDepartment or msDepartment. There are no rules for this naming convention but under circumstances you may have other customizations that will pull this data from the database.
    • Third row Here you enter the title of the field when it will be shown on a user's WordPress user profile. This title should not be empty but it will only be used if you checked the option to Show Azure AD user attributes in a WordPress user profile.

  • Click "+" after you completed an attribute mapping to add the mapping.
  • Scroll to the end of the page and click Save configuration to save the changes.

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 );

Related

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
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us