Configure ACUL Screens

Advanced rendering mode is configured on a per-screen basis. You can configure advanced rendering mode and manage your ACUL screens in your Dashboard at Branding > Universal Login > Customizations or you can use the command line.

Configuration options

Screens that use advanced rendering mode have the following configuration options:

Reference bundled assets for HTML tags that should be included in the <head> tag
Filter your configurations based on defined conditions
Provide context to your template
Customize the Universal Login context object by specifying the optional transaction and configuration data

Each configuration option is described below.

Reference your bundled assets

Advanced rendering mode allows you to add meta information, replace default page titles and favicons, and reference your bundled assets by defining HTML tags that are included in the <head> of the page template. You can define up to 25 tags per screen, all of which are defined as an array of JSON objects.

"head_tags": [
  {
    "tag": "",
    "content": "",
    "attributes": {}
  }
]

Was this helpful?

Tag

Any HTML element valid for use in the <head> tag. Review MDN documentation for more details.

Content (optional)

The content between the opening and closing tags. Content is limited to 250 characters.

When using a custom <title> tag:

My Company Login | {{client.name}}

Was this helpful?

When using a custom font:

'@font-face {  font-family: "custom-font";  src: url("https://cdn.sass.app/{{client.metadata.custom_font}}");}body {  font-family: custom-font;}'

Was this helpful?

The content attribute allows access to the variables below; they are resolved on the server before the page template is returned to the browser.

branding.settings
branding.themes.default
client.id
client.name
client.metadata.[key_name]
organization.id
organization.name
organization.branding
organization.metadata.[key_name]
screen.name
prompt.name
locale
user.id
user.metadata.[key_name]
user.app_metadata.[key_name]

Was this helpful?

Attributes

Up to 10 valid HTML attributes can be included in a given tag.

Dynamic segments for URL type attributes

URL attributes like src and href include dynamic segments that allow you to segment bundles into packages based on attributes like client, organization, or locale.

Dynamic segments have access to the following context data:

screen.name
prompt.name
client.id
client.name
client.metadata.[key_name]
organization.id
organization.name
organization.metadata.[key_name]
transaction.locale

Was this helpful?

Always provide integrity SHAs when referencing Javascript assets for your ACUL setup; review the MDN documentation on SRI for details on setting up subresource integrity support for your assets. Dynamic segments allow you to design an array of SHAs for up to ten possible permutations of the resolved URL.

Filter your ACUL customizations by Client or Organization information

By default, your ACUL customizations display whenever a screen is rendered for your tenant. The filter object allows you to define specific conditions under which your custom UI should be used.

To use the filter object, specify the match_type in conjunction with includes_any or excludes_any:

match_type (Required): This tells the system how to interpret your rules.
- includes_any: Use your custom UI if any of the conditions you define are met.
- excludes_any: Do not use your custom UI if any of the conditions you define are met.

When you use filter, you must specify whether clients or organizations (or both) will see your customizations. For more information about application clients and organizations, read Applications in Auth0 and Auth0 Organizations.

Which clients and organizations will use your ACUL customizations are identified by id or metadata:

id: A specific client or organization ID.
metadata: A key-value pair from the client's or organization's metadata. For example, you can use metadata: { region: "APAC" } to target all clients in the APAC region.

Example

If you only want your advanced customizations to be used for clients with the ID app_123 or for clients that have premium: true in their metadata, insert the code below:

{
  // ... other configurations
  "filter": {
    "match_type": "includes_any",
    "clients": [
      {
        "id": "app_123"
      },
      {
        "metadata": {
          "premium": true
        }
      }
    ]
  }
}

Was this helpful?

Template context

The use_page_template configuration is optional and defaults to false. If you set a custom page template for your tenant, changing the setting to true activates it.

Because the default Auth0 UI is not being used, the {%- auth0:head -%} liquid tag is replaced by your custom defined head tags when set to true and the {%- auth0:widget -%} renders nothing. Everything else in the page template is rendered, including any JS or CSS used to customize the default widget.

Go to Branding > Universal Login > Customizations to use custom template contexts.

Remove the default head tags

The following HTML tags are added by default to the advanced rendering mode page template and can be disabled by setting the value of default_head_tags_disabled to true.

<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="noindex, nofollow">
<link rel="shortcut icon" href="https://cdn.sass.app/favicon.ico">
<title>My App | Login</title>

Was this helpful?

Always include replacements for the <title> tag and robots <meta> tag when removing the default head tags by including them in head_tags.

Optional data can be included the Universal Login Context by adding it to the context_configuration array. Not all optional data is available on every screen; if the requested data is not available, the API returns an error. Refer to the individual screen pages for information about what data is available for each screen.

Referencing entity.metadata or authorization_parameters without a specific key throws an error. For security reasons, full authorization parameters or metadata objects are not exposed.

Below are the available optional context data:

