Sign-up Prompt Customizations

Before you start

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

Early Access Note: Sign-up Prompt Customizations is currently available in Early Access. If you are interested in using this feature, contact Auth0 support. To learn more about Auth0 release stages, review Product Release Stages.

Sign-up Prompt Customizations is an Early Access feature from Auth0 that allows customers with Custom Domain and Custom Page Template enabled to add custom fields and messages to their app’s sign-in prompts.

Supported content types

Two use cases are supported in the early access release for customizing the signup prompts: custom content and data capture.

Custom content is static content like text, links, or images placed directly on the signup prompt.

Data capture uses dynamic form elements generated on the signup prompt and captured in a database, which is useful for collecting and validating user consent or user-produced data like surname. This feature is unavailable if you have Passwordless signup flow enabled.

Only use Custom Fields to convey or collect sensitive or regulated data as permitted under your agreement with Okta.

Auth0 has three signup prompts that can be customized: signup, signup ID, and signup password. Sign-up Prompt Customizations allow insertion of custom code, referred to as Partials, into the prompts. 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 available.

Each prompt type has six potential customization points when using database and/or passwordless connections, of which four are always available and two are available when displaying federated connections:

ulp-container-form-content-start
ulp-container-form-content-end
ulp-container-form-footer-start
ulp-container-form-footer-end

The following customization points require federated connections to be displayed:

ulp-container-secondary-actions-start
ulp-container-secondary-actions-end

Style and validate form inputs

To use this feature's pre-built element styles, wrap each input, textarea, select, or checkbox element in a <div> with the ulp-field class, Similarly, add the ulp-error class to the <div> to use pre-built error styles. If the ulp-error-info element is present, a styled error message will also be displayed.

Input Field Elements

Pre-built element and error styling for input fields

<div class="ulp-field">
  <label for="first-name">First Name</label>
  <input type="text" name="ulp-first-name" id="first-name">
  <div class="ulp-error-info">
    First Name is Required
  </div>
</div>

Was this helpful?

Select Elements

Pre-built element and error styling for select fields

<div class="ulp-field">
  <label for="preferred-language">Preferred Language</label>
  <select name="ulp-preferred-language" id="preferred-language">
    <option></option>
    <option value="english">English</option>
    <option value="french">French</option>
    <option value="spanish">Spanish</option>
  </select>
  <div class="ulp-error-info">
    Please Select a Language.
  </div>
</div>

Was this helpful?

Text Elements

Pre-built element and error styling for text fields

<div class="ulp-field">
  <label for="comments">Comments</label>
  <textarea type="text" name="ulp-comments" id="comments"></textarea>
  <div class="ulp-error-info">
    Please provide an answer.
  </div>
</div>

Was this helpful?

Checkbox Elements

Pre-built element and error styling for checkbox fields

<div class="ulp-field">
  <input type="checkbox" name="ulp-terms-of-service" id="terms-of-service">
  <label for="terms-of-service">
    I agree to the <a href="#">Terms of Service</a>
  </label>
  <div class="ulp-error-info">
    Please agree to the Terms of Service.
  </div>
</div>

Was this helpful?

Client-side validation

To validate a user's input, Auth0 recommends that the validation functions be included in the Partial unless they need to be available to multiple Partials, in which case it needs to be in the <head> of the page template.

To add client-side validation to a form element:

Reference the javascript 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.

Phone Number Validation

Client-Side Phone Number Validation

// Phone Validation Library
<script src="https://cdn.jsdelivr.net/npm/imask@7.1.3/dist/imask.min.js" referrerpolicy="no-referrer"></script>

// Validation Function
<script>
  IMask(document.getElementById('ulp-field-phone'), {mask: '(000) 000-0000'});
  function validatePhoneFunction(element, formSubmitted) {
    if (!formSubmitted) {
      return true;
    }

    return element.value.replace(/\D/g, '').length === 10;
  }
</script>

// Custom Input Field including the validation error HTML
<div class="ulp-field">
  <label for="ulp-field-phone">Phone Number</label>
  <input type="text" name="ulp-field-phone" id="ulp-field-phone">
  <div
    class="ulp-error-info"
    data-ulp-validation-function="validatePhoneFunction"
    data-ulp-validation-event-listeners="blur,change,input,focus">
    Invalid phone number
  </div>
</div>

Was this helpful?

Be extremely 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.

Use the API to edit custom prompts

Access the Partials API at /v2/prompts/{prompts_name}/partials in the Auth0 Management API. Every Prompt must specify the Screen when adding, updating, or deleting a Partial.

The calls allowed are READ, ADD, UPDATE, and DELETE, and below are example calls for each.

View Partials

View all the Partials for a Prompt via GET

