Customize the user interface of your application using a custom policy in Azure Active Directory B2C

Note

In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. For most scenarios, we recommend that you use built-in user flows.

By completing the steps in this article, you create a sign-up and sign-in custom policy with your brand and appearance. With Azure Active Directory B2C (Azure AD B2C), you get nearly full control of the HTML and CSS content that's presented to users. When you use a custom policy, you configure UI customization in XML instead of using controls in the Azure portal.

Prerequisites

Complete the steps in Get started with custom policies. You should have a working custom policy for sign-up and sign-in with local accounts.

Use custom page content

By using the page UI customization feature, you can customize the look and feel of any custom policy. You can also maintain brand and visual consistency between your application and Azure AD B2C.

How it works

Azure AD B2C runs code in your customer's browser by using Cross-Origin Resource Sharing (CORS). At runtime, content is loaded from a URL you specify in your user flow or custom policy. Each page in the user experience loads its content from the URL you specify for that page. After content is loaded from your URL, it's merged with an HTML fragment inserted by Azure AD B2C, and then the page is displayed to your customer.

Custom page content margin

Custom HTML page content

Create an HTML page with your own branding to serve your custom page content. This page can be a static *.html page, or a dynamic page like .NET, Node.js, or PHP.

Your custom page content can contain any HTML elements, including CSS and JavaScript, but cannot include insecure elements like iframes. The only required element is a div element with id set to api, such as this one <div id="api"></div> within your HTML page.

<!DOCTYPE html>
<html>
<head>
    <title>My Product Brand Name</title>
</head>
<body>
    <div id="api"></div>
</body>
</html>

Customize the default Azure AD B2C pages

Instead of creating your custom page content from scratch, you can customize Azure AD B2C's default page content.

The following table lists the default page content provided by Azure AD B2C. Download the files and use them as a starting point for creating your own custom pages.

Default page Description Content definition ID
(custom policy only)
exception.html Error page. This page is displayed when an exception or an error is encountered. api.error
selfasserted.html Self-Asserted page. Use this file as a custom page content for a social account sign-up page, a local account sign-up page, a local account sign-in page, password reset, and more. The form can contain various input controls, such as: a text input box, a password entry box, a radio button, single-select drop-down boxes, and multi-select check boxes. api.localaccountsignin, api.localaccountsignup, api.localaccountpasswordreset, api.selfasserted
multifactor-1.0.0.html Multi-factor authentication page. On this page, users can verify their phone numbers (by using text or voice) during sign-up or sign-in. api.phonefactor
updateprofile.html Profile update page. This page contains a form that users can access to update their profile. This page is similar to the social account sign-up page, except for the password entry fields. api.selfasserted.profileupdate
unified.html Unified sign-up or sign-in page. This page handles the user sign-up and sign-in process. Users can use enterprise identity providers, social identity providers such as Facebook or Google+, or local accounts. api.signuporsignin

Hosting the page content

When using your own HTML and CSS files to customize the UI, host your UI content on any publicly available HTTPS endpoint that supports CORS. For example, Azure Blob storage, Azure App Services, web servers, CDNs, AWS S3, or file sharing systems.

Guidelines for using custom page content

  • Use an absolute URL when you include external resources like media, CSS, and JavaScript files in your HTML file.
  • Using page layout version 1.2.0 and above, you can add the data-preload="true" attribute in your HTML tags to control the load order for CSS and JavaScript. With data-preload=true, the page is constructed before being shown to the user. This attribute helps prevent the page from "flickering" by preloading the CSS file, without the un-styled HTML being shown to the user. The following HTML code snippet shows the use of the data-preload tag.
    <link href="https://path-to-your-file/sample.css" rel="stylesheet" type="text/css" data-preload="true"/>
    
  • We recommend that you start with the default page content and build on top of it.
  • You can include JavaScript in your custom content for both user flows and custom policies.
  • Supported browser versions are:
    • Internet Explorer 11, 10, and Microsoft Edge
    • Limited support for Internet Explorer 9 and 8
    • Google Chrome 42.0 and above
    • Mozilla Firefox 38.0 and above
    • Safari for iOS and macOS, version 12 and above
  • Due to security restrictions, Azure AD B2C doesn't support frame, iframe, or form HTML elements.

Custom page content walkthrough

Here's an overview of the process:

  1. Prepare a location to host your custom page content (a publicly accessible, CORS-enabled HTTPS endpoint).
  2. Download and customize a default page content file, for example unified.html.
  3. Publish your custom page content your publicly available HTTPS endpoint.
  4. Set cross-origin resource sharing (CORS) for your web app.
  5. Point your policy to your custom policy content URI.

