SSO | OpenID Connect - Hybrid flow

Deprecation notice

On the 4th July 2022 version 18.0 of the WPO365 | LOGIN has been published. This version is fully compatible with the configuration for previous version(s) but at the same time allows admins of existing installations and newcomers at the same time a few more alternatives, for example:

Configure the Authorization Code User Flow (for OpenID Connect based single sign-on)
Improved support for Azure AD B2C and multi-tenancy
The ability to disable single sign-on

. To accommodate this new options the WPO365 configuration pages have been updated and the new SSO Getting started guide. will help you getting the WPO365 plugin set up in no time.

Please note Users that haven't upgraded yet and use a version of the plugin < 18 should continue with this getting started guide.

Introduction

Use this guide if you want to configure the single sign-on capability of the WordPress + Office 365 plugin (also see the following video https://youtu.be/h2rXZGjir8k).

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.
Your website uses SSL and the internet address starts with https://.

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 premium editions' 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.

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.
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.

Organizational directory only basically prevents users from other Office 365 accounts to sign into your WordPress website using this registration. To allow this see https://www.wpo365.com/wordpress-extranet/.

Scroll down to ‘Redirect URI’ and select Web from the platform dropdown list.

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).

Enter the Redirect URI of the application.
Click Register.

Authentication

Click Authentication from the 'App registration' menu on the left (if not already loaded).
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.

Token configuration

Click Token configuration from the 'App registration' menu on the left.
Click + Add optional claim.
Select ID.
From the list check the following options
- email
- family name
- given name
- upn

Please note that the information below only applies to older versions of the BASIC edition of the plugin. Since version 11.0 premium the premium extensions LOGIN+, SYNC and INTRANET will always retrieve all the (Azure AD / Office / Distribution list) groups a user is member of from Microsoft Graph (because of the ID token's limited capacity of max. 200 groups). For the plugin to be able to retrieve all groups the user is a member of, you must configure the Integration portion of the plugin (see https://docs.wpo365.com/article/23-integration for details).

Optionally click + Add groups claim if you want enable features of the LOGIN+, SYNC and 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).
Select Security groups.
Click Add.

API Permissions

Click API permissions from the 'App registration' menu on the left
Click + Add permission.
Select Microsoft Graph > Delegated permissions and check
- email
- openid
- profile
Click Add permissions.

Please note that you should not delete the default User.Read permission.

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 you must grant admin consent for all selected permissions and not only for those where is written that Admin consent is required. If you do not grant admin consent for all permissions, users are required to so themselves but they are not able to do so when the plugin retrieves a token on their behalf (and therefore users cannot be challenged directly).

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 grand 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: 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.

Plugin configuration

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 older versions of the BASIC edition of the plugin. Since version 11.0 the WPO365 | LOGIN (free) edition and all premium extensions such as PROFILE+, LOGIN+, SYNC and INTRANET will create new WordPress users. However, only the premium extensions will retrieve a user's first, last and full name plus email address from Microsoft 365.

If you need to manually create a WordPress (test) user to match with a user that signs in with Microsoft then configure that user so that:

The WordPress user's username matches that user's Azure AD / Office 365 username e.g. 'john.doe@your-tenant.onmicrosoft.com' or 'john.doe@custom-domain.com'.
And / or the WordPress user's email address matches your user's Azure AD / Office 365 email e.g. 'john.doe@custom-domain.com' (note that often Office 365 / Azure AD login names and their email addresses are the same).

Plugin self-test

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.