SAML 2.0 based single sign-on

Use this guide if you want to 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).

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 a new  Enterprise Application).
  • 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 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.

Important information

The plugin, by default, supports OpenID Connect based single sign-on. However, as this article will explain, it is possible to instead configure the plugin to support SAML 2.0 based single sign-on. There are many differences between the two (see https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-vs-authorization for details) but one important difference is the fact that SAML is only for authentication whereas OpenID Connect can be used to authenticate a user and get authorization to access - for example - Microsoft 365 services (using OAuth 2.0) in one request.

Unfortunately, when SAML is used to authenticate a user, the plugin cannot get authorization for that user to access - for example - Microsoft 365 services (using OAuth 2.0). This means that the Microsoft 365 Apps that ship as part of the plugin e.g. for Power BI, Content by Search (SharePoint Online), Documents (SharePoint Online / OneDrive) and Employee Directory (Microsoft Graph) can not be used.

On the other hand, all capabilities of the premium plugins such as retrieving custom user profile fields and images and map those to WordPress and / or BuddyPress (extended) profile fields and avatars, retrieving all (Azure AD and Microsoft 365) groups a user is a member of, would still work as expected when configure a so-called app-only access token. See https://docs.wpo365.com/article/101-app-only-integration for details.

Enterprise Application 

  • In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
  • Navigate to Azure Active Directory > Enterprise applications.
  • Click + New application.
  • Click Create your own application.
  • Enter a name that helps you remember what application you are currently registering e.g. 'WordPress Internet SAML | Production'.
  • Select the option that you want to Integrate any other application you don't find in the gallery.
  • Click Create to create the new Enterprise application.
  • Click Add (and wait until the Overview page automatically appears).
  • Click Single sign-on in the Enterprise application's menu.
  • Select SAML to continue.

Or follow these instructions if you still using the old app gallery experience.

  • In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
  • Navigate to Azure Active Directory > Enterprise applications.
  • Click + New application.
  • Click Non-gallery application to continue.
  • Enter a name that helps you remember what application you are currently registering e.g. 'WordPress Internet SAML | Production'.
  • Verify that in the list of supported features SAML based single sign-on is listed.
  • Click Add (and wait until the Overview page automatically appears).
  • Click Single sign-on in the Enterprise application's menu.
  • Select SAML to continue.

Basic SAML Configuration

The Basic SAML Configuration section defines the so-called Service Provider (SP) that wants to connect to the Identity Provider (IdP) so it can benefit from single sign-on. In this case your WordPress website is a Service Provider that wants to connect to Azure Active Directory that is the Identity Provider. 

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.
  • Enter your website's absolute login form URL as Sign on URL e.g. https://www.example.com/wp-login.php.
  • 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 Sometimes the IT department requires you to provide an XML based metadata file instead. In that case, use the guidance provided in the previous step to create an XML based metadata file for the Service Provider portion of the Enterprise Application configuration using this tool.

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

Currently the plugin does not support (custom) claims other then the default ones for givenname, surname, emailaddress, name and Unique User Identifier. To retrieve custom user profile fields and profile images and map those to WordPress and / or BuddyPress (extended) profile fields and avatars, the (PREMIUM and INTRANET edition of the) WPO365 plugin can connect to Microsoft Graph instead. See https://www.wpo365.com/extra-buddypress-profile-fields-from-azure-ad/ for details. 

To enable Microsoft Graph integration with SAML you must configure a so-called app-only access token. See https://docs.wpo365.com/article/101-app-only-integration for details.

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.
  • Click Show advanced configuration options.
  • Check Use SAML 2.0 (instead of OpenID Connect), read the information in the popup and click Confirm to continue.
  • Enter your website's home address as Base URL e.g.  https://www.example.com/.
  • 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.
  • 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'.
  • 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.

Advanced settings

Since version 11.14 of the plugin it is possible to configure advanced settings for the (OneLogin) SAML 2.0 library (see https://github.com/onelogin/php-saml for an example of such settings). This may be needed if you need to allow for multiple authentication options when users receive - for example - the following error Authentication method 'WindowsIntegrated' by which the user authenticated with the service doesn't match requested authentication method 'Password, ProtectedTransport'. 

Advanced settings need to be added as a PHP constant to your wp-config.php file. The following example illustrates how you can add support for the WindowsIntegrated authentication method.

define( 'WPO_SAML2_ADVANCED_SETTINGS', 
    array( 
        'security' => array(
            'requestedAuthnContext' => array (
                'urn:federation:authentication:windows',
                'urn:oasis:names:tc:SAML:2.0:ac:classes:Password',
                'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport',
            )
        ) 
    )
);

/* That's all, stop editing! Happy publishing. */

Troubleshooting

Some customers have reported that users that are on an AAD joined device that are also using Windows Hello for Business will have their MFA claim attached to their primary refresh token, meaning that non-incognito authentication attempts via Edge, or Chrome with the Windows 10 Accounts or Office Online extensions, will supply an authentication type of X509, multifactor. This is problematic because it does not appear that there is an option to include a multifactor designation alongside X509 in the requestedAuthnContext, which in turn means that such an authentication type will not work against an SSO application that specifies an array for requestedAuthnContext. Setting that value to false using advanced settings added to your wp-config.php (see the previous paragraph) seems the best thing to do in that case.

define( 'WPO_SAML2_ADVANCED_SETTINGS', 
	array(
		'security' => array(
			'requestedAuthnContext' => false 
		)
	)
);

/* That's all, stop editing! Happy publishing. */
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us