How to enable Single Sign-On (SSO) to WordPress using Azure AD and the OneLogin SAML SSO plugin.
Here at Cloudrun, we allow clients to login to the website using their own Office 365 credentials (as guests), with SSO (Single Sign-On), as well as being able to login using our own Azure AD or on-premises (federated) AD credentials. So we thought we’d share how to do this, it’s pretty straight forward once you know how!
Note that you can do this using an internal server e.g. for testing or dev, some people get confused and think that Azure will need to talk to their WordPress server, but that is absolutely not the case, just the browser needs to be able to connect to both, so the server can be internally accessible only as long as it can connect to the internet as well.
Also note that this does require Azure AD Premium in addition to your normal Office 365 subscription, so you need to have this as part of EMS or a standalone Azure AD P1 or P2 license. You can get a trial.
- Take a WordPress backup
- Make sure you have a local WordPress admin account, e.g. not just a WordPress.com account, since that option will not be available once SSO is enabled.
Install the OneLogin SAML SSO plugin
First install this plugin, see https://wordpress.org/plugins/onelogin-saml-sso/ for more information. It’s pretty basic but importantly it works, and has the bonus of being free. The documentation is somewhat sparse, which is where this post may be useful if you are having trouble.
The config involves going back and forth between WordPress and Azure AD, so make sure you can login to both.
- In wp-admin, navigate to Settings > SSO/SAML Settings.
- Configure a Service Provider Entity Id (2/3 down the page), we used cloudrun-dev. Otherwise you will have conflicts if you have multiple environments or sites. Save the config.
- At the top, there is a link which says: ‘Go to the metadata of this SP’. Click this, and save it as an XML file.
- Now go to https://portal.azure.com and open Azure AD
- Click Enterprise Applications > New Application > Non-gallery application. Give it a name and click Add.
- Once the application has been created, click on Single sign-on, then SAML.
- Click Upload metadata file at the top, then choose the file you saved earlier.
- The Service Provider Entity Id you configured earlier should go into the Identifier (Entity ID) field, and the AssertionConsumerService goes into the Reply URL from the XML file.
- Save and close.
- Download the Base64 certificate and open the .cer file in notepad.
- Click on Users and Groups, and add a group containing the users who will be allowed to login via SSO. This can include Guest users.
- Paste the contents of the Azure AD app into the plugin settings:
Login URL > Single Sign On Service Url
Azure AD Identifier > IdP Entity Id
Logout URL > Single Log Out Service Url
- Paste the certificate contents into X.509 Certificate
It should look similar to this:
Finally set the attribute mapping. These can be found in Azure AD, click the edit button on User Attributes & Claims, then copy and paste the full claim names in the first column as below.
Note that for Username in WordPress you might want to use Email rather than UPN if you want to allow Guests to login, because Guest accounts end up with EXT#@<tenantname>.onmicrosoft.com at the end which will cause an error.
Otherwise, if you don’t need guests, use the userprincipalname, because that will work for users and admins who don’t have a mailbox.
So your plugin looks like this:
Also set a few other options:
- Create user if not exists
- Update user data
- Match WordPress account by: E-mail.
- Set the default WordPress role for new users if required in Settings > General > New User Default Role.
Test the application
Now you have everything configured, tick Enable at the top of the plugin and save. Don’t worry, you won’t lock yourself out since you can still login using the wp-login.php? normal URL.
In Azure, click on the test button and you should be logged in, and a WordPress account will be created with matching details. You may want to add this manually to editor or admin roles as required.
Adding a login / logout link
I then use the plugin Login-Logout to add a login link to the header. Just install this plugin, and add the widget to the header. Tick the Inline button to get rid of the bullet, and then I use custom CSS to style:
There is an excellent Edge plugin which will allow you to see the SAML response amogts other things.
Install the My Apps Secure Sign-in Extension https://www.microsoft.com/store/productId/9PC9SCKKZK84 and use Edge to do the test, you get a neat report:
Note that only users in your own Azure AD will be able to login. To allow external users access, you will need to configure Guest access in Azure AD and then invite them individually, or just send a link without an invite as per https://docs.microsoft.com/en-us/azure/active-directory/b2b/add-user-without-invite.
See https://cloudrun.co.uk/office365/securing-guest-access-in-azure-ad/ for more info.
Also note that you can add Google as an IDP and they use their Google accounts as well as Microsoft, see https://docs.microsoft.com/en-us/azure/active-directory/b2b/google-federation.