Synchronize Microsoft 365 / Azure AD profile fields
This guide will assist you in synchronizing user attributes from Entra, like job title, department, or employee number, to WordPress/BuddyPress, and storing them as WordPress user meta or BuddyPress profile fields.
| Please note This is a one-way synchronization that is applied on the following occasions:
Any values updated in WordPress will not be sent to Entra. |
Before you start
- You should already have configured the single sign-on capability of the WordPress + Office 365 plugin.
- Optionally, you have configured WPO365 User synchronization or support for Entra's SCIM based Provision Service.
- You have installed and activated any of the premium bundles that support the CUSTOM USER FIELD feature set.
- You are a Global Administrator for your company’s Entra ID (Azure AD) 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.
Decide whether WPO365 should skip updating a user when signing in
If you are regularly synchronizing user attributes from Entra to WordPress using WPO365 User synchronization or support for Entra's SCIM based Provision Service, you can consider to configure WPO365 to prevent user updates upon sign-in. To do so, check the Express Login option on the plugin's Login / Logout page. Keep in mind that this does also skip other update routines - if configured - such as updating a user's WordPress role and Avatar.
Decide whether WPO365 should retrieve user attributes from Microsoft Graph
When a user signs in with Microsoft, WPO365 can attempt to retrieve user attributes for the user currently signing in from Microsoft Graph. Retrieving user attributes from Microsoft Graph is a convenient way to have access to all possible user attributes in Entra, without the need to customize the claims in the ID token or SAML response. However, it also means that you must give WPO365 sufficient permissions to access Microsoft Graph, either on behalf of the logged-in user or using application-level permissions.
| Please note In the earlier versions of WPO365, retrieving user attributes was enabled by default. |
| Please note If you enable WPO365 to retrieve user attributes from Microsoft Graph, you may need to update the API Permissions in Entra for your App registration. For instructions, scroll down to the paragraph Update API Permissions for Microsoft Graph. |
Save user claims / properties as WP user meta
You can configure WPO365 to save claims / properties it receives from Entra when you go to WP Admin > WPO365 > User sync and scroll down to the section Custom user fields (Azure AD -> WordPress).
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.
To save - for example - a custom claim in the ID token department as WP user meta with key entraDepartment and with title (used only if shown on a user's profile page) Department, enter the following configuration.
| Please note It is advisable to add the prefix oidc:: so that WPO365 knows to look for this specific claim in the OpenID Connect ID token. |
| Please note You can view the claims in an ID token - for example - when you successfully run the Plugin self-test and then click the link View on the line that reads Can decode the ID token. |
Claims in SAML response
If you configured SAML 2.0 based single sign-on, then you can configure the WPO365 plugin to look in the SAML response for (custom) claims that contain (custom) user attributes. To add claims to a SAML 2.0 response, navigate to Microsoft Entra Admin Center > Identity > Applications > Enterprise applications > [your enterprise application] > Single Sign-on > Attributes & Claims.
To save - for example - a custom claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department in the SAML response as WP user meta with key entraDepartment and with title (used only if shown on a user's profile page) Department, enter the following configuration.
| Please note It is advisable to add the prefix saml:: so that WPO365 knows to look for this specific claim in the SAML 2.0 response. |
| Please note You can view the claims in a SAML 2.0 response - for example - when you successfully run the Plugin self-test and then click the link View on the line that reads SAML response has been processed and no errors occurred. |
User Resource properties from Microsoft Graph
If you checked the option Retrieve user attributes from Graph or if you have configured WPO365 User synchronization, then you can configure the WPO365 plugin to look up user attributes in a Microsoft Graph User Resource object.
To save - for example - a User Resource property departement as WP user meta with key entraDepartment and with title (used only if shown on a user's profile page) Department, enter the following configuration.
| Please note It is advisable to add the prefix graph:: so that WPO365 knows to look for this specific claim in the SAML 2.0 response. |
| Please note 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.
Attributes in SCIM messages
If you configured support for Entra's SCIM based User Provisioning Service, then you can configure the WPO365 plugin to look in the SCIM messages for user attributes. Please refer to our implementation guide for SCIM based Entra User Provisioning for instructions how to add attributes to a SCIM message.
To save - for example - an attribute scim::urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department in a SCIM message as WP user meta with key entraDepartment and with title (used only if shown on a user's profile page) Department, enter the following configuration.
| Please note It is recommended to prepend the prefix scim:: to ensure that WPO365 correctly identifies and sources the specific attribute within a SCIM message. |
Retrieving array / child properties
Sometimes you may want to reference complex user profile properties when synchronizing WordPress user profiles from 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).
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
Update API Permissions for Microsoft Graph
App registration
Only perform this step, if you checked the option to retrieve user attributes 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. |
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).