Support for WordPress Multisite WPMU

Use this guide if you want to configure the WordPress Multisite capability of the WordPress + Office 365 plugin.

Before you start

You have reviewed the installation prerequisites and have installed but not yet network activated the plugin (see Getting started - Installation).
You are a Global Administrator for your company’s Office 365 tenant / Azure AD directory (or have at least the ability to create (or edit an existing) Azure Active Directory App registrations).
You are an Administrator for your WordPress website.

Network activate the plugin

The plugin must be network activated.

Go to My Sites > Network Admin > Plugins.
Click Network activate.

Network Activate does pretty much what it say it does: It activates the plugin on all sites in the network and administrators of subsites no longer have the option to either activate it or deactivate it.

Choose a WordPress Multisite Mode

Network administrators now must choose one of two possible configurations:

Shared All subsites in the network share the same Azure AD App registration. Each user who successfully signs in with Microsoft is always redirected back to your network's main site. After the plugin finished processing Microsoft's authentication response it will redirect the user to the subsite he / she initially requested.
Dedicated Each subsite in the network is treated isolated from the other and each one will have to be configured individually. It is still possible to use a single Azure AD App registration but at the very least you'll need to add each site's URL as Redirect URI. If a subsite is not configured, the plugin will fallback to behave like the shared scenario, using a default configuration that is saved as part of the network configuration.

Mainly if you’d need to isolate each site in the network for reasons of security or if you need support for mapped domains, you should choose the dedicated mode.

Creating new users / adding members to a blog

The plugin treats new users / existing users differently, depending on the aforementioned Multisite Mode and additional WPO365 configuration(s). The following table should help to understand the options available to you.

Desired outcome

Necessary configuration

New user is (not) added to the network's main site.

Dedicated Mode

Since each site is configured individually, the plugin does not differentiate between main site and subsite. Therefore whether or not a new users is added (after the user signed in successfully with Microsoft) is controlled by the Create new users option on the plugin's User registration configuration page.

Shared Mode

Whether or not a new users is added (after the user signed in successfully with Microsoft) to the main site is controlled by the Create new users option on the plugin's User registration configuration page.

New user is (not) added to a subsite of the network.

Dedicated Mode

Since each site is configured individually, the plugin does not differentiate between main site and subsite. Therefore whether or not a new users is added (after the user signed in successfully with Microsoft) is controlled by the Create new users option on the plugin's User registration configuration page.

Shared Mode

Whether or not a new users is added (after the user signed in successfully with Microsoft) to a subsite is controlled by the Do not add user to WPMU subsite option on the plugin's User registration configuration page. Please note that this property is only visible when the the Shared Mode is detected.

Please note

In shared mode the plugin treats a signed-in user slightly different than a user who is not signed in.

A user who is a member of blog A and who has successfully signed in (into blog A) and then tries to navigate to blog B's (administration) dashboard will see the following default WordPress warning "you do not currently have privileges on this site".
If that same user, however, logs out from WordPress and then navigates directly to the blog B's (administration) dashboard and settings do not prevent adding new members to a subsite, will be added.
If settings prevented the users being added automatically, however, the user will see a WPO365 USER NOT FOUND error (because the user could not be added).

Recommended configuration Shared Mode

The shared scenario doesn’t need to be configured, as it’s the default scenario. To configure the WPO365 | LOGIN plugin and its single sign-on, as a network administrator, you will need to navigate to WP Admin > My Sites > Network Admin > Dashboard and then click WPO365 from the main admin menu on the left. Please note the following recommended configuration:

WordPress Site URL (main site)	https://your-website.com/
Azure AD Redirect URL	https://your-website.com/
COOKIE_DOMAIN	.your-website.com

Please note

To view the WordPress Site URL navigate to WP Admin > My Sites > Network Settings > Sites.
To change the Azure AD Redirect URL navigate to WP Admin > My Sites > Network Admin > Dashboard > WPO365 > Single sign-on, scroll down to Redirect URL and click the View in Azure Portal and make sure that you copy the exact value from Azure Portal over to the corresponding WPO365 setting.
To change the COOKIE_DOMAIN please edit your wp-config.php file and add the line define('COOKIE_DOMAIN', 'your-website.com'); just below the line that reads /* That's all, stop editing! Happy publishing. */.

Important The recommended configuration would give any user who can sign in with Microsoft basically access to the main site and the subsites of the network, even when that user is not a member of those subsites. If you don't want this, then please configure the dedicated mode instead, or at least edit your wp-config.php file with add the line define('COOKIE_DOMAIN', $_SERVER[ 'HTTP_HOST' ] );

Recommended configuration Dedicated Mode

To configure the dedicated scenario, you should update the configuration and add the following line to your wp-config.php

define( 'WPO_MU_USE_SUBSITE_OPTIONS', true );

immediately above the line

/* That's all, stop editing! Happy publishing. */

And after the line

define('BLOG_ID_CURRENT_SITE', 1);<br>

If you don’t add this line or add it but set WPO_MU_USE_SUBSITE_OPTIONS to false, the plugin will select the default shared scenario.

