Universal Login
This document clarifies how the New Universal Login page can be customized, and provides guidance on when to use specific techniques.
Customization
A custom domain must be enabled for New Universal Login page customizations to work. This is one major difference between New and Classic Universal Login.
Three mechanisms are available for customizing the Universal Login page.
No-Code Editor: Style the login widget in New Universal Login experience to fit your brand. You can personalize the color, font, borders, and backgrounds of the widgets your customers see for login, password reset, authentication, and more.
Partials: Allow you to inject custom HTML or JS at specific points in the login widget.
Page Templates: Provide for customizing the layout and appearance of the login page using liquid syntax and page template variables. Cascading Style Sheets (CSS) or Javascript (JS) can be used for more extensive customization. (examples)
Text Prompts: Allow customizing the actual text of the login page. This includes text field names and the text that renders on buttons.
Use the No-Code Editor to make basic changes to the login widget, including color, font, borders, and backgrounds.
Use Partials to add custom content to login and signup pages, or to collect and validate additional data during login or signup.
Use Page Templates to make advanced changes to the layout of the page or implement conditional formatting. Page templates can use CSS or JS to hide certain page elements, as needed.
Use Text Prompts to customize the text displayed on the login page.
Custom Content and Data Capture (Partials)
You can upload custom HTML and JS code, called Partials, to be displayed in specific sections of the New Universal Login widget. Partials can only be updated via the Partials API.
You can use partials to do things like add a “terms and conditions” checkbox that must be checked before the user can complete signup. Partials support client side validation (through Javascript directly on the page) and client side validation (through actions).
Review the documentation for Customizing Signup and Login Prompts.
Page Templates
Page Templates for New Universal Login can only be updated via the Page Templates API. Page templates are used to format the HTML page within which the login widget renders. For example, adding a background or controlling where on the page the widget renders.
CSS Customization
CSS can be used to make minor modifications to the login page. You can add an in-line style sheet, or a link to an external stylesheet in the page template.
Note the CSS class names are not static and customizations targeting them will fail. Class names change when the Auth0 product is updated, which is often. Customizations may work briefly but will fail without notice.
JS customization
JS customizations should be avoided if possible–Partials (covered earlier in this document) are easier to implement and will not be affected by changes to the New Universal Login DOM.
New Universal Login does not depend on JS. It contains some JS, but the essential functions of the page don’t require it. JS script tags can be added to the page template to manipulate page elements. For example, to hide the signup link, consider the following template. Note this introduces a dependency on JS for the page to render as intended. JS customizations also depend on a rigid DOM structure and may break without warning (this is uncommon but has happened).
<!DOCTYPE html>
<html>
<head>
{%- auth0:head -%}
</head>
<body class="_widget-auto-layout">
{%- auth0:widget -%}
<script type="text/javascript">
document.addEventListener("DOMContentLoaded", function (event) {
Element.prototype.remove = function () {
this.parentElement.removeChild(this);
}
NodeList.prototype.remove = HTMLCollection.prototype.remove = function () {
for (var i = this.length - 1; i >= 0; i--) {
if (this[i] && this[i].parentElement) {
this[i].parentElement.removeChild(this[i]);
}
}
}
var xpath = "//a[contains(@href,'signup')]";
var signUpLink = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue;
if (signUpLink) {
signUpLink.parentElement.remove();
}
});
</script>
</body>
</html>
Text Prompts
Prompts can be changed on the Auth0 dashboard under Branding > Universal Login > Advanced Options > Custom Text
A “prompt” is a specific step in the login flow. For example, MFA OTP enrollment (mfa-otp) or signing in with a username and password (login-password). A “screen” is a subset of a prompt. A prompt might have a single screen or multiple screens. The login-password prompt only has a single screen (login-password), where the mfa-otp prompt has the mfa-otp-enrollment-qr screen, and the mfa-otp-enrollment-code screen. The former is the screen for enrolling in MFA OTP with a QR code, and the latter provides a code for the user to manually enter in their authenticator app.
The list of prompts is available at:
https://auth0.com/docs/customize/universal-login-pages/customize-login-text-prompts#prompt-values
Updating Text Prompts via API (advanced use case)
In addition to the dashboard prompt editor, prompts can be updated via the API. The syntax is:
PUT https://tenant.auth0.com/api/v2/prompts/<prompt>/custom-text/<language>
{
"<screen>": {
"<text_id>": "text1 in language"
}
}
Where:
<prompt>= a prompt from the list of prompts above
<language> = a language from the list of supported languages
<screen> = a screen from the prompt
<text_id> = the Key from the screen.
For example, to change the Trouble Scanning? text on the MFA OTP QR code enrollment prompt, for users with their language set to English, send the following payload:
PUT https://tenant.auth0.com/api/v2/prompts/mfa-otp/custom-text/en
{
"mfa-otp-enrollment-qr": {
"codeEnrollmentText": "Click here if you cleaned your camera lens and still have trouble scanning."
}
}