Configure ACUL Screens

Advanced rendering mode is configured on a per-screen basis through Management API calls and is also supported in Deploy CLI and Auth0 Terraform Provider.

Configuration options

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

  • Advanced or standard screen rendering mode

  • Include or exclude the default head tags in the page template

  • Optional transaction and configuration data that should be included in the Universal Login Context

  • HTML tags to be included in the <head> tag that reference your hosted asset bundles

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.

Include optional data in Universal Login Context

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?

/

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

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]

Attributes

Up to 10 valid HTML attributes can be included in the current tag.

Dynamic segments for URL type attributes

URL attributes like src and href include dynamic segments that allow you to segment bundles into logical 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

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.

/

# PATCH to /api2/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.

/

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?

/