Synchronize users between Office 365 and WordPress

Version Supported
Personal Blog (free) No
Commercial / School / Non-profit (premium) Yes

Feature description

The WordPress + Office login (premium) plugin allows WordPress administrators to synchronize users between Office 365 Azure AD and WordPress. To do so, the plugin will retrieve a list – when manually triggered to do so – of all Office 365 Azure AD users (from Microsoft Graph) and then perform a comparison between users found in Office 365 Azure AD and WordPress. What follows below is an instructional guidance that also explains how the User Synchronization feature works internally. For you, as an administrator, this should help you when working with the results of a synchronization run.


  • You must be a WordPress administrator to be able to synchronize users.
  • You must have generated an Application Key / Secret for your registered application in Azure Active Directory.
  • You must have activated the User Synchronization feature in the plugin’s configuration as described here.

Required Configuration

For this feature to work correctly, you must change the permissions that you initially granted to the registered app for the WordPress + Office 365 Login plugin. To do so, proceed as follows:

  • Sign into your Azure Portal
  • Navigate to Azure Active Directory, click App registrations followed by View all applications and select your application registration
  • For your application registration click Settings in the left upper corner and select Required permissions from the available Settings
  • Click Add and then 1 Select API and check Microsoft Graph
  • Scroll down to the section Delegated permissions and check Read all users’ full profiles and Read all Groups (to allow for the plugin to verify any mapping between Azure AD Security Groups and WordPress roles)
  • Save your changes and finally click Grant permissions Updated permissions for registered app

**Please note that if you select User.Read.Basic instead of User.Read.All synchronization of extra profile fields will fail. **


Once you have installed, activated and configured the plugin, you should see a new menu item WPO365 User Sync in your WP Admin Users menu. If you don’t then please verify whether all prerequisites are met. Please note that the plugin will create a new database table to save the results of synchronization job and that this table is created when the plugin is activated. If this table does not exist then please re-activate the plugin one more time.

The feature, when synchronizing, retrieves a list of all Office 365 Azure AD users and searches for matching WordPress users by comparing email addresses (similar to the way the WPO365-login plugin creates WordPress users with their email address i.e. their User Principal Name (UPN) as login name. When no matching WordPress user can be found, the user information will be added to the table Office 365 Azure AD users without a corresponding WordPress user. If you checked Create users it will also immediately create a WordPress user for these users. Finally, it will earmark / tag the existing WordPress users so the plugin knows which WordPress users exist in both Azure AD and in WordPress.

Please note, that new users will always at the very least receive the default role main site. If you have configured roles mappings the plugin will additionally try and retrieve the Azure AD Security Group membership information. For this to work correctly, you must ensure that the Azure AD application registration’s required permissions include Read all Groups.

In addition to retrieving Azure AD Security Group membership information the plugin is capable of retrieving additional user details from Microsoft Graph, if you have configured the plugin to show O365 user fields and configured these extra user fields correctly.

When finished with processing the list of all Office 365 Azure AD users the plugin will search for all WordPress users that have not been tagged. It will add the user information of those users to the table WordPress users without a corresponding Office 365 Azure AD user. Most likely this list contains users that left your company or WordPress-only users. If you checked Delete users all untagged users will be deleted immediately, but please use this option very carefully.

In the third and last table Existing WordPress users with a corresponding Office 365 Azure AD user you will find a list of all existing WordPress users for which a matching Office 365 Azure AD user was found when the synchronization job ran last. If you checked Update users at the top of the User Synchronization page the plugin will try and update the configured extra user fields as well the WordPress role(s) assigned to each user. You can read about the possible WordPress user role update scenarios to understand how the plugin will handle updating the user’s role information.

What follows from the previous paragraph is that the plugin will log the results of a synchronization job in three convenient tables. To view these tables you must click the corresponding links shown at the end of the page:

  • Office 365 Azure AD users without a corresponding WordPress user
  • WordPress users without a corresponding Office 365 Azure AD user
  • Existing WordPress users with a corresponding Office 365 Azure AD user

If you didn’t check Create users or Delete users, you can work with the first two tables to manually select users that you want to create or delete. If you did check one of the options, the tables will still contain the same information, however, do not offer you the possibility to create or delete users. In this case the tables should be considered a log file.

Synchronization Result

Please note that each time when you start a new synchronization job the information of the last run will be truncated. If you want to truncate the results of the last synchronization run you can always click the Truncate results button.

Also note that you can change the number of table rows by adding the following line to your wp-config.php file:

define( 'WPO_USER_SYNC_PAGE_SIZE', 20);

If not found, the page size will default to 10 rows.

Additional considerations

The User synchronization feature will retrieve all users by calling Microsoft Graph and it does by calling the Graph API in batches, each time requesting up to 25 users, to prevent the system from being flooded. However, it’s easy to see that for large tenants with many Azure AD users the process can take several minutes to complete.


    • mvan

      Hi Tas

      Currently it can only be ran manually, also because it uses delegated permissions (instead of application permissions) i.e. the synchronization job needs you to be logged on interactively.

      Best wishes

  1. Tas Gray

    Hi Marco,

    I don’t seem to be able to get the sync to work. But interestingly, if I signin with an Office 365 user it will create an account. Any help you can offer?

    Also, is there a way to get the plugin to bring across the firstname and lastname fields on a user profile? They seem to remain blank.

  2. Daniel FEldbrugge

    If you select the option create user. Will there also be an (activation) email being sent to that user?

    • mvan

      Hi Daniel – No, the user is create “silently” and no email is sent. I’ll take this in consideration for a future release, however – thanks!

  3. Hamwic Education Trust

    We are having trouble with the User synchronisation. It is similar to the Tas Gray issue above. Users are created if they log in using their email address, but the user sync does not work.
    I have followed your setup video about 4 times now to make sure I have not missed anything, but we still seem to have the issue.
    Any assistance appreciated.

    • mvan

      Hi Jai. Most likely it is a permission issue. If you are sure that 1. you actived the User Synchronization feature, 2. you’ve assigned the correct permissions e.g. User.Read.All (make sure you didn’t assign application permissions by mistake), 3. granted permissions as an administrator and 4. finally created an application secret and added the key to the Integration tab of the Wizard, then you may want to delete all tokens (use the button on the Integration tab of the Wizard), log out of WordPress alltogether and sign back in using Microsoft to make sure that you get a set of fresh tokens. Please let me know if this helped you overcome this hurdle – Otherwise, feel free contact me directly through the contact form.

  4. Tomas


    When a user info has been updated or a new user have been added in Office 365 Azure AD, will it sync to WordPress automatically? Or do the WP Administrator every time need to update manually (which will be quite difficult if there´s a lot of updates on regular basis).

    If there´s no auto syncing currently, will there be? Possible to use a cron job or something.

    • mvan

      Hi Tomas. Initially permissions to access Microsoft Graph (used to sync users) were configured as “delegated” permissions. This meant that a logged-in user is required to access Microsoft Graph. In the meantime the plugin also supports “application” permissions, but User sync has not yet been implemented in an asynchronous way. Therefore you’ll still need to start it manually. This may change, however, in the course of this year.

Leave a Reply

Your email address will not be published. Required fields are marked *