Customize Signup and Login Prompts

Before you start

Make sure your tenant has a Custom Domain configured.
Confirm you are using Universal Login for all signup and login prompts, and ensure the Customize Login Page toggle has been disabled for Login Prompts.
Check that you have a Custom Page Template configured.

Customize Signup and Login Prompts is a feature that allows customers with and Custom Page Template enabled to add custom fields and content to their app’s signup and login prompts.

Use cases

Customize Signup and Login Prompts supports two use cases: custom content and data capture. Custom content is static content like text, links, or images placed directly on the signup and login prompts. Data capture uses form elements dynamically added to the Signup and Login prompts, which is useful for collecting and validating user consent or user-produced data like surname.

Only use Signup and Login Prompt Customizations to convey or collect sensitive or regulated data as permitted under your agreement with Okta.

Terminology

A prompt is a specific step in a given authentication flow. Each prompt has at least one screen and, depending on tenant configuration, each supported screen has either four or six entry points, which are locations in the screen where custom code (partials) can be inserted. The following prompts can be customized: Login screens

login
login-id
login-password
login-passwordless-sms-otp
login-passwordless-email-code
passkey-enrollment
passkey-enrollment-local

Signup screens

signup
signup-id
signup-password
passkey-enrollment
passkey-enrollment-local

Partials support HTML, CSS, JavaScript, and Liquid syntax to power conditional logic and dynamic variables. In addition, any Liquid variable that is available to the Page Template is also supported. These entry points are available when a database or passwordless connection is enabled:

form-content-start
form-content-end
form-footer-start
form-footer-end

The following entry points are available when at least one social or enterprise connection is enabled:

secondary-actions-start
secondary-actions-end

Screenshots of each Custom Prompt option and their partials

Use the Auth0 Dashboard to manage Partials

Use the Dashboard to insert custom fields and content into Login and Signup screens using partials.

Navigate to Auth0 Dashboard > Branding > Universal Login, and select Enhance screens with partials.
Select the Screen to customize with the partials editor.

Screens can have the following Rendering modes:

STANDARD: The screen is rendered using the default Universal Login UI; you can use partials to insert code snippets and template variables.
ADVANCED: The screen is rendered using ACUL and partials do not apply.
ADVANCED (FILTERED): The screen is rendered with ACUL applied to specific applications and organizations; partials only apply to screens excluded from ACUL filters.

Select ENTRY POINTS to insert code snippets and template variables.
Select to add CODE SNIPPETS to the selected entry point.
Select { } to add TEMPLATE VARIABLES to the selected entry point.
Select ACTIONS to add Actions and apply custom logic using your partials fields and content.
Select Save and Publish to update your Screen.

Manage Partials programmatically

You can manage Partials using the Auth0 Management API (GET /prompts/{prompts_name}/partials). Every prompt must specify the screen when adding, updating, or deleting a partial. Partials can be a maximum of 10,000 characters. Partials can also be managed using Auth0 CLI’s Customize Interface by running auth0 ul customize in your terminal.

An image showing the command-line interface for Partials.

Style and validate Form Inputs

Customize Signup and Login Prompts offers pre-built styles and support for client-side validations for certain HTML form elements. The following elements are supported:

<input type="text">
<input type="number">
<input type="checkbox">
<input type="password">
<input type="email">
<input type="tel">
<input type="url">
<select>
<textarea>

To use pre-built input styles, wrap your form element of choice in a <div> with the ulp-field class. Similarly, add the ulp-error class to the same <div> to use pre-built error styles. If the ulp-error-info element is present, a styled error message will also be displayed. You can find pre-built code snippets when using the partials editor.

Client-side validation

The feature’s client-side validation framework allows customers to validate user input using HTML attributes to execute one or more custom validation functions. Validation functions can be included directly in the Partial or included in the <head> of the page template. To add client-side validation to a form element:

Reference the validation function using the data-ulp-validation-function attribute on the <div class="ulp-error-info"> element.
Declare which DOM events the validation function should be run on using the data-ulp-validation-event-listeners attribute on the <div class="ulp-error-info"> element, noting that validations run automatically on submission.
For WCAG compliance, inputs must be programmatically linked to their error messages - for example, by using aria-describedby="error-id" and aria-invalid="true" - to ensure screen readers announce validation errors.

Be cautious when using third-party JavaScript on your signup page. Sensitive security-related information often flows through the signup page, leaving it vulnerable to cross-site scripting.Whenever possible, Auth0 recommends validating user-provided data before submitting.

Localize content

Partial content can be localized by defining new custom text variables using the Custom Text API. Up to thirty custom text variables can be defined per screen/language combination.

