SSO | SAML 2.0 - Manual configuration

Deprecation notice

Starting with WPO365 v25.0 the recommended approach to configure SAML 2.0 based SSO is an automated one that involves the generation, export and import of metadata XML files (see https://docs.wpo365.com/article/100-single-sign-on-with-saml-2-0-for-wordpress).

Use this guide if you want to manually configure the SAML based single sign-on capability of the WordPress + Microsoft Office 365 / Azure AD plugin. Also see the following video https://youtu.be/_yMsAKF7hxc.

Perform the following steps to configure the SAML Service Provider portion of the Enterprise application.

Scroll to the Basic SAML Configuration panel and click Edit.
Enter your website's absolute URL as Identifier (Entity ID) e.g. https://www.example.com/.
Enter again your website's absolute URL as Reply URL (Assertion Consumer Service URL) e.g. https://www.example.com/. This is where Azure AD will redirect the user together with the SAML response after the user signed in with Microsoft.
Leave the Relay State empty. The WPO365 plugin will determine where to redirect the user after successful authentication.
Enter your website's absolute logout form URL as Logout Url e.g. https://www.example.com/wp-login.php?action=logout.
Click Save to save your configuration.

Please note See https://docs.wpo365.com/article/90-single-sign-out for more information on support for single sign-out, which is supported by the PROFESSIONAL, PREMIUM and INTRANET editions of the plugin.

User Attributes & Claims

Mapping (custom) claims to WordPress user profile fields is a premium feature that requires one of the following addons / bundles CUSTOM USER FIELDS, LOGIN+, SYNC or INTRANET.

For instructions on how to configure this synchronization of Azure AD user profile attributes to WordPress, please check this guide.

SAML Signing Certificate

The SAML response that the Identity Provider (= Azure Active Directory) will send to the Service Provider (= WordPress website) will be encrypted and must be decrypted by the WPO365 plugin before it's processed. The X509 certificate needed for this can be downloaded in this section of the SAML configuration.

Scroll down to the SAML Signing Certificate section.
Click the Certificate (base64) link.
Save the file and change the file extension to .pem e.g. saml-response.pem.
The file will be needed once you will configure the WPO365 plugin's SAML portion.

Set up Name of your Enterprise Application

The last section provides you with 3 links that are needed to configure the Identity Provider of the WPO365 plugin's SAML portion.

Users & Groups

Perform the following steps to assign users and / or groups of users to the Enterprise application to allow them access to the Service Provider (= WordPress website) through the Identity Provider (= Azure Active Directory).

Click Users and groups in the Enterprise application menu.
Click + Add user.
Click Users and then search for users in the panel that opens to the right.
Once you finished adding users click Select.
Return to the Single sign-on page for the following step to configure the WPO365 plugin.

Plugin configuration

Perform the following steps, to configure the plugin to use SAML based single sign-on.

Leave the Enterprise application that you created and configured open in on browser tab.
Open a new browser tab and navigate to WP Admin > WPO365 > Single sign-on.
If not yet enabled, then toggle Single Sign-on enabled.
Select Azure AD (default) as the Identity Provider (IdP).
Select SAML 2.0 as the SSO-Protocol.
Check whether the proposed SP - Base URL corresponds to your WordPress website's home address URL.
Scroll to the 4th section on the SAML configuration page of the Enterprise application.
Copy the Azure AD Identifier from the Enterprise application and paste it as IdP Entity ID e.g. https://sts.windows.net/9be34e84-6f85-xxxx-xxxx-xxxxxxxxxxxx/
Copy the Login URL from the Enterprise application and paste it as IdP Single Sign-on Service URL e.g. https://login.microsoftonline.com/9be34e84-6f85-xxxx-xxxx-xxxxxxxxxxxx/saml2
Copy the Logout URL from the Enterprise application and paste it as IdP Single Logout Service URL e.g. https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0
Scroll up to the first section of the SAML configuration page of the Enterprise application.
Copy the Identifier (Entity ID) from the Enterprise application and paste it as SP Entity ID e.g. https://www.example.com/.
Copy the Reply URL (Assertion Consumer Service URL) from the Enterprise application and paste it as SP Assertion Consumer Service URL e.g. https://www.example.com/.
Copy the Logout Url from the Enterprise application and paste it as SP Single Logout Service URL e.g. https://www.example.com/wp-login.php?action=logout.
Now open the X509 certificate that you downloaded previously in a notepad, copy it to the clipboard and paste it as X509 Certificate. Ensure to include the first (----- BEGIN ...) and last line (-----END ...) and the new line break after the last line.
In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
Navigate to Azure Active Directory > Properties.
Copy the Tenant ID and paste it as Directory (tenant) ID.
Select your desired Authentication scenario 'Intranet' or 'Internet' in the section Inclusions / exclusions.
Check for (custom) domain names in Azure Portal and add these on the User registration configuration page of the WPO365 plugin.

Plugin self-test

On the plugin’s Single Sign-on configuration page 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 configuration menu.
Click Start self-test to check the current configuration and the plugin’s ability to sign a user in with SAML (and optionally an app-only 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.