1. Create your HTML content

Create a custom page content with your product's brand name in the title.

  1. Copy the following HTML snippet. It is well-formed HTML5 with an empty element called <div id="api"></div> located within the <body> tags. This element indicates where Azure AD B2C content is to be inserted.

    <!DOCTYPE html>
    <html>
    <head>
        <title>My Product Brand Name</title>
    </head>
    <body>
        <div id="api"></div>
    </body>
    </html>
    
  2. Paste the copied snippet in a text editor, and then save the file as customize-ui.html.

Note

HTML form elements will be removed due to security restrictions if you use login.microsoftonline.com. If you want to use HTML form elements in your custom HTML content, use b2clogin.com.

2. Create an Azure Blob storage account

In this article, we use Azure Blob storage to host our content. You can choose to host your content on a web server, but you must enable CORS on your web server.

To host your HTML content in Blob storage, perform the following steps:

  1. Sign in to the Azure portal.
  2. On the Hub menu, select New > Storage > Storage account.
  3. Select a Subscription for your storage account.
  4. Create a Resource group or select an existing one.
  5. Enter a unique Name for your storage account.
  6. Select the Geographic location for your storage account.
  7. Deployment model can remain Resource Manager.
  8. Performance can remain Standard.
  9. Change Account Kind to Blob storage.
  10. Replication can remain RA-GRS.
  11. Access tier can remain Hot.
  12. Select Review + create to create the storage account. After the deployment is completed, the Storage account page opens automatically.

2.1 Create a container

To create a public container in Blob storage, perform the following steps:

  1. Under Blob service in the left-hand menu, select Blobs.
  2. Select +Container.
  3. For Name, enter root. The name can be a name of your choosing, for example contoso, but we use root in this example for simplicity.
  4. For Public access level, select Blob, then OK.
  5. Select root to open the new container.

2.2 Upload your custom page content files

  1. Select Upload.
  2. Select the folder icon next to Select a file.
  3. Navigate to and select customize-ui.html, which you created earlier in the Page UI customization section.
  4. If you want to upload to a subfolder, expand Advanced and enter a folder name in Upload to folder.
  5. Select Upload.
  6. Select the customize-ui.html blob that you uploaded.
  7. To the right of the URL text box, select the Copy to clipboard icon to copy the URL to your clipboard.
  8. In web browser, navigate to the URL you copied to verify the blob you uploaded is accessible. If it is inaccessible, for example if you encounter a ResourceNotFound error, make sure the container access type is set to blob.

3. Configure CORS

Configure Blob storage for Cross-Origin Resource Sharing by performing the following steps:

  1. In the menu, select CORS.
  2. For Allowed origins, enter https://your-tenant-name.b2clogin.com. Replace your-tenant-name with the name of your Azure AD B2C tenant. For example, https://fabrikam.b2clogin.com. Use all lowercase letters when entering your tenant name.
  3. For Allowed Methods, select both GET and OPTIONS.
  4. For Allowed Headers, enter an asterisk (*).
  5. For Exposed Headers, enter an asterisk (*).
  6. For Max age, enter 200.
  7. Select Save.

3.1 Test CORS

Validate that you're ready by performing the following steps:

  1. Repeat the configure CORS step. For Allowed origins, enter https://www.test-cors.org
  2. Navigate to www.test-cors.org
  3. For the Remote URL box, paste the URL of your HTML file. For example, https://your-account.blob.core.windows.net/azure-ad-b2c/unified.html
  4. Select Send Request. The result should be XHR status: 200. If you receive an error, make sure that your CORS settings are correct. You might also need to clear your browser cache or open an in-private browsing session by pressing Ctrl+Shift+P.

4. Modify the extensions file

