The WordPress + Microsoft Office 365 / Azure AD Plugin allows your users to seamlessly sign into your WordPress website using their Microsoft Office 365 Azure AD account: No username or password required!
Intro for intranet and internet site owner
Basically the plugin supports two scenarios, which can be configured using the plugin’s options page.
Intranet
When you have build your corporate Intranet (or Extranet for a customer-only portal) with WordPress, you probably want to block all anonymous traffic to your site. This implies that admin pages as well as client facing pages must be protected. And this is exactly what the WPO365 plugin will do for you.
Internet
On the other hand, you may want solely to prevent unauthenticated access to the WordPress admin pages for authors, editors etc. Most likely, you would want this in case of a corporate internet website. Of course, WordPress already accommodates this out-of-the-box.
Whatever scenario you configure, however, with the plugin you can offer your users a single sign-on login experience because users are authenticated by Azure AD and thus can use their existing Office 365 account.
Intro for techies
For some (or all) page requests (see related post Make your WordPress (intranet) private), the plugin will try and establish the identity of the user. It will do so by requesting the user to sign in with Microsoft using the Azure AD supported Open Connect ID capability. For this reason a user will be redirected to Microsoft identity provider to sign in. Having successfully authenticated him or herself, the user automatically returns to your website with the appropriate identity and authorization information (that optionally include information about the user’s Azure AD Security Group memberships). The plugin will then proceed and find or create a corresponding WordPress user for this identity. The plugin leaves WordPress own signin capability intact so both WordPress-only users can sign in when they navigate to the default WordPress login page e.g. /wp-login.php whilst Microsoft Office 365 Azure AD users are authenticated by the plugin when they request a page or post (depending on the selected authentication scenario).
Please note that the WordPress + Office 365 BASIC plugin does not automatically create new users. See the plugins gallery for premium editions.
Detailed authentication flow
Once the plugin is activated, it will try and check for each page request whether the user is authenticated by Azure AD, unless:
- The selected scenario tells it to skip that page. This is for example the case when you activated the Internet scenario and you want the plugin not to try and authenticate user requesting a client facing page.
- The requested page is blacklisted (see WPO365 Options explained).
When the page is not skipped the plugin will execute as follows:
- It will quickly check whether it has already previously confirmed the user’s identity using Azure ID. If so, the user will be logged on the WordPress and hence the plugin will try and find a specific user property.
- If the user’s identity is not yet confirmed, the plugin will redirect the user to Microsoft’s Open Connect ID endpoint. Here the user can log on using his corporate (or school or personal) account. After logon (or when already logged on) the user will be redirected back to your WordPress site. This time the request has been modified by Azure ID and a handful of information about the user has been added to the request such as name, email address and optionally the user’s Azure AD Security Group memberships.
- Now the plugin will check, whether the request contains the user’s encrypted login information or an error, in case something went something went wrong e.g. “access denied” (See Troubleshooting the WPO365-login plugin). If an error was detected the flow is stopped immediately and the user is redirected to the default WordPress login page, along with an error message.
- When the plugin detects encrypted login information it will try and decode this. This is a rather “tricky” business and if an error occurs during this process, the flow is stopped immediately and the user is redirected to the default WordPress login page. In this cases the user will see a message “Your login may be tampered with”.
- Once the user’s login information is decoded successfully, the plugin will take the user’s Office 365 user name and it will try and find an existing user in WordPress with either that login name or that email address. If no user is found, the plugin will create one for you (this capability is not available in the basic version of the plugin and in other versions it can be disabled) and assign him or her the role you configured in the plugin’s settings (“Subscriber” by default, see WPO365 Options explained).
- Now that a corresponding WordPress user has been found (or was newly created) the plugin will add a custom user property that includes a timestamp and that is used by the plugin to skip session validation for future requests when found and not expired.
- The premium version offers enhanced capabilities such as setting (multiple) WordPress roles for a user based on the user’s Azure AD Security Group memberships, retrieving additional user information from Microsoft Graph e.g. Job Title, Office Location, Business Phones, etc. as well as updating the user’s WordPress avatar with the user’s Office 365 profile image.
- Finally the plugin will automatically log in the corresponding WordPress user for the Azure AD user.
- It will also try and restore the user’s state. When users are redirected to Microsoft’s Azure AD login endpoint, the plugin stores the page the user requested before being redirected. Once the user is returns to your site (redirected by Azure AD after having successfully logged in) the plugin will try and retrieve this information and sends the user to page initially requested.
- And last but not least the plugin (by default) prevent a user to update his or her email address and password.
Part of the magic the plugin does for you relies on creating a WordPress user for each Azure AD user automatically. Think of it in the following way. The plugin will try and establish the user’s identity with the help of Azure AD and will then find / create a corresponding user in WordPress (by email address). In most cases, the user doesn’t know the actual password for the WordPress user because the plugin does the login automatically in the background.
WordPress vs. Azure AD Authentication
From the description of the authentication flow it becomes obvious that the plugin itself does not authenticate users. Not by any means! It merely redirects a user to Microsoft’s central login endpoint. It’s where users possibly are required to enter their corporate credentials once. However, user that are already logged on to Azure AD won’t ever see a login mask at all. And the other way around the same is true: Once users logged on to your WordPress with the help of the plugin and thus with Azure AD they won’t be hassled with further login screens, for example, when they would like to open a SharePoint Online workspace.
Sounds like a lot of redirects, doesn’t it? Yes, it does! But in reality, when everything is running smooth, you’ll hardly notice this flow when you’re already logged on to Azure AD. Therefore we referred to this as “closely resembles Single Sign-On”, even when we realize that it isn’t.
At the same time, the normal WordPress login will continue to work as expected. This means that you can have a combination of users that access your WordPress site using their corporate (Azure AD) login whilst others may still use the default WordPress login and navigate to the site’s default login page e.g. yoursite.net/wp-login. But when the plugin is activated, users can navigate to any page e.g. to the site’s landing page and will be automatically get authenticated.