When you configure the dedicated scenario you must configure the WPO365 | LOGIN plugin and its single sign-on for each subsite by navigating to each subsite's WP Admin (Dashboard) and then click WPO365 from the main admin menu on the left. However, you can define a default configuration when you navigate to WP Admin > My Sites > Network Admin > Dashboard > WPO365. Perform the following steps to create a local copy of the default (central) configuration for the current subsite.

Go to WP Admin > WPO365 > ... > Import / Export for the subsite in question.
Locate the line Copy central WPO365 configuration (WordPress multisite) and click Copy options. Please note that this is a destructive action and will replace the existing configuration of the subsite in question.
The Copy options will automatically replace the Redirect URI options in a configuration with the subsite's home URL address. But you must still manually add that URL to list of Redirect URIs on the App registration's Authentication page in Azure AD (also see the comment immediately beneath the table below).

The following is the recommended default configuration for the dedicated scenario:

WordPress Site URL	https://www.your-website.com/
Azure AD Redirect URL	https://www.your-website.com/
COOKIE_DOMAIN	$_SERVER[ 'HTTP_HOST' ]
DOMAIN_CURRENT_SITE	www.your-website.com

Then for each subsite that you want to configure you must add your subsite's WordPress Site URL as a new Azure AD Redirect URL in Azure to the list of Redirect URIs on the Authentication page of the App registration that you configured for your WordPress website.

Please note

To view the WordPress Site URL navigate to WP Admin > My Sites > Network Settings > Sites.
To change the Azure AD Redirect URL navigate to WP Admin > WPO365 > Single sign-on for the specific subsite, scroll down to Redirect URL and click the View in Azure Portal and make sure that you copy the exact value from Azure Portal over to the corresponding WPO365 setting.
To change the COOKIE_DOMAIN please edit your wp-config.php file and add the line define('COOKIE_DOMAIN', $_SERVER[ 'HTTP_HOST' ] ); just below the line that reads /* That's all, stop editing! Happy publishing. */.

Please note that for dedicated mode you should configure $_SERVER[ 'HTTP_HOST' ] as the COOKIE_DOMAIN. This basically tells WordPress to set a cookie for the correct subdomain or mapped domain the user requested.

Important When you choose the dedicated scenario and

Users can sign into the network's main site with Microsoft
The main site's address is https://your-website.com/

Then users will obtain an authentication cookie for your-website.com and this may give them unexpected access to any of the subsites of the network e.g. https://subdomain.your-website.com/ or worse it may confuse WordPress and users end up in an infinite loop. To work-around this, it is recommended that instead you make your main site exclusively available under https://www.your-website.com/. In that case users will obtain an authentication cookie for www.your-website.com which won't allow them access to any of the subdomains.

To change your primary domain of your network from your-website.com to www.your-website.com you can perform the following steps:

Note: As this requires custom configuration regarding coding on your WordPress files, this falls outside the scope of support offered by Downloads by van Wieren. This article is for informational purposes only.

Before you start making the following changes navigate to WP Admin > My Sites > Network Admin > Dashboard > WPO365 > ... > Miscellaneous and delete the current WPO365 | LOGIN configuration.
Navigate to the main site itself WP Admin > Dashboard > WPO365 > ... > Miscellaneous and delete the current WPO365 | LOGIN configuration.
In the wp_options table look for the entries named “siteurl” and “home” and change them to https://www.your-website.com/.
In the wp_site table look for the entry named "siteurl" and change it to https://www.your-website.com/.
In the wp_blogs table look for the entry in the "domains" column that have the old domain name and update it to https://www.your-website.com/.
In the wp-config.php file look for the DOMAIN_CURRENT_SITE and change it to define('DOMAIN_CURRENT_SITE', 'www.your-website.com' );
Now you can recreate the WPO365 | LOGIN configuration(s) and make sure to add the new Redirection URIs on the App registration's Authentication page.

Single sign-on

To configure the single sign-on capability of the WordPress + Office 365 plugin for either scenario, please consult the Getting started - Single sign-on documentation.

Please keep in mind that when you opt for the Dedicated scenario you can basically use one and the same Azure Active Directory App registration for all subsites but at the very least you'll need to add each subsite's URL as separate Redirect URI on the App registration's Authentication page.

Integration

To configure the Integration (e.g. with Microsoft Graph and SharePoint Online) capability of the WordPress + Office 365 plugin for either scenario, please consult the Getting started - Integration documentation.

Related configurations

If you combine the power of WordPress Multisite and the WordPress + Office 365 plugin, you can also

Redirect users from a central login to their subsite by configuring a mapping table between Azure AD groups on the one and WordPress subsites on the other hand read more.
Configure a default role for a new user for a subsite read more.

Troubleshooting

The plugin tries to catch as many exceptions as possible, especially those that cause the user to be trapped in an infinite loop. Still, if users complain about this then consult the corresponding knowledge base article https://docs.wpo365.com/article/5-infinite-loop.