Create or update a custom text variable

Manage custom text variables with the Custom Text API. Calls must specify the screen when adding, updating, or deleting a custom text variable. Custom text variables follow the var-<name> naming convention. Markdown links are supported and are converted to HTML <a> elements before being displayed to users. Below is an example call to add a variable for the text of a terms of service checkbox label in English and Spanish. See the to learn more.

# PUT /api/v2/prompts/signup-id/custom-text/en
{
  "signup": {
    "var-tos": "I agree with the [Terms of Service](https://en.example.com/tos)"
  }
}

# PUT /api/v2/prompts/signup-id/custom-text/es
{
  "signup": {
    "var-tos": "Estoy de acuerdo con los [Términos de Servicio](https://es.example.com/tos)"
  }
}

Use a custom text variable in a Partial

Custom text variables are referenced in partials using the prompts.screen.text object; the reference for the var-tos example in the previous section is prompt.screen.text.varTos. See below for an example of how to use a previously created variable in a partial on the Signup ID Prompt, noting that the Management API’s var-tos variable is referenced as varTos in the partial.

# PUT api/v2/prompts/signup/partials
<div class='ulp-field'>
  <input type='checkbox' name='ulp-terms-of-service' id='terms-of-service'>
  <label for='terms-of-service'>{{ prompt.screen.text.varTos }}</label>
</div>

Validate and save captured data

Data captured by custom form elements is available in Actions, and Auth0 recommends validating the data collected before saving or submitting it.

When using custom form elements, you must include the ulp- prefix with any input names to ensure the data is available to Actions.

Each Action receives the captured data as an object on the event.request.body. Customers can return a validation error by using the api.validation.error function. When using a database connection:

Data from the Signup Prompts is accessible on the pre-user-registration trigger. A validation error from the trigger prevents the user from registering.
Data from Login Prompts is accessible on the post-login trigger. Validation errors are forwarded to the customer’s application error page.

When using social or enterprise connections:

Data from Login Prompts is accessible on the post-login trigger. Validation errors are forwarded to the customer’s application error page.

When using a custom database connection:

Data from the Signup Prompts is accessible on the pre-user-registration trigger with the following custom database action scripts: Create User and Login.
Data from Login Prompts is accessible on the post-login trigger with the following custom database action scripts: Login and Change Password.

To use custom database action scripts, enable Context objects in database scripts in your custom database connection. To learn more, read Enable context object.

When using a Passwordless connection:

Data from both the Signup and Login Prompts is accessible on the post-login trigger. Validation errors are forwarded to the customer’s application error page.

When using passkey prompts:

Data from the passkey-enrollment prompt is accessible on the pre-user-registration trigger. A validation error from the trigger prevents the user from registering.
The passkey-enrollment and passkey-enrollment-local prompts never capture data on the Post Login trigger.
Data from the passkey-enrollment-local prompt is not accessible since it is always displayed after the post-login trigger is run.

Sanitize any data that you collect on the form before saving or rendering it.

Ensure any data being saved has passed through Liquid’s {{escape}} helper function
If you render data in an Email Template, remove Liquid syntax
If you render data on a webpage, escape HTML entities
If you save data to a database, use parameterized queries
If you pass data into query string, encode with eg: {{encodeURI}} or {{encodeURIParam}}

For more information regarding risk mitigation and best practices for securely storing data see this cheatsheet.

Save to user metadata

From the Action, captured data can be sent to an external API for validation and storage or saved in user_metadata on the user via api.user.setUserMetadata.

// Given this code in the signup form
// <div class="ulp-field">
//   <label for="full-name">Full Name</label>
//   <input type="text" name="ulp-full-name" id="full-name">
// </div>

exports.onExecutePreUserRegistration = async (event, api) => {
  const fullName = event.request.body['ulp-full-name'];
  if(!fullName) {
    api.validation.error("invalid_payload", "Missing Name");
    return;
  }

  api.user.setUserMetadata("fullName", fullName);
};

Before you start

​Use cases

​Terminology

​Use the Auth0 Dashboard to manage Partials

​Manage Partials programmatically

​Style and validate Form Inputs

​Client-side validation

​Localize content

​Create or update a custom text variable

​Use a custom text variable in a Partial

​Validate and save captured data

​Save to user metadata

Use cases

Terminology

Use the Auth0 Dashboard to manage Partials

Manage Partials programmatically

Style and validate Form Inputs

Client-side validation

Localize content

Create or update a custom text variable

Use a custom text variable in a Partial

Validate and save captured data

Save to user metadata