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.

If you are in doubt whether you should configure Azure AD B2C based single sign-on or just single sign-on then please refer to the plugin's  default single sign-on configuration guide

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 

https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy-name>/oauth2/v2.0/authorize

The premium WPO365 | LOGIN+ extension (as well as the SYNC and INTRANET bundles) will allow you additionally to map custom claims in the Azure AD B2C ID token to WordPress user profile fields.

Before you start

• You have reviewed the installation prerequisites and have installed and activated the WPO365 | LOGIN plugin (see Getting started - Installation).
• In order to support Azure AD B2C you must have at least purchased the WPO365 | LOGIN+ extension or any of the bundles ( WPO366 | SYNC or WPO365 | INTRANET).
• 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://.

Important information

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 sync.

Whether or not these capabilities can be used or not must be established from case to case and may depend on your configuration / customization of Azure AD B2C.

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 Azure B2C configuration.

• 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).

Plugin configuration

Once you have created an Azure AD B2C tenant, registered your WordPress website in that Azure AD B2C tenant and created at least one user flow you configure the WPO365 | LOGIN plugin to allow users to sign in with Azure AD B2C using your (custom) policy and login form.

• 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 search for Azure AD B2C. 
• 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.
• Switch back to the browser tab with Azure Portal still open and navigate back up to Azure AD B2C and click Authentication.
• Ensure that the Redirect URI entered here matches exactly with the Redirect URI that you have entered / is automatically proposed on the plugin's wizard Single Sign-on page.
• In the browser tab with Azure Portal open, navigate back up to Azure AD B2C and click Overview.
• 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 on the plugin's wizard Single Sign-on page.
• Click User flows and copy the name of the user flow (custom) policy e.g. B2C_1_signup_signin_1 and past it into the corresponding field on the plugin's wizard Single Sign-on 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.

Send WordPress emails using Microsoft Graph

Please note that - starting with version 18 - the WPO365 | LOGIN plugin allows administrators to configure a tenant different than the Azure AD B2C tenant (and subsequently a registered application different than the Azure AD B2C application registration) to send WordPress emails using Microsoft Graph.

To configure WordPress to send emails using Microsoft Graph go to WP Admin > WPO365 > Mail.

Troubleshooting

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).