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.

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

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://.

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

Plugin configuration

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.

Please note You will find that when you test your user flow in Azure AD B2C with the Run user flow tool provided by Microsoft (see screenshot below), you may find that it not works as expected. When you click Run user flow, Microsoft will generate a default link that will take users to the login mask and this specific link is missing two parameters that are needed for WPO365 to work as expected. You must add these parameters manually as follows: state WPO365 uses the state parameter to "remember" where users started their login-journey (e.g. on a login page). The state parameter must therefore contain the URL where users should be returned to after the authenticated successfully and this URL should ideally be URL encoded twice e.g. &state=https%253A%252F%252Fwebsite.tld%252Fpath%252F response_mode Since Azure AD B2C by default returns the authentication response (e.g. an ID token) as a query string parameter following a #-sign, WPO365 would never receive it. Therefore you must instruct Azure AD B2C to post the authentication response e.g. &response_mode=form_post If the Run user flow still is not working for you at this point, then please check whether the Azure AD B2C user flow is sending a code or an ID token as its default authentication response. This is mostly defined by a setting on the Authentication page under the heading Implicit grant and hybrid flows of the App Registration that you have connected to the user flow that you are testing. You can inspect the authentication response, by redirecting the result of Run user flow to https://jwt.ms. To do so, you must add this redirect URI on to the list of Redirect URIs on the same Authentication page of your App Registration and when testing using the Run user flow tool, selecting that specific Redirect URL. Keep in mind that if your user flow is sending an ID token (instead of an Authorization Code) that you must change the setting "Select OpenID Connect flow" on the plugin's Single Sign-on page as well.

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.

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.

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