JavaScript and page layout versions in Azure Active Directory B2C

Note

This feature is in public preview.

Azure AD B2C provides a set of packaged content containing HTML, CSS, and JavaScript for the user interface elements in your user flows and custom policies.

To enable JavaScript for your applications:

If you intend to enable JavaScript client-side code, the elements you base your JavaScript on must be immutable. If they're not immutable, any changes could cause unexpected behavior on your user pages. To prevent these issues, enforce the use of a page layout and specify a page layout version to ensure the content definitions you’ve based your JavaScript on are immutable. Even if you don’t intend to enable JavaScript, you can specify a page layout version for your pages.

Enable JavaScript

In the user flow Properties, you can enable JavaScript. Enabling JavaScript also enforces the use of a page layout. You can then set the page layout version for the user flow as described in the next section.

User flow properties page with Enable JavaScript setting highlighted

Select a page layout version

Whether or not you enable JavaScript in your user flow's properties, you can specify a page layout version for your user flow pages. Open the user flow and select Page layouts. Under LAYOUT NAME, select a user flow page and choose the Page Layout Version.

For information about the different page layout versions, see the Page layout version change log.

Page layout settings in portal showing page layout version dropdown

Guidelines for using JavaScript

Follow these guidelines when you customize the interface of your application using JavaScript:

  • Don't bind a click event on <a> HTML elements.
  • Don’t take a dependency on Azure AD B2C code or comments.
  • Don't change the order or hierarchy of Azure AD B2C HTML elements. Use an Azure AD B2C policy to control the order of the UI elements.
  • You can call any RESTful service with these considerations:
    • You may need to set your RESTful service CORS to allow client-side HTTP calls.
    • Make sure your RESTful service is secure and uses only the HTTPS protocol.
    • Don't use JavaScript directly to call Azure AD B2C endpoints.
  • You can embed your JavaScript or you can link to external JavaScript files. When using an external JavaScript file, make sure to use the absolute URL and not a relative URL.
  • JavaScript frameworks:
    • Azure AD B2C uses a specific version of jQuery. Don’t include another version of jQuery. Using more than one version on the same page causes issues.
    • Using RequireJS isn't supported.
    • Most JavaScript frameworks are not supported by Azure AD B2C.
  • Azure AD B2C settings can be read by calling window.SETTINGS, window.CONTENT objects, such as the current UI language. Don’t change the value of these objects.
  • To customize the Azure AD B2C error message, use localization in a policy.
  • If anything can be achieved by using a policy, generally it's the recommended way.

Next steps

You can find examples of JavaScript usage in JavaScript samples for use in Azure Active Directory B2C.