GET /api/v2/prompts/signup-id/partials
# response
# success code: 200
# not found code: 404
body: {
  "signup-id": {
    "form-content-start": "<div>HTML or Liquid</div>...",
    "form-content-end": "<div>HTML or Liquid</div>...",
  }
  }

Was this helpful?

Add Partials

Add one or more Partials to one or more Entry Points on a Prompt via PUT

# eg: PUT /api/v2/prompts/signup-id/partials

# Request Body
{
  "signup-id": {
    "form-content-start": "<div>NEW HTML or Liquid</div>...",
    "form-content-end": "<div>NEW HTML or Liquid</div>...",
  }
}
# response
success code: 200
body: {
  "signup-id": {
    "form-content-start": "<div>NEW HTML or Liquid</div>...",
    "form-content-end": "<div>NEW HTML or Liquid</div>...",
  }
}

Was this helpful?

Update Partials

Update one or more Partials in one or more Entry Points on a Prompt via PUT

# eg: PUT /api/v2/prompts/signup-id/partials

# current resource
# {
#   "signup-id": {
#     "form-content-start": "<div>HTML or Liquid</div>...",
# "form-content-end": "<div>HTML or Liquid</div>...",
#   }
# }

# request
{
  "signup-id": {
    "form-content-start": "<div>UPDATED HTML or Liquid</div>...""
  }
}

#response
success code: 200
body: {
  "signup-id": {
    "form-content-start": "<div>UPDATED HTML or Liquid</div>...",
    "form-content-end": "<div>HTML or Liquid</div>...",
  }
}

Was this helpful?

Delete Partials

Delete one or more Partials on a Prompt via PUT

# Delete a single partial
# eg: PUT /api/v2/prompts/signup-id/partials

# current resource
# {
#  "signup-id": {
#    "actionable-form-start": "<div>HTML or Liquid</div>...",
#    "actionable-field-username-end": "<div>HTML or Liquid</div>...",
#    "actionable-form-end": "<div>HTML or Liquid</div>...",
#   }
# }

# request (note missing "actionable-form-start" entry)
{
  "signup-id": {
    "actionable-field-username-end": "<div>HTML or Liquid</div>...",
    "actionable-form-end": "<div>HTML or Liquid</div>...",
  }
}

# response
success code: 200
body: {
  "signup-id": {
    "actionable-field-username-end": "<div>HTML or Liquid</div>...",
    "actionable-form-end": "<div>HTML or Liquid</div>...",
  }
}

# Delete all partials for a screen
# eg: PUT /api/v2/prompts/signup-id/partials

# current resource
# {
#  "signup-id": {
#    "actionable-form-start": "<div>HTML or Liquid</div>...",
#    "actionable-field-username-end": "<div>HTML or Liquid</div>...",
#    "actionable-form-end": "<div>HTML or Liquid</div>...",
#   }
# }

# request
{
  "signup-id": null
}

# response
success code: 200
body: {}

Was this helpful?

Example cURL Request

Use cURL to request a response from the API

URL='https://YOUR_TENANT.auth0.com'
ENDPOINT="$URL/api/v2/prompts/signup/partials"
TOKEN="YOUR_ACCESS_TOKEN"
JSON_BODY='{"signup": {"form-content-start": "<div>HTML or Liquid</div>","form-content-end": "<div>HTML or Liquid</div>"}}'

curl -X PUT \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d $JSON_BODY\
"$ENDPOINT"

Was this helpful?

For further examples and tutorials of how to add custom prompts to your signup flow, see Use Dynamic Variables to Internationalize Custom Form Elements and Use Actions to Validate and Store End-user Data Gathered By Sign-Up Prompt Customizations.

Save captured data

Data captured in the Sign-up Prompts is accessible with Actions on the Pre User Registration Flow, where the onExecutePreUserRegistration handler receives the captured data as an object on the event.request.body. The handler also includes a new api.validation.error function that returns a validation error to the prompt and prevents the registration from going forward.

Validate and save a name

Example of how to validate data and save it

#Given this code in the entry point
<div class="ulp-field">
<label for="first-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);
};

Was this helpful?

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.

Sign-up Prompt Customizations

Home

Get Started

Authenticate

Manage Users

Customize

Secure

Deploy and Monitor

Troubleshoot

Sign-up Prompt Customizations

Before you start

Supported content types

Style and validate form inputs

Client-side validation

Use the API to edit custom prompts

Save captured data

Home

Get Started

Authenticate

Manage Users

Customize

Secure

Deploy and Monitor

Troubleshoot

Sign-up Prompt Customizations

Before you start

Supported content types

Signup prompt entry points

Style and validate form inputs

Client-side validation

Use the API to edit custom prompts

Save captured data