diff --git a/main/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts.mdx b/main/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts.mdx index 996c19b271..2bd52af6a1 100644 --- a/main/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts.mdx +++ b/main/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts.mdx @@ -13,20 +13,19 @@ title: Customize Signup and Login Prompts **Customize Signup and Login Prompts** is a feature that allows customers with Custom Domain and Custom Page Template enabled to add custom fields and content to their app’s signup and login prompts. -#### Use Cases +## 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. +**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 +## 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. @@ -45,7 +44,6 @@ The following prompts can be customized: * `signup` * `signup-id` * `signup-password` -* `customized-consent` * `passkey-enrollment` * `passkey-enrollment-local` @@ -65,59 +63,39 @@ The following entry points are available when at least one social or enterprise ![Screenshots of each Custom Prompt option and their partials](/docs/images/cdy7uua7fh8z/7sQVWVbaTp4VMW4nJjsn2G/74d0b30da7b034bd695274dbd146964b/Custom_Prompts.png) -#### Use the Auth0 Dashboard to manage Partials +## Use the Auth0 Dashboard to manage Partials Use the Dashboard to insert custom fields and content into Login and Signup screens using partials. 1. Navigate to [Auth0 Dashboard > Branding > Universal Login](https://manage.auth0.com/#/universal-login/customize-partials), and select **Enhance screens with partials**. -2. Select the **Screen** to customize with the partials editor. +2. 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](/docs/customize/login-pages/universal-login) UI; you can use partials to insert code snippets and [template variables](/docs/customize/login-pages/universal-login/customize-templates#page-template-variables). +* **STANDARD**: The `screen` is rendered using the default [Universal Login](/docs/customize/login-pages/universal-login) UI; you can use partials to insert code snippets and [template variables](/docs/customize/login-pages/universal-login/customize-templates#page-template-variables). * **ADVANCED**: The `screen` is rendered using [ACUL](/docs/customize/login-pages/advanced-customizations) 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. -3. Select **** **ENTRY POINTS** to insert code snippets and template variables. +3. Select **** **ENTRY POINTS** to insert code snippets and template variables. -4. Select **** to add **CODE SNIPPETS** to the selected entry point. +4. Select **** to add **CODE SNIPPETS** to the selected entry point. -5. Select **\{ }** to add **TEMPLATE VARIABLES** to the selected entry point. +5. Select **\{ }** to add **TEMPLATE VARIABLES** to the selected entry point. -6. Select **** **ACTIONS** to add [Actions](/docs/customize/actions/actions-overview) and apply custom logic using your partials fields and content. +6. Select **** **ACTIONS** to add [Actions](/docs/customize/actions/actions-overview) and apply custom logic using your partials fields and content. 7. Select **Save and Publish** to update your **Screen**. - ![[partials]](/docs/images/universal-login/partials-editor.png) +## Manage Partials programmatically -#### Use the Management API to manage Partials - -Partials can be a maximum of 10,000 characters. You can manage Partials using the [Auth0 Management API](https://auth0.com/docs/api/management/v2/prompts/put-partials) at `/v2/prompts/{prompts_name}/partials`. Every prompt must specify the `screen` when adding, updating, or deleting a partial. Below is an example call to view all existing partials for a prompt, noting that `ulp-container` prefix is not required when referencing entry points in API calls. - -```json lines -GET /api/v2/prompts/signup-id/partials -# response -# success code: 200 -# not found code: 404 -body: { - "signup-id": { - "form-content-start": "
HTML or Liquid
...", - "form-content-end": "
HTML or Liquid
..." - } -} -``` - - - - - +You can manage Partials using the [Auth0 Management API](https://auth0.com/docs/api/management/v2/prompts/put-partials) (`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 Universal Login Customize Interface by running `auth0 ul customize` in your terminal. ![An image showing the command-line interface for Partials. ](/docs/images/cdy7uua7fh8z/KxWfVAMkumyI2jrUqkEp8/b9315709899864a2f8758ad7f5a4f5b2/Partials_CLI_Image.jpg) -#### Style and Validate Form Inputs +## 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: @@ -133,7 +111,9 @@ Customize Signup and Login Prompts offers pre-built styles and support for clien To use pre-built input styles, wrap your form element of choice in a `
` with the `ulp-field` class. Similarly, add the `ulp-error` class to the same `
` to use pre-built error styles. If the `ulp-error-info` element is present, a styled error message will also be displayed. -#### Client-Side Validation +You can find pre-built code snippets when using the [partials](#use-the-auth0-dashboard-to-manage-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 `` of the page template. @@ -143,145 +123,19 @@ To add client-side validation to a form element: * Declare which DOM events the validation function should be run on using the `data-ulp-validation-event-listeners` attribute on the `
` 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. - - - - -```html lines -
- - -
- First Name is Required -
-
-``` - - - - -```html lines -
- - -
- Please Select a Language. -
-
-``` - - - - -```html lines -
- - -
- Please provide an answer. -
-
-``` - - - - -```html lines -
- - -
- Please agree to the Terms of Service. -
-
-``` - - - - -```javascript lines -// Validation Function - - -// Custom Input Field including the validation error HTML -
- - -
- Invalid phone number -
-
-``` - - - - ```html lines - - -
- - - -
- ``` - - - - - - - - + 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 +## Localize content -Partial content can be localized by defining new custom text variables using the [Custom Text API](https://auth0.com/docs/api/management/v2/prompts/put-custom-text-by-language). Up to thirty custom text variables can be defined per screen/language combination. +Partial content can be localized by defining new custom text variables using the [Custom Text API](/docs/api/management/v2/prompts/put-custom-text-by-language). Up to thirty custom text variables can be defined per screen/language combination. -##### Create or Update a Custom Text Variable +### Create or update a custom text variable -The Custom Text API is available [here](https://auth0.com/docs/api/management/v2/prompts/get-custom-text-by-language) and each variable follows a `var-` naming convention. Calls to the API must specify the screen when adding, updating, or deleting a custom text variable. Markdown links are supported and are converted to HTML `` elements before being displayed to users. +Manage custom text variables with the [Custom Text API](/docs/api/management/v2/prompts/get-custom-text-by-language). Calls must specify the `screen` when adding, updating, or deleting a custom text variable. Custom text variables follow the `var-` naming convention. Markdown links are supported and are converted to HTML `` 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 Management API to learn more. @@ -301,12 +155,7 @@ Below is an example call to add a variable for the text of a terms of service ch } ``` - - - - - -##### Use a Custom Text Variable in a Partial +### 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. @@ -314,40 +163,50 @@ Custom text variables are referenced in partials using the `prompts.screen.text` # PUT api/v2/prompts/signup/partials
- +
``` +## Validate and save captured data -#### Validate and Save Captured Data - -Data captured by custom form elements is available in Actions, and Auth0 recommends validating the data collected - - +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](/docs/customize/actions/actions-overview). - - + 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: +When using a [database connection](/docs/authenticate/database-connections#use-auth0-user-store): -* Data from the Signup Prompts is accessible on the [`pre-user-registration`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger) trigger. A validation error from the trigger prevents the user from registering. +* Data from the Signup Prompts is accessible on the [`pre-user-registration`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger) trigger. A validation error from the trigger prevents the user from registering. * Data from Login Prompts is accessible on the [`post-login`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) trigger. Validation errors are forwarded to the customer’s application error page. -When using a Passwordless connection: +When using a [custom database connection](/docs/authenticate/database-connections/custom-db): + +* Data from the Signup Prompts is accessible on the [`pre-user-registration`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger) trigger with the following custom database action scripts: [Create User](/docs/authenticate/database-connections/custom-db/templates/create) and [Login](/docs/authenticate/database-connections/custom-db/templates/login). + +* Data from Login Prompts is accessible on the [`post-login`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) trigger with the following custom database action scripts: [Login](/docs/authenticate/database-connections/custom-db/templates/login) and [Change Password](/docs/authenticate/database-connections/custom-db/templates/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](https://auth0.com/docs/authenticate/database-connections/custom-db/create-db-connection#enable-context-object). + + +When using a [Passwordless connection](/docs/authenticate/passwordless/passwordless-with-universal-login): * Data from both the Signup and Login Prompts is accessible on the [`post-login`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) trigger. Validation errors are forwarded to the customer’s application error page. -When using `passkey` prompts: +When using [`passkey`](/docs/authenticate/database-connections/passkeys) prompts: -* Data from the `passkey-enrollment` prompt is accessible on the [`pre-user-registration`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger) trigger. A validation error from the trigger prevents the user from registering. +* Data from the `passkey-enrollment` prompt is accessible on the [`pre-user-registration`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger) 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`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) trigger is run. - +When using social or enterprise connections: +* Data is *not* captured when a user logs in with either a [social](/docs/authenticate/identity-providers/social-identity-providers) or an [enterprise](/docs/authenticate/enterprise-connections) connection. + + 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](https://shopify.github.io/liquid/filters/escape/) @@ -357,10 +216,9 @@ Sanitize any data that you collect on the form before saving or rendering it. * 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](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html). + - - -##### Save to User Metadata +### 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`. @@ -382,11 +240,6 @@ exports.onExecutePreUserRegistration = async (event, api) => { }; ``` - - - - - ## Learn more * [Use Dynamic Variables to Internationalize Custom Form Elements](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts/use-dynamic-variables-to-internationalize-custom-form-elements)