Skip to main content
You can customize pages by providing a page template created with the Liquid template language. With page templates, you can define the content displayed around Universal Login prompts, such as the login box or an challenge. As the same page template is used for all login flow pages, this method of customization allows you to easily implement a consistent, branded experience for users. To use customized page templates, you must configure a Custom Domain for your tenant. Further, you can only update Universal Login page templates with the Management API.
The term prompt refers to a specific step of the login flow, such as the sign-up page or an MFA challenge. The variables and code samples on this page may use the term prompt or the term widget. While these terms are synonymous in the context of Universal Login, they are not interchangeable within your code.  To ensure successful customization, verify you are using the appropriate term listed for any elements you add to your code.

​
Page template requirements

When creating a Universal Login page template, you must include the following tags: To center the prompt on the page, add class="_widget-auto-layout" to the <body> element. You can omit this attribute to manually position the prompt as needed.
Page template limitations:
  • CSS class names change each time Auth0 builds the project. Custom CSS that targets these classes will break with each new build.
  • The HTML structure of Universal Login pages is subject to change. Avoid customizations that rely on the HTML structure to prevent any interruptions.
To learn more, review CSS customization.
Example template:
The following example demonstrates the simplest Universal Login page template you can create with the required tags:
If you use Storybook to view your template, be aware that the <script> tag breaks the rendering as it cannot parse these tags correctly.  As a workaround, use backticks (`) and plus sign (+) characters to properly inject the <script> tag into your template code.Example:<scr`+`ipt>console.log("test");</scr`+`ipt>

​
Page template variables

Page templates support a variety of context variables that impact how a page is rendered. For example, you can use these variables to:
  • Render different content depending on the application associated with the login flow. For example, you may manage two brands that require different page designs.
  • Render different content depending on the specific prompt. For example, you may want to add information about what your application offers on the Login page but prefer the MFA flow to only display the MFA challenge prompt.
  • Add a footer with user support information, such as links to your support page or contact information.

​
Available variables

Page templates support the following variables:

​
Application

​
Branding

​
Tenant

​
Organizations

The following variables refer to the Auth0 Organizations feature.

​
Tenant

​
Tracking

Correlation ID is currently in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. To learn more about Auth0’s product release cycle, read Product Release Stages. To participate in this program, contact Auth0 Support or your Technical Account Manager.
We strongly recommend you never use Personally Identifiable Information (PII) or other sensitive information as the unique correlation_id.

​
Custom Domain

The following variables refer to the custom domain used for the current session. Use these variables to render different content based on which custom domain the user is accessing, or to retrieve domain metadata configured for that domain.

​
Current user information

You can only use the following variables for pages that render after authentication.

​
Current screen information

​
Prompts

The term prompt refers to a specific step of the login flow. A specific prompt may consist of one or more screens. You can manage prompts through the Auth0 Dashboard or the prompts endpoints of the Management API. The sections below provide details for each available prompt.

​
Screen: brute-force-protection-unblock

brute-force-protection-unblock reference screenshot

​
Screen: brute-force-protection-unblock-success

brute-force-protection-unblock-success reference screenshot

​
Screen: brute-force-protection-unblock-failure

brute-force-protection-unblock-failure reference screenshot

​
Screen: redeem-ticket

redeem-ticket reference screenshot

​
Screen: device-code-activation

device-code-activation reference screenshot

​
Screen: device-code-activation-allowed

device-code-activation-allowed reference screenshot

​
Screen: device-code-activation-denied

device-code-activation-denied reference screenshot

​
Screen: device-code-confirmation

device-code-confirmation reference screenshot

​
Screen: email-otp-challenge

email-otp-challenge reference screenshot

​
Screen: email-verification-result

email-verification-result reference screenshot

​
Screen: accept-invitation

accept-invitation reference screenshot

​
Screen: login

login reference screenshot

​
Screen: login-id

login-id reference screenshot

​
Screen: login-password

login-password reference screenshot

​
Screen: login-passwordless-email-code

login-passwordless-email-code reference screenshot
login-passwordless-email-link reference screenshot

​
Screen: login-passwordless-sms-otp

login-passwordless-sms-otp reference screenshot

​
Screen: login-email-verification

login-email-verification reference screenshot

​
Screen: logout

logout reference screenshot

​
Screen: mfa-detect-browser-capabilities

mfa-detect-browser-capabilities reference screenshot

​
Screen: mfa-enroll-result

mfa-enroll-result reference screenshot

​
Screen: mfa-login-options

mfa-login-options reference screenshot

​
Screen: mfa-begin-enroll-options

mfa-begin-enroll-options reference screenshot

​
Screen: mfa-email-challenge

mfa-email-challenge reference screenshot

​
Screen: mfa-email-list

mfa-email-list reference screenshot

​
Screen: mfa-otp-enrollment-qr

mfa-otp-enrollment-qr reference screenshot

​
Screen: mfa-otp-enrollment-code

mfa-otp-enrollment-code reference screenshot

​
Screen: mfa-otp-challenge

mfa-otp-challenge reference screenshot

​
Screen: mfa-phone-challenge

mfa-phone-challenge reference screenshot

​
Screen: mfa-phone-enrollment

mfa-phone-enrollment reference screenshot

​
Screen: mfa-push-welcome

mfa-push-welcome reference screenshot

​
Screen: mfa-push-enrollment-qr

mfa-push-enrollment-qr reference screenshot

​
Screen: mfa-push-challenge-push

mfa-push-challenge-push reference screenshot

​
Screen: mfa-push-list

mfa-push-list reference screenshot

​
Screen: mfa-recovery-code-enrollment

mfa-recovery-code-enrollment reference screenshot

​
Screen: mfa-recovery-code-challenge

mfa-recovery-code-challenge reference screenshot

​
Screen: mfa-country-codes

mfa-country-codes reference screenshot

​
Screen: mfa-sms-enrollment

mfa-sms-enrollment reference screenshot

​
Screen: mfa-sms-challenge

mfa-sms-challenge reference screenshot

​
Screen: mfa-sms-list

mfa-sms-list reference screenshot

​
Screen: mfa-voice-enrollment

mfa-voice-enrollment reference screenshot

​
Screen: mfa-voice-challenge

mfa-voice-challenge reference screenshot

​
Screen: mfa-webauthn-platform-enrollment

mfa-webauthn-enrollment reference screenshot

​
Screen: mfa-webauthn-roaming-enrollment

mfa-webauthn-guidance-enrollment reference screenshot

​
Screen: mfa-webauthn-platform-challenge

mfa-webauthn-challenge-user-initiated reference screenshot

​
Screen: mfa-webauthn-roaming-challenge

mfa-webauthn-challenge-user-initiated reference screenshot

​
Screen: mfa-webauthn-change-key-nickname

mfa-webauthn-change-key-nickname reference screenshot

​
Screen: mfa-webauthn-enrollment-success

mfa-webauthn-enrollment-success reference screenshot

​
Screen: mfa-webauthn-error

mfa-webauthn-error reference screenshot

​
Screen: mfa-webauthn-not-available-error

mfa-webauthn-not-available-error reference screenshot

​
Screen: organization-selection

organization-selection reference screenshot

​
Screen: organization-picker

organization-picker reference screenshot

​
Screen: reset-password-request

reset-password-request reference screenshot

​
Screen: reset-password-email

reset-password-email reference screenshot

​
Screen: reset-password

reset-password reference screenshot

​
Screen: reset-password-success

reset-password-success reference screenshot

​
Screen: reset-password-error

reset-password-error reference screenshot

​
Screen: reset-password-mfa-email-challenge

reset-password-mfa-email-challenge reference screenshot

​
Screen: reset-password-mfa-otp-challenge

reset-password-mfa-otp-challenge reference screenshot

​
Screen: reset-password-mfa-phone-challenge

reset-password-mfa-phone-challenge reference screenshot

​
Screen: reset-password-mfa-push-challenge-push

reset-password-mfa-push-challenge-push reference screenshot

​
Screen: reset-password-mfa-recovery-code-challenge

reset-password-mfa-recovery-code-challenge reference screenshot

​
Screen: reset-password-mfa-sms-challenge

reset-password-mfa-sms-challenge reference screenshot

​
Screen: reset-password-mfa-voice-challenge

reset-password-mfa-voice-challenge reference screenshot

​
Screen: reset-password-mfa-webauthn-platform-challenge

reset-password-mfa-webauthn-platform-challenge reference screenshot

​
Screen: reset-password-mfa-webauthn-roaming-challenge

reset-password-mfa-webauthn-roaming-challenge reference screenshot

​
Screen: passkey-enrollment

passkey-enrollment reference screenshot

​
Screen: passkey-enrollment-local

passkey-enrollment-local reference screenshot

​
Screen: phone-identifier-challenge

phone-identifier-challenge reference screenshot

​
Screen: phone-identifier-enrollment

phone-identifier-enrollment reference screenshot

​
Screen: signup

signup reference screenshot

​
Screen: signup-id

signup-id reference screenshot

​
Screen: signup-password

signup-password reference screenshot

​
Screen: status

status reference screenshot

​
Custom query parameters

Auth0 recommends you treat ext- parameters as untrusted since these values can be attacker-controlled URL inputs. You should follow the recommended steps to mitigate security concerns:
  • Use HTML-escaped outputs in templates
  • Do not interpolate ext- values in <script> blocks or event handler attributes
  • Validate against JavaScript or data schemes before you use these values in URLs
You should note, the character allowlist does not eliminate all XSS risk in every rendering context. To learn more about security guidelines and recommendations, review Security Guidance.
You can also use query parameters within the context by passing them to the /authorize endpoint when initiating the authentication request. These custom query parameters must have the ext- prefix. The following example uses the ext-ga and ext-test query parameters to the login page template:
Custom query parameters have the following limitations:
  • Each ext- parameter name must be unique
  • One authorize request can can contain a maximum of ten ext- parameters
  • The ext- parameter name must start with ext-, contain only [a-zA-z0-9_-], and be a maximum of 28 characters, as in the following: /^ext-[\w-]{1,28}$/
  • The ext- parameter value must contain only [a-zA-Z0-9-.*~@+ /:_], and be a maximum of 255 characters, as in the following: /^[-\w.*~@+ /:]{1,255}$/

​
Custom signup prompts

If you use custom signup prompts, you must enable custom page templates. The following is the minimum template that allows custom signup prompts to render:
To learn more, review Customize Signup and Login Prompts.

​
Examples

​
Login box + image layout

The following template will show the login box to the left, and an image to the right only for the login/signup pages. The rest of the pages will look like the default ones.
Universal Login box with email username/password and image layout example

​
Page footers

The example below adds a gray footer with links to Privacy Policy and Terms of Services:
Universal Login box with email address/password and footers layout example

​
Page templates API

To set the page template, you need to use the . You first need to get a Management API token with the update:branding, read:branding, delete:branding scopes. If you are using the API Explorer Application to generate tokens, make sure those scopes are enabled for the Auth0 Management API. To set the template, you need to use the following endpoint:
Using the Auth0 CLI? If you haven’t already, set up and authenticate your CLI session before running this command.
To retrieve the template, you need to use the following endpoint: To delete the template, you need to use the following endpoint: The maximum size for the Page Template is 100KB. If that is not big enough, consider moving images/css files outside of the Page Template code.

​
CSS customization

Page template limitations:
  • CSS class names change each time Auth0 builds the project. Custom CSS that targets these classes will break with each new build.
  • The HTML structure of Universal Login pages is subject to change. Avoid customizations that rely on the HTML structure to prevent any interruptions.
There are a few things that you can customize using CSS:
  • You can resize the login prompt by enclosing the variables below in <style> tags in the <head> element.
    • Use --prompt-width to adjust the container width. Its default value is 400px.
    • For Forms: Use --form-max-width to set the maximum form width. Its default value is 500px.
      • To apply your code to the Form page only, include {% if prompt.name == "custom-form" %} in the <head> element.
  • You can use a Google font by importing it and overriding the --font-family CSS variable.
  • You can hide the tenant logo by adding class="_hide-prompt-logo" in the <body> element.
  • You can specify a custom logo by adding class="_use-custom-prompt-logo" in the <body> element. This would let you, for example, change the login page logo depending on the application:
The current implementation does not support further CSS customization. If you look at the HTML that is generated, you will see code like:

​
Using the Auth0 CLI

You can use the Auth0 CLI to easily update Page Templates. In the Auth0 CLI, run: auth0 universal-login customize The Auth0 CLI will open two windows:
  • A browser window with a Storybook that shows the login page with the page template applied:
Page Templates Storybook
  • The default editor, with the page template code:
undefined
You can now change the page template code, and you will be able to preview the changes in your browser window. Once you close the window, you’ll be asked if you want to save the template. If you answer Yes, the template will be uploaded to your tenant.

​
Troubleshooting

If the template is not being applied, verify that you’re navigating to {customDomain}/authorize. If you’re navigating to {yourDomain}/authorize, Auth0 will not render the page template.