To configure UI customization, copy the ContentDefinition and its child elements from the base file to the extensions file.

  1. Open the base file of your policy. For example, SocialAndLocalAccounts/TrustFrameworkBase.xml. This base file is one of the policy files included in the custom policy starter pack, which you should have obtained in the prerequisite, Get started with custom policies.

  2. Search for and copy the entire contents of the ContentDefinitions element.

  3. Open the extension file. For example, TrustFrameworkExtensions.xml. Search for the BuildingBlocks element. If the element doesn't exist, add it.

  4. Paste the entire contents of the ContentDefinitions element that you copied as a child of the BuildingBlocks element.

  5. Search for the ContentDefinition element that contains Id="api.signuporsignin" in the XML that you copied.

  6. Change the value of LoadUri to the URL of the HTML file that you uploaded to storage. For example, https://your-storage-account.blob.core.windows.net/your-container/customize-ui.html.

    Your custom policy should look like the following code snippet:

    <BuildingBlocks>
      <ContentDefinitions>
        <ContentDefinition Id="api.signuporsignin">
          <LoadUri>https://your-storage-account.blob.core.windows.net/your-container/customize-ui.html</LoadUri>
          <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
          <DataUri>urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0</DataUri>
          <Metadata>
            <Item Key="DisplayName">Signin and Signup</Item>
          </Metadata>
        </ContentDefinition>
      </ContentDefinitions>
    </BuildingBlocks>
    
  7. Save the extensions file.

5. Upload and test your updated custom policy

5.1 Upload the custom policy

  1. Make sure you're using the directory that contains your Azure AD B2C tenant by selecting the Directory + subscription filter in the top menu and choosing the directory that contains your tenant.
  2. Search for and select Azure AD B2C.
  3. Under Policies, select Identity Experience Framework.
  4. Select Upload custom policy.
  5. Upload the extensions file that you previously changed.

5.2 Test the custom policy by using Run now

  1. Select the policy that you uploaded, and then select Run now.
  2. You should be able to sign up by using an email address.

Sample templates

You can find sample templates for UI customization here:

git clone https://github.com/Azure-Samples/Azure-AD-B2C-page-templates

This project contains the following templates:

To use the sample:

  1. Clone the repo on your local machine. Choose a template folder /ocean_blue or /slate_gray.

  2. Upload all the files under the template folder and the /assets folder, to Blob storage as described in the previous sections.

  3. Next, open each \*.html file in the root of either /ocean_blue or /slate_gray, replace all instances of relative URLs with the URLs of the css, images, and fonts files you uploaded in step 2. For example:

    <link href="./css/assets.css" rel="stylesheet" type="text/css" />
    

    To

    <link href="https://your-storage-account.blob.core.windows.net/your-container/css/assets.css" rel="stylesheet" type="text/css" />
    
  4. Save the \*.html files and upload them to Blob storage.

  5. Now modify the policy, pointing to your HTML file, as mentioned previously.

  6. If you see missing fonts, images, or CSS, check your references in the extensions policy and the *.html files.

Configure dynamic custom page content URI

By using Azure AD B2C custom policies, you can send a parameter in the URL path, or a query string. By passing the parameter to your HTML endpoint, you can dynamically change the page content. For example, you can change the background image on the Azure AD B2C sign-up or sign-in page, based on a parameter that you pass from your web or mobile application. The parameter can be any claim resolver, such as the application ID, language ID, or custom query string parameter, such as campaignId.

Sending query string parameters

To send query string parameters, in the relying party policy, add a ContentDefinitionParameters element as shown below.

<RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <UserJourneyBehaviors>
    <ContentDefinitionParameters>
        <Parameter Name="campaignId">{OAUTH-KV:campaignId}</Parameter>
        <Parameter Name="lang">{Culture:LanguageName}</Parameter>
        <Parameter Name="appId">{OIDC:ClientId}</Parameter>
    </ContentDefinitionParameters>
    </UserJourneyBehaviors>
    ...
</RelyingParty>

In your content definition, change the value of LoadUri to https://<app_name>.azurewebsites.net/home/unified. Your custom policy ContentDefinition should look like the following code snippet:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://<app_name>.azurewebsites.net/home/unified</LoadUri>
  ...
</ContentDefinition>

When Azure AD B2C loads the page, it makes a call to your web server endpoint:

https://<app_name>.azurewebsites.net/home/unified?campaignId=123&lang=fr&appId=f893d6d3-3b6d-480d-a330-1707bf80ebea

Dynamic page content URI

Content can be pulled from different places based on the parameters used. In your CORS-enabled endpoint, set up a folder structure to host content. For example, you can organize the content in following structure. Root folder/folder per language/your html files. For example, your custom page URI might look like:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://contoso.blob.core.windows.net/{Culture:LanguageName}/myHTML/unified.html</LoadUri>
  ...
</ContentDefinition>

Azure AD B2C sends the two letter ISO code for the language, fr for French:

https://contoso.blob.core.windows.net/fr/myHTML/unified.html

Next steps

For more information about UI elements that can be customized, see reference guide for UI customization for user flows.