Synchronize users from Azure AD to WordPress [deprecated]

Deprecation notice

This article is no longer maintained. Please follow the instructions in this article instead: https://docs.wpo365.com/article/57-synchronize-users-from-azure-ad-to-wordpress.

Use this guide if you want to configure / schedule the synchronization of (Office 365 / Azure AD) user to WordPress with the WordPress + Office 365 plugin.

Before you start

You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.
If you also plan to synchronize users from Azure AD to WordPress and you would like the mappings you are about to configure to be applied whenever you synchronize users, then you must also already 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.

Enable user synchronization

Navigate to the plugin's wizard WP Admin > WPO365 and click User Sync.
Check Enable user sync.

Prevent WordPress to send "email changed" emails

Go to WP Admin > WPO365 > ... > Miscellaneous and check the option to prevent WordPress to send "email changed" emails (see https://docs.wpo365.com/article/115-prevent-wordpress-to-send-email-changed-email for details).

App permissions

Review the App permissions you previously configured in Azure Portal when you registered an App in Azure AD for your WordPress website (see https://docs.wpo365.com/article/23-integration) and ensure that you have assigned Group.Read.All and User.Read.All permissions to your App if you intend to manually start user synchronization.
If you intend, however, to schedule user synchronization, you must register another App in Azure AD so that your website can access Microsoft Graph when you are not logged in (app-only access, see https://www.wpo365.com/use-app-only-token/ for details). Please refer to this article https://www.wpo365.com/app-only-application-id/ for details on how register the second App in Azure AD and assign it Application Permissions for Group.Read.All and User.Read.All.

Query

You can control which users are synchronized to your WordPress website by updating the User sync query.

Navigate to WP Admin > WPO365 > User sync.
Scroll down to User sync query.
Update the query according to your needs. Make sure that the query always returns an array (possibly empty) of Microsoft Graph User Resources (and not a single user object). To test your query, consider using Microsoft's Graph Explorer https://developer.microsoft.com/en-us/graph/graph-explorer. Also see
- https://docs.wpo365.com/article/8-synchronize-only-users-belonging-to-a-specific-azure-ad-group
- https://www.wpo365.com/user-sync-query/
Scroll down and click Save configuration.

Synchronizing users

Once you have enabled user synchronization and ensured that all permissions are configured for your App(s) in Azure AD, you should see a new menu item WPO365 User Sync in your WP Admin > Users menu (you may need to refresh the page once). If you don’t then please verify whether all prerequisites are met.

Important The plugin will create a new database table to save the results of synchronization job and this table is created when the plugin is activated. If this table does not exist then please re-activate the plugin one more time.

When synchronizing, the plugin 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.

Important 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 Groups.Read.All.

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.

Scheduling user synchronization

Since v10.0 the plugin offers a new exciting preview of a feature that allows you to schedule the synchronization of users.

You can schedule a new (WordPress cron) job to synchronize users as follows.

Navigate to WP Admin > Users > WPO365 User Sync.
Check one or more of the available options to Create, Update or Delete users.
Check (Re-)Schedule user synchronization.
Configure when the job should ideally be executed by selecting a recurrence and time of the day.
Click Schedule synchronization.

If the job has been saved successfully, you will see an information about the next scheduled instance of the job and its configuration.

Click Delete schedule to delete the job.

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 10 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. When you execute user synchronization manually, you will notice the page being reloaded many times. When executing the user synchronization on a schedule, however, each batch is executed as yet another cron job (see next point).
Keep in mind that scheduled user synchronization relies on WordPress cron jobs. WordPress cron will only be triggered on page load - i.e. when someone visits a page on your site. This means that, for example, if you have a task scheduled for 4:00 PM but do not have any visitors until 10:00 PM your task will not run until then.
The plugin will send Administrators an email once the synchronization is ready.