Before you start
- You have reviewed the installation prerequisites and have installed and 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 register new applications).
- You are an Administrator for your WordPress website.
The only exception is when you host your (development) website on 'localhost'. This restriction is enforced by Microsoft to protect oauth / ID tokens being exchanged between the Azure Active Directory endpoint and your website.
- Your WordPress Administrator login name does not equal your Office 365 (Azure AD) login name or email address and your WordPress Administrator email address does equal your Office 365 (Exchange) email address.
When your WordPress login name does not equal your Office 365 (Azure AD) login name or email you can still log into your WordPress website when you navigate to https://www.example.com/wp-login.php (even when you configure the PROFESSIONAL edition capability to intercept manual login attempts). However, because your email address does match with a valid Office 365 email address, the plugin can also sign you in with Microsoft. This way - as an administrator - you avoid not being able to sign into your own website.
- 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.
- Click + New registration.
- Enter any name that helps you remember what application you are currently registering e.g. 'WordPress Intranet | Production'.
- Scroll down to ‘Supported account types’ and select an option as you see fit e.g. Accounts in this organizational directory only.
- Choose the ‘Platform configuration’ Client Application (Web, iOS, Desktop+Devices).
- Click Register.
- Click Authentication from the 'App registration' menu on the left (if not already loaded).
- Click + Add platform to add a new ‘Platform configuration’.
- Click Web to add a new ‘Web application’.
- Enter the Redirect URI of the application.
At this point you can switch back to the browser tab with the plugin’s wizard open and copy the automatically proposed Redirect URI from the the ‘Single Sign-on’ tab of the plugin’s wizard.
Please not that if your intention is to use the WPO365 plugin for your internet website (in other words, when you do not want to restrict access to all pages and posts of your WordPress website to users that signed in with Microsoft) you should change the proposed Redirect URI before you copy it and add wp-admin/ e.g. https://www.your-website.com/wp-admin/ (include the trailing slash).
- Scroll down to ‘Implicit grant’ and check ID tokens for the plugin to request this token from Microsoft.
- Optionally check Access tokens. For further instruction on how to configure integration of Office 365 / Microsoft Graph with WordPress see Getting Started - Access tokens.
- Click Token configuration from the 'App registration' menu on the left.
- Click + Add optional claim.
- Select ID.
- From the list check the following options
- family name
- given name
- Optionally click + Add groups claim if you want enable features of the PROFESSIONAL, PREMIUM or INTRANET edition of the plugin e.g.
- Azure AD + WordPress role mapping when users sign in with Microsoft.
- Denying access to users based on Azure AD / Office 365 group membership(s).
- Click API permissions from the 'App registration' menu on the left
- Click + Add permission.
- Select Microsoft Graph > Delegated permissions and check
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’.
- In 'Azure Portal' navigate to the application registration’s Overview page and copy the 'Directory ID' and paste it into the corresponding field on the plugin’s wizard Single Sign-on tab.
- Repeat the previous step and copy the 'Application ID' and paste it into the corresponding field on the plugin’s wizard Single Sign-on tab.
- Select your desired Authentication scenario 'Intranet' or 'Internet'.
- Enter a Domain hint e.g. 'custom-domain.com'.
A domain hint helps Microsoft to decide whether a user already has a valid (login) session for the domain hinted at. Under normal circumstances you don’t need to configure this hint. However, more and more users have accounts in multiple Office 365 / Azure AD tenants or work on computers where users have previously logged on to different Office 365 / Azure AD tenants. For example, at home a family member may have logged on to the Office 365 / Azure AD tenant of his / her school or university.
- Check for (custom) domain names in Azure Portal and add these on the User registration page of the plugin's wizard in the corresponding field(s).
Create a WordPress (test) user
Please note that the following information only applies to the BASIC edition of the plugin. The PROFESSIONAL, PREMIUM and INTRANET edition will create new WordPress users with user names and email address set to match their Office 365 details automatically. However, for the BASIC edition you must do so manually by creating a user with
- A WordPress username that matches your (test user’s) Azure AD / Office 365 username e.g. 'firstname.lastname@example.org' or 'email@example.com' when you added a custom domain to Azure Active Directory (see Custom domain names in Azure Portal).
- And / or a WordPress email address matches your (test user’s) Azure AD / Office 365 email e.g. 'firstname.lastname@example.org' (note that often Office 365 / Azure AD login names and their email addresses are the same).
Please note that the Plugin self-test is available from mid-January 2020 (v9.6).
- On the plugin’s wizard 'Single Sign-on' tab click Test + Save configuration.
- A popup window will open and you’re reminded to optionally clear server-side cache (if you didn’t do so at the start).
- Click Confirm and you’ll be automatically taken to the ‘Plugin self-test’ page.
- Alternatively you can simply click Plugin self-test from the plugin's wizard menu.
- Click Start self-test to check the current configuration and the plugin’s ability to retrieve an ID token (and optionally an 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.