Azure AD B2C based single sign-on
Use this guide if you want to configure the Azure AD B2C based single sign-on capability of the WordPress + Microsoft Office 365 / Azure AD plugin.
Azure Active Directory B2C provides business-to-customer identity as a service. Your customers use their preferred social, enterprise, or local account identities to get single sign-on access to your applications and APIs. See https://docs.microsoft.com/en-us/azure/active-directory-b2c/overview for details.
Please note If you are in doubt whether you should select Azure AD (default) or - for example - Azure AD B2C then select Azure AD (default). For those interested in Azure AD B2C please consult the corresponding configuration guide. Others are recommended to follow the steps provided in the default guide to configure SSO.
Important Recently Microsoft has introduced their next generation Customer Identity Access Management platform Microsoft Entra External ID for customers, also known as Azure Active Directory (Azure AD) for Customers. Check out this article if you want to read more about this exciting new platform. Even though this platform is still in preview, it can already be created and configured. WPO365 has already added support for this new platform and implemented many of the features it supports e.g. Single Sign-on and User synchronization for Azure AD B2C for Azure AD for Customers. If you are considering to implement Azure AD B2C at this point in time, then you should first review the features currently offered by Azure AD for Customers and make a fundamental decision whether or not to implement this new platform instead.
What you can expect
When you configure the WPO365 | LOGIN plugin to use Azure AD B2C support, the WPO365 | LOGIN plugin will redirect users to the Azure AD B2C endpoint for authorization and to obtain an ID token
Please note The premium WPO365 | LOGIN+ extension (as well as the SYNC and INTRANET bundles) will allow you to map additional (custom) claims in the Azure AD B2C ID token to WordPress user profile fields. This extension will also allow you to use your own custom login domain instead e.g. https://login.contoso.com/ and to embed the Azure AD B2C login form in your WordPress website's login page. Scroll down for further
Before you start
- You have reviewed the installation prerequisites and have installed and activated the WPO365 | LOGIN plugin (see Getting started - Installation).
- You are a Global Administrator for your company’s Office 365 tenant / Azure AD directory (or you have at least obtained approval for your plans from your company's Global Administrator ).
- You are an Administrator for your WordPress website.
- Your website uses SSL and the internet address starts with https://.
When you configure Azure AD B2C based single sign-on (as opposed to regular Azure AD based single sign-on) some capabilities may no longer work as expected e.g. Microsoft 365 Apps, Roles + Access or User synchronization.
Azure AD B2C
The steps to configure Azure AD B2C are basically beyond the scope of the WPO365 documentation. The following steps, however, are presented as a reference implementation. Some remarks are added that outline important steps that you should use to verify your own setup.
- Create an Azure AD B2C tenant (see https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-tenant).
- Register your WordPress website in Azure AD B2C by creating an App registration (see https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-register-applications). Please ensure that you completed the following steps
- Register a web application and as Redirect URI you must enter your website's URI with a trailing "/" if you configured WordPress permalinks e.g. https://www.wpo365.com/.
- Create a client secret and make sure to copy the secret's Value and not the secret's ID and save if temporarily in a text editor (you cannot retrieve it once you navigate away from the page).
- Please note that you do not need to complete the last step to Enable ID token implicit grant.
- Create at least a (recommended) sign-in and sign-up user flow (see https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-user-flows?pivots=b2c-user-flow).
- Ensure that you either disabled the password reset option or otherwise add a password reset policy (see https://docs.microsoft.com/en-us/azure/active-directory-b2c/add-password-reset-policy?pivots=b2c-user-flow).
Proceed with the following steps to configure the WPO365 | LOGIN plugin to allow users to sign in with Azure AD B2C using your (custom) policy and login form, as soon as you have created an Azure AD B2C tenant, registered your WordPress website and created at least one user flow.
- Go to WordPress Admin > WPO365 > Single Sign-on.
- As Identity Provider (IdP) select Azure AD B2C.
- As SSO protocol select OpenID Connect.
- As OpenID Connect flow select Auth.-code (recommended).
- In another browser tab open Azure Portal and select your Azure AD B2C tenant (see https://docs.microsoft.com/en-us/azure/active-directory-b2c/tutorial-create-tenant#select-your-b2c-tenant-directory for details steps), click All services and open your Azure AD B2C service.
- Click App registrations and search for the App registration that you created when you registered your WordPress website with Azure AD B2C.
- Go to the application registration’s Overview page and copy the Directory (tenant) ID and paste it into the corresponding field on the plugin’s wizard Single Sign-on page in the first browser tab.
- Repeat the previous step and copy the Application (client) ID and paste it into the corresponding field on the plugin’s wizard Single Sign-on page.
- Now it's time to retrieve the Application (client) secret that you created before and that you temporarily saved, for example in a text editor. Paste the secret in the corresponding field on the plugin's Single Sign-on configuration page.
- Switch back to the browser and open the Authentication page of your App registration.
- Ensure that the Redirect URI entered here matches exactly with the Redirect URI that you have entered / is automatically proposed on the plugin's Single Sign-on configuration page.
- Now return the App registration's Overview page.
- Copy the (first segment) of the Domain name e.g. wpo365connect when the domain name shown is wpo365connect.onmicrosoft.com and past it into the corresponding field AAD B2C / CIAM domain name on the plugin's wizard Single Sign-on page.
- One level up from App registrations, continue to User flows and copy the name of the user flow (custom) policy for sign-in e.g. B2C_1_signup_signin_1 and past it into the corresponding field B2C policy name on the plugin's Single Sign-on configuration page.
- To test the configuration go to WordPress Admin > WPO365 > Plugin self-test and click Start test.
Mapping custom claims
To map custom claims in the Azure AD B2C ID token - send by Microsoft to the website whenever a user successfully authenticates - you must complete the following steps.
- Go to WP Admin > WPO365 > User sync.
- Scroll down to Custom user fields.
- From the dropdown Source for custom user fields select ID Token claims.
- Now map a property from the ID token e.g. streetAddress by adding it to the list together with a custom title that will be used if the information is shown in a user WordPress user's profile (which can be achieved by checking the corresponding option).
- To see a list of all (custom) claims in your Azure AD B2C ID token, please run the Plugin self-test.
- Go to WP Admin > WPO365 > Plugin self-test.
- Click Start self-test.
- Sign in when asked to do so with a (test) Azure AD B2C account and wait until the test completes.
- After page reloaded, scroll down to the section labelled AZURE AD B2C SSO.
- Click on the View link for the Can decode the ID token test case.
Please note that adding additional custom claims to the ID token is beyond the scope of this documentation.
Support for custom login domain and embedded login
The configuration of Azure AD B2C based SSO will redirect the user to your B2C tenant's unique login page e.g. https://contoso.b2clogin.com. You can improve this login experience as follows.
- Custom login domain Instead of sending users to a different domain, you can create an Azure Front Door instance that will make your B2C tenant available under your own custom domain e.g. https://login.contoso.com. Presumable, users will appreciate this and feel more comfortable. Check out this article for guidance.
- Embedded login Taking things one step further, you can actually embed your B2C tenant's unique login page in your WordPress website using an iFrame. Please consult this article for steps how to achieve this.
Please note The aforementioned features are premium features and require the LOGIN+ extension (but are also included - for example - in the SYNC bundle).
Send WordPress emails using Microsoft Graph
Since WPO365 separates the Azure AD instance used for SSO from the one used to send WordPress emails using Microsoft Graph, you can still configure Azure AD B2C based SSO, whilst sending emails using Microsoft Graph from an account located in your "home" (non B2C) Azure AD tenant.
To configure WordPress to send emails using Microsoft Graph go to WP Admin > WPO365 > Mail and check out this article for guidance.
Missing password reset policy
When you receive an error similar to the following error
[...] Wpo\Services\Router_Service::route_openidconnect_error -> AADB2C90118: The user has forgotten their password. Correlation ID: [...]
Then ensure that you either disabled the password reset option or otherwise add a password reset policy (see https://docs.microsoft.com/en-us/azure/active-directory-b2c/add-password-reset-policy?pivots=b2c-user-flow).
Missing implicit grants
When you receive an error similar to the following error
[...] Wpo\Services\Router_Service::route_openidconnect_error -> AADB2C90057: The provided application is not configured to allow the \'OAuth\' Implicit flow. Correlation ID: [...]
Then update the configured OpenID Connect Flow on the plugin's Single Sign-on page to Auth.-code (recommended).