"context-configuration": [
    "branding.settings",
    "branding.themes.default",
    "client.logo_uri",
    "client.description",
    "client.metadata",
    "organization.display_name",
    "organization.branding",
    "organization.metadata",
    "screen.texts",
    "tenant.name",
    "tenant.friendly_name",
    "tenant.enabled_locales",
    "untrusted_data.submitted_form_data",
    "untrusted_data.authorization_params.login_hint",
    "untrusted_data.authorization_params.screen_hint",
    "untrusted_data.authorization_params.ui_locales",
    "untrusted_data.authorization_params.ext-"
  ],

Was this helpful?

Manage untrusted data with the untrustedData screen property

The untrustedData screen property is available to handle potentially unsafe information submitted by an end user, as well as if certain parameters and custom query parameters are passed to the /authorize call.

Below are the unstrustedData properties and parameters:

Interface	Type	Required	Description
untrustedData.submittedFormData	object	No	• Data is available on a case-by-case basis. • Sensitive data like password is not included. • Data from custom form fields like custom prompts is included. • This does not appear on every screen.
untrustedData.authorizationParams[keyName]	object	No	The entire object cannot be exposed; each key must be explicitly added to the context. The following keys are available: •`authorizationParams.login_hint` (string) •`authorizationParams.screen_hint` (string) •`authorizationParams.ui_locales` (string) •`authorization_params.ext-someParam` (string)

interface untrustedData {
  authorizationParams: null | {
    login_hint?: string;
    screen_hint?: string;
    ui_locales?: string;
    [key: `ext-${string}`]: string;
  };
  submittedFormData: null | {
    [key: string]:
        | string
        | number
        | boolean
        | undefined;
  };
}

Was this helpful?

To learn more, read ACUL JS SDK screen references.

Example calls

Below are examples of how to use the Management API and Auth0 Terraform Provider to configure ACUL screens.

Management API example

Below is an example of a direct call to the Management API to configure the Login ID screen.

To disable advanced rendering mode, send a PATCH call to the same endpoint, replacing "rendering_mode": "advanced" with "rendering_mode": "standard". This will revert to the default rendering behavior, removing any previously set context_configuration and head_tags.

Call the Management API

# PATCH to /api/v2/prompts/login-id/screen/login-id/rendering
{
  "rendering_mode": "advanced",
  "context_configuration": [
    "branding.themes.default",
    "client.logo_uri",
    "client.description",
    "client.metadata.google_tracking_id",
    "screen.texts",
    "tenant.enabled_locales",
    "untrusted_data.submitted_form_data",
    "untrusted_data.authorization_params.ext-my_param"
  ],
  "head_tags": [
    {
      "tag": "script",
      "attributes": {
        "src": "https://cdn.sass.app/auth-screens/{{client.name}}.js",
        "defer": true,
        "integrity": [
          "sha256-someHash/Abc+123",
          "sha256-someHash/cDe+456"
        ]
      }
    },
    {
      "tag": "link",
      "attributes": {
        "rel": "stylesheet",
        "href": "https://cdn.sass.app/auth-screens/{{client.name}}.css"
      }
    }
  ]
}

Was this helpful?

Auth0 Terraform provider example

Below is an example of an Auth0 Terraform call to configure the Login ID screen.

Call a Terraform Provider

resource "auth0_prompt_screen_renderer" "apsr" {
  prompt_type     = "login-id"
  screen_name = "login-id"
    rendering_mode = "advanced"
    context_configuration = [
        "branding.settings",
        "branding.themes.default",
        "client.logo_uri",
        "client.description",
        "organization.display_name",
        "organization.branding",
        "screen.texts",
        "tenant.name",
        "tenant.friendly_name",
        "tenant.enabled_locales",
        "untrusted_data.submitted_form_data",
        "untrusted_data.authorization_params.ui_locales",
        "untrusted_data.authorization_params.login_hint",
        "untrusted_data.authorization_params.screen_hint",
        "user.organizations"
    ]
    head_tags = jsonencode([
       {
           attributes: {
               "async": true,
               "defer": true,
               "integrity": [
                   "sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g=="
               ],
               "src": "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js"
           },
           tag: "script"
       }
   ])
}

Was this helpful?

Deploy CLI example

For a Deploy CLI example, check out the Deploy CLI GitHub repo.

Auth0 CLI example

For an Auth0 CLI example, check out the Auth0 CLI GitHub repo.

Customize

Configure ACUL Screens

Configuration options

Reference your bundled assets

Tag

Content (optional)

Attributes

Dynamic segments for URL type attributes

Filter your ACUL customizations by Client or Organization information

Example

Template context

Remove the default head tags

Customize the Universal Login context object

Manage untrusted data with the untrustedData screen property

Example calls

Management API example

Auth0 Terraform provider example

Deploy CLI example

Auth0 CLI example