Our WordPress + Office 365 login plugin allows your users to seamlessly sign into your WordPress website using their Microsoft Office 365 Azure AD account: No username or password required. This documentation offers a detailed introduction of the plugin’s features and supported authentication flow. It should help you decide whether or not our plugin can help you improve the user experience when they try to gain accessing to your WordPress site. And if you can’t decide or am not sure whether your scenario is supported by our plugin, we’d love to hear from you and learn how we should improve and make it more versatile. Click this link to see how you can get in touch with us.
3-seconds intro for techies
For some (or all) page requests, 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 may be redirected to the Microsoft authorization endpoint to sign in and then return to your website with the appropriate identity and authorization information. 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 you 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 our pluging.
30-seconds intro for Intranet and Internet site owner
Basically the plugin supports two scenarios, which can be configured using the plugin’s options page.
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 WordPress + Office 365 login plugin will do for you.
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. However, with the plugin you can offer of a login experience that closely resembles Single Sign-On because users are authenticated by Azure AD and can use their existing Office 365 account.
Please be aware that if your WordPress website is optimized with caching services offered by either plugins such as WP Rocket or by the hosting provider, the Intranet scenario may not work as expected and cached dynamic front-end pages may be served as static HTML and thus causing the authentication validation to fail.
3-minutes explanation of the 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 some information about the user has been added to the request.
Now the plugin will check, whether the request contains the user’s encrypted login information upon a successful login or an error when 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 email address. It will try and find an existing user in WordPress by that email address. If no user is found, the plugin will create one for you (even though this feature 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.
And finally the plugin will automatically log in the corresponding WordPress user for the Azure AD user.
3-minutes explanation 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.
30-seconds list of noteworthy features
- 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.
- 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. Therefore and to not to confuse or break the system, the plugin “protects” a user’s password and email address preventing user’s to change their password by preventing them to change it (see WPO365 Options explained).
If you have further questions after reading through this section or the plugin is not working according to your expectations, you can acquire additional support.