Support for multitenant apps

Use this guide if you want to configure support for the multi-tenancy capability of Azure Active Directory applications and enable it for the WordPress + Office 365 plugin. You can use the multi-tenancy capability of Azure AD to allow accounts from any organizational directory (rather than only your own) to access your WordPress website.

Before you start

You have purchased the premium extension WPO365 | LOGIN+ to be able to support the Azure AD multitenancy feature (or any of the bundles WPO365 | SYNC or WPO365 | INTRANET).
You are fully aware of the consequences of allowing users in any Azure AD tenant to sign in to your application after consenting to use their account with your application.
You have understand the difference between Azure Active Directory Guest users and users from another organizational directory (see https://www.wpo365.com/guest-users-or-multi-tenant/ for details).
You must already have configured the single sign-on capability of the WordPress + Office 365 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.

App registration

In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
Navigate to Azure Active Directory > App registrations.
Select the App registration that you created when you configured the single sign-on capability of the plugin.

Authentication

Click Authentication from the 'App registration' menu on the left.
Scroll down to Supported account types.
Check Accounts in any organizational directory (Any Azure AD directory - Multitenant).
Click Save.

Please note that if you'd like to add users with personal Microsoft accounts (MSAL e.g. Outlook, Skype, Xbox) that you need to manually update the manifest as explained on the page.

User registration

Navigate to the plugin's wizard WP Admin > WPO365 and click Single Sign-on.
Check the option Allow users from other tenants.

Optionally, if you would like to synchronize user attributes e.g. companyName or the user's profile picture you should add Multi-tenant API Permissions. Perform the following steps to accomplish this:
- Add https://graph.microsoft.com/User.Read to the list of Multi-tenant API Permissions.
- Click + to add the permission to the list

Click Save configuration.

Please note Adding permissions to the list here will require users from the other domain to grant their consent. Alternatively, a (global) administrator can grant consent on behalf of all users for the other domain, as shown in the example below.

Domain whitelist

Optionally, you can restrict access to your website to users coming from selected domains.

Navigate to WP Admin > WPO365 > User registration.
Allow users coming from specific domains by adding domains those domains to the list of Allowed (login) domains (see https://docs.wpo365.com/article/43-domain-whitelist for details).

Authorization

Please note If an individual user (or an administrator on behalf of all users) already granted consent using the method explained before in the paragraph User registration then authorization is already given and you can safely skip this paragraph.

For the plugin to be able to retrieve information about a user from another tenant e.g. the user's companyName or profile image, it must be able to request access tokens from that user's (Azure AD) tenant. By default, the plugin is capable of requesting information from another tenant if multi-tenancy is configured according to the steps outlined in this article. However, before the plugin successfully can request data, an administrator of the other tenant must have granted permissions to the Enterprise Application that will be automatically created in the other tenant's Azure AD as soon as a first user of that other tenant successfully signs in with your multi-tenanted App registration.

Perform the following steps to find the Enterprise Application in another tenant's Azure AD.

As an administrator of another tenant with sufficient privileges first navigate to Azure Portal Azure Active Directory Enterprise applications.
From the drop down list Application type be sure to select All applications and then search for the Application (client) ID that was assigned to the App registration for the WordPress website in the home tenant.
Click on the name to load the Overview page of the Enterprise application.
Continue to the Permissions page (in the Security section) and click Grant consent for ...

Only when an administrator of another tenant has granted consent will the plugin be able to request access tokens for users of another tenant.

Please bear in mind that many administrators have locked down their Azure AD and the ability for users to add third party applications. Therefore it is recommended that users from other tenants are made aware of the fact that they may not be able to sign into your application after all and if that is the case that they should get in contact with their global tenant administrator.

Synchronize user attributes

Complete the following steps to synchronize user attributes from users from other tenants.

Ensure that you have added at least https://graph.microsoft.com/User.Read to the list of Multi-tenant API Permissions as explained in the paragraph User registration at the beginning of this article.
Then go to WP Admin > WPO365 > User sync and add the fields you want to synchronize e.g. companyName and employeeId as shown below.

To add a user attribute to the list, perform the following steps:
- Add the property name in the first field e.g. companyName (see https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-beta#properties for all available properties).
- Then add the friendly name in the lower of the two fields e.g. Company.
- Click + to add the attribute to the list.
Scroll down and click Save configuration.
Go to WP Admin > WPO365 > Integration and select the beta version for the Graph API (the beta API will return significantly more fields).

Scroll down and click Save configuration.

Test and Troubleshoot

To test your multitenant app you can log on with a (test) user that is a member of a different Azure AD tenant.

Enable the plugin's Debug log (see https://docs.wpo365.com/article/19-enable-debug-log).
Navigate to the plugin's wizard WP Admin > WPO365 > ... > Debug.
Check Log ID token.
Now try to sign in again with the (test) user that is a member of a different Azure AD tenant.
Navigate back to WP Admin > WPO365 > ... > Debug and click Show all.
Search for the ID token in the log and check to see if it is complete.