Edit

Configure authentication options in a single-page application by using Azure AD B2C

  • Article

This article describes how to customize and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your single-page application (SPA).

Before you start, familiarize yourself with the following article: Configure authentication in a sample web application.

Use a custom domain

By using a custom domain, you can fully brand the authentication URL. From a user perspective, users remain on your domain during the authentication process, rather than being redirected to the Azure AD B2C b2clogin.com domain name.

To remove all references to "b2c" in the URL, you can also replace your B2C tenant name, contoso.onmicrosoft.com, in the authentication request URL with your tenant ID GUID. For example, you can change https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ to https://account.contosobank.co.uk/<tenant ID GUID>/.

To use a custom domain and your tenant ID in the authentication URL, follow the guidance in Enable custom domains. Find your Microsoft Authentication Library (MSAL) configuration object and change the authorities and knownAuthorities to use your custom domain name and tenant ID.

The following JavaScript code shows the MSAL configuration object before the change:

const msalConfig = {
    auth: {
      ...
      authority: "https://fabrikamb2c.b2clogin.com/fabrikamb2c.onmicrosoft.com/B2C_1_susi",
      knownAuthorities: ["fabrikamb2c.b2clogin.com"],
      ...
    },
  ...
}

The following JavaScript code shows the MSAL configuration object after the change:

const msalConfig = {
    auth: {
      ...
      authority: "https://custom.domain.com/00000000-0000-0000-0000-000000000000/B2C_1_susi",
      knownAuthorities: ["custom.domain.com"],
      ...
    },
  ...
}

Prepopulate the sign-in name

During a sign-in user journey, your app might target a specific user. When an app targets a user, it can specify in the authorization request the login_hint query parameter with the user's sign-in name. Azure AD B2C automatically populates the sign-in name, and the user needs to provide only the password.

To prepopulate the sign-in name, do the following:

  1. If you're using a custom policy, add the required input claim, as described in Set up direct sign-in.

  2. Create an object to store the login_hint, and pass this object into the MSAL loginPopup() method.

    let loginRequest = {
    loginHint: "bob@contoso.com"
}

myMSALObj.loginPopup(loginRequest);

Preselect an identity provider

If you configured the sign-in journey for your application to include social accounts, such as Facebook, LinkedIn, or Google, you can specify the domain_hint parameter. This query parameter provides a hint to Azure AD B2C about the social identity provider that should be used for sign-in. For example, if the application specifies domain_hint=facebook.com, the sign-in flow goes directly to the Facebook sign-in page.

To redirect users to an external identity provider, do the following:

  1. Check the domain name of your external identity provider. For more information, see Redirect sign-in to a social provider.

  2. Create an object to store extraQueryParameters, and pass this object into the MSAL loginPopup() method.

    let loginRequest = {
     extraQueryParameters: {domain_hint: 'facebook.com'}
}

myMSALObj.loginPopup(loginRequest);

Specify the UI language

Language customization in Azure AD B2C allows your user flow to accommodate a variety of languages to suit your customers' needs. For more information, see Language customization.

To set the preferred language, do the following:

  1. Configure language customization.

  2. Create an object to store extraQueryParameters, and pass this object into the MSAL loginPopup() method.

    let loginRequest = {
     extraQueryParameters: {ui_locales: 'en-us'}
}

myMSALObj.loginPopup(loginRequest);

Pass a custom query string parameter

With custom policies, you can pass a custom query string parameter. A good use-case example is when you want to dynamically change the page content.

To pass a custom query string parameter, do the following:

  1. Configure the ContentDefinitionParameters element.

  2. Create an object to store extraQueryParameters, and pass this object into the MSAL loginPopup() method.

    let loginRequest = {
     extraQueryParameters: {campaignId: 'germany-promotion'}
}

myMSALObj.loginPopup(loginRequest);

Pass an ID token hint

A relying party application can send an inbound JSON Web Token (JWT) as part of the OAuth2 authorization request. The inbound token is a hint about the user or the authorization request. Azure AD B2C validates the token and then extracts the claim.

To include an ID token hint in the authentication request, do the following:

  1. In your custom policy, define an ID token hint technical profile.

  2. Create an object to store extraQueryParameters, and pass this object into the MSAL loginPopup() method.

    let loginRequest = {
     extraQueryParameters: {id_token_hint: 'id-token-hint-value'}
}

myMSALObj.loginPopup(loginRequest);

Secure your logout redirect

After logout, the user is redirected to the URI specified in the post_logout_redirect_uri parameter, regardless of the reply URLs that have been specified for the application. However, if a valid id_token_hint is passed and the Require ID Token in logout requests is turned on, Azure AD B2C verifies that the value of post_logout_redirect_uri matches one of the application's configured redirect URIs before performing the redirect. If no matching reply URL was configured for the application, an error message is displayed and the user is not redirected.

To support a secured logout redirect URI, follow the steps below:

  1. Create a globally accessible variable to store the id_token.

    let id_token = "";

  2. In the MSAL handleResponse function, parse the id_token from the authenticationResult object into the id_token variable.

    function handleResponse(response) {
    if (response !== null) {
        setAccount(response.account);
        id_token = response.idToken;
    } else {
        selectAccount();
    }
}

  3. In the signOut function, add the id_token_hint parameter to the logoutRequest object.

    function signOut() {
    const logoutRequest = {
        postLogoutRedirectUri: msalConfig.auth.redirectUri,
        //set id_token_hint to the id_token value
        idTokenHint : id_token,
        mainWindowRedirectUri: msalConfig.auth.redirectUri
    };
    myMSALObj.logoutPopup(logoutRequest);
}

In the above example, the post_logout_redirect_uri passed into the logout request will be in the format: https://your-app.com/. This URL must be added to the Application Registration's reply URL's.

Enable single logout

Single logout in Azure AD B2C uses OpenId Connect front-channel logout to make logout requests to all applications the user has signed into through Azure AD B2C.

These logout requests are made from the Azure AD B2C logout page, in a hidden Iframe. The Iframes make HTTP requests to all the front-channel logout endpoints registered for the apps that Azure AD B2C has recorded as being logged in.

Your logout endpoint for each application must call the MSAL logout() method. You must also explicitly configure MSAL to run within an Iframe in this scenario by setting allowRedirectInIframe to true.

The following code sample sets allowRedirectInIframe to true:

const msalConfig = {
    auth: {
        clientId: "enter_client_id_here",
        .....
    },
    cache: {
        cacheLocation: "..",
        ....
    },
    system: {
        allowRedirectInIframe: true
    };
}

async function logoutSilent(MSAL) {
   return MSAL.logout({
      onRedirectNavigate: (url) => {
         return false;
       }

Next steps

Learn more about MSAL.js configuration options.