Integration

Use this guide if you want to configure the integration capability of the WordPress + Office 365 plugin for it to be able to request access tokens needed to request data from Microsoft Services such as Microsoft Graph and SharePoint Online (also see the following video https://youtu.be/DmRZbKGminE).

Before you start

You must already have configured the single sign-on capability of the WordPress + Office 365 plugin.

When a user signs into your website with Microsoft the help of the plugin, an additional 'Authorization code' is received that is needed to request access tokens. Therefore the integration capability of the plugin will only work for users that actually signed in with Microsoft.

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.

Authentication

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.
Find the App registration that you created for the WordPress website.

If there are many App registrations and you cannot determine which one was created for the WordPress website you can go the plugin's wizard and activate the Single Sign-on tab, copy the 'Application ID' and search for it.

Scroll down to ‘Implicit grant’ and check Access tokens for the plugin to request such tokens from Microsoft.

API Permissions

Click API permissions from the 'App registration' menu on the left.
Select Microsoft Graph > Delegated permissions.
- offline_access (because if you don't allow this the app won't be able to request refresh tokens and all requests for access tokens after the first will fail)
Scroll down to Group and check
- Group.Read.All (if your intention is to enable Azure AD + WordPress role mapping when synchronizing users)
Scroll down to Sites and check
- Sites.Read.All (if your intention is to use the Documents app).
Scroll down to User and check
- User.Read.All (if your intention is to enable retrieving additional Office 365 User Fields when synchronizing users and / or your intention is to use the Employee Directory app).
Click Add permissions.
Select SharePoint > Delegated permissions and check
- Sites.Search.All (if your intention is to use the Content by Search app).
Click Add permissions.
Wait until Grant admin consent for … has become available, then click to grant consent for all users in your tenant to use this ‘App registration’.

Please note that it can take up to several minutes before the consent button becomes available and can be clicked. And even after that you may see a red warning that consent could not be granted. If you see this warning, please repeat the sequence and click to gran consent for all users in your tenant again.

After you clicked to grant consent please wait until any spinner has disappeared to ensure that consent has been granted.

Last but not least: Even after waiting for several minutes and all indicators showing you that consent has been granted, it may take a few more minutes before the App registration becomes fully functional and the ID token contains the upn, email, given and family name. If the Plugin self-test later on fails but you are convinced that you did everything right, then wait a few more minutes and repeat the self-test.

Certificates & Secrets

Click Certificates & Secrets from the 'App registration' menu on the left.
Click + New client secret.
Give the new secret a name that helps you remember it later and choose an expiry date e.g. Never.
Copy the secret - e.g. in a Notepad application - as soon as you save it. You won’t be able to retrieve it later.

Plugin configuration

Navigate to the Integration page of the plugin’s wizard and copy the Client secret that you just created and copied to the side.
Select your preferred Microsoft Graph version (recommended is Beta).
Enable the Token service if you’re planning on deploying any of the client-side apps that ship with the plugin e.g.
- Content by Search (SharePoint Online)
- Documents (SharePoint Online / OneDrive)
- Employee Directory (Microsoft Graph)
Enable the Check nonce for improved security.

If you are updating an existing configuration then click Delete tokens to ensure that all existing access tokens are deleted and any changes you made are reflected by new fresh tokens retrieved from the Azure AD endpoint.

Plugin self-test

Please note that the Plugin self-test is available from mid-January 2020 (v9.6).

Click Plugin self-test from the plugin's wizard menu.
Check the option to Test access token(s).
Click Start self-test to check the current configuration and the plugin’s ability to retrieve a valid access token.

As soon as the self-test is starting, the ‘Test mode’ will be activated. During this time the plugin is not protecting your website. The plugin will now try and sign in using Microsoft and you may be prompted by Microsoft to sign in. Please be aware that at no time your authentication input will be shared with (y)our website and or the plugin: All information you enter is only shared with Microsoft at all times!

Once the self-test is finished (during the self-test the page may be reloaded) you will see the test results. You can click on each entry in the list to view the full details incl. category, severity and a proposed resolution to fix the issue.