Use Cases: Configure a progressive profile form using Forms

Before you start

Create a Machine-to-Machine Application with the following scopes enabled:

read:users
update:users
create:users
read:users_app_metadata
update:users_app_metadata
create:users_app_metadata

Private Beta Note: Forms for Actions is currently in Private Beta Access. To learn more about Auth0 release stages, review Product Release Stages.

Forms for Actions allows you to create a custom form to prompt the user for missing information, such as company name and job title, and store them as user_metadata attributes.

The sections below outline how you can create a progressive profile form using nodes and flows, along with steps for adding your form to a Post Login Action.

Create a form with Forms for Actions

To create a new information gathering form, follow these steps:

Navigate to Auth0 Dashboard > Actions > Forms.
Select Actions > Forms to open the Form editor in a new tab.
Select Create form > Start from scratch.

By default, a new form contains a Start node, a Step node, and an Ending screen node.

Configure the Start node

To ensure that the Auth0 pipeline connection is secure, add a Hidden field variable named context_token by following these steps:

Select the Start node from the Form editor.
Select Add New Item.
Enter context_token. A Default value is not needed.
Select Publish to save.

Dashboard > Forms > Uses cases > Start node

Add a Get user flow

Add a Get user Flow node to validate the context_token value, gather user data, and store this information for further processing by following these steps:

Select Flow from the bottom of the Form editor.
Remove the existing link between the Start and Step nodes.
Select the new Flow > Click to add a flow > Create a new flow.
1. Enter Get user in the Name field.
2. Select Create.
Link the Flow Get user node to the Start and Step nodes.
Select Publish to save.

Dashboard > Forms > Use Case > Get user flow node

Select the Flow Get user > Edit flow to open the Flow editor in a new tab.
Below the Start Action, select the + icon to add a Verify JSON web token Action. Complete the fields below, then select Save to continue.
- ID: Enter verifyJwt.
- Connection: Select the + icon to add a connection.
  - Secret: Enter MY_SECRET_PASSWORD, then select Continue.
    Replace MY_SECRET_PASSWORD with a long random string to use in the Verify JSON web token connection Action and the custom Post Login Action.
  - Connection name: Enter JWT_Login_flow, then select Add Connection.
- Token: Enter {{input.body.context_token}}.
Below the Verify JSON web token Action, add an if/then condition Action. Complete the fields below, then select Save to continue.
- Alias: Enter Verify context_token.
- Condition: Enter {{verifyJwt.valid}}, then select is true from the dropdown menu.
Below the True branch of the if/then condition Action, add an Auth0 Get user Action. Complete the fields below, then select Save to continue.
- ID: Enter getUser.
- Connection: Select the + icon to add a connection to the Machine to Machine Application.
- User ID: Enter {{verifyJwt.payload.user_id}}.
Below the Auth0 Get user Action, add a Store state variable Action. Complete the field below, then select Save to continue.
- Data fields: Enter user, then enter {{getUser.body}} as the value.
Below the False branch of the if/then condition Action, add a Show error message Action. Complete the fields below, then select Save to continue.
- Alias: Enter Invalid context_token.
- Error message: Enter We're sorry, but your context_token is not valid.
Select Publish to save.

Dashboard > Forms > Use Cases > Get user flow actions

The Verify JSON web token Action validates the value of the context_token hidden field.
The If/then condition Action logically routes the flow based on the value returned from the Verify JSON web token Action.
The Auth0 Get user Action collects the user data using the user Id received from the Verify JSON web token Action.
The Store state variable Action stores the data received from the Auth0 Get user Action.
The Show error message Action displays an error if the If/then condition Action returns false.

Add a Router node

Add a Router node that reviews the user_metadata.company_name and user_metadata.job_title values to determine the appropriate next steps. If the values are missing, the flow continues to the Step node to prompt the user for the information. If the values are present, the authentication flow resumes to login.

Return to the Form editor and select Router.
Remove the existing link between the Get user Flow and Step nodes.
Select the new Router node to add a new rule.
1. Select Rule 1.
2. Alias: Enter Check company_name and job_title.
3. Variable:
  1. Enter {{state.user.user_metadata.company_name}}.
  2. From the dropdown menu, select has not value.
4. Select Or.
5. Variable:
  1. Enter {{state.user.user_metadata.job_title}}.
  2. From the dropdown menu, select has not value.
6. Select Publish to save.
Add a link from the rule Check company_name and job_title to the Step node and link the Default Case rule to the Ending screen node.
Select Publish to save.

Configure the Step node

The Step node is the graphical interface visible to users. Add Fields to the Step node to collect the new agreement acceptance value by following these steps:

Drag a Rich text field from the Components menu into the Step node.
- Rich text: Enter a custom message.
  - Example: Complete your profile! We need you to complete your profile to personalize your experience.
Drag a Text field into the Step node.
- ID: Enter company_name.
- Label: Enter Company name.
- Label: Enable the checkbox.
- Required: Enable the checkbox.
Drag a Text field into the Step node.
1. ID: Enter job_title.
2. Label: Enter Job title.
3. Label: Enable the checkbox.
4. Required: Enable the checkbox.
Select Publish to save.

Add an Update user_metadata flow

Add a Flow node after the Step node to update the user_metadata and resume the authentication flow by following these steps:

Select Flow from the bottom of the Form editor.
Remove the existing link between the Step and Ending Screen nodes.
Select the new Flow > Click to add a flow > Create a new flow.
- Enter Update user_metadata in the Name field.
- Select Create.
Link the Flow node to the Step and Ending Screen nodes as pictured below.
Select Publish to save.

Select the Flow Update user_metadata > Edit flow to open the Flow editor in a new tab.
Below the Start Action, select the + icon to add an Auth0 Update user Action. Complete the fields below, then select Save to continue.
- Connection: From the dropdown menu, select the same connection as used in the Flow Get user.
- User ID: Enter {{state.user.user_id}}.
- Body: Copy and paste the following code
  { "user_metadata": { "job_title": "{{input.body.job_title}}", "company_name": "{{input.body.company_name}}" } }
  Was this helpful?
  /
Select Publish to save.

Retrieve your form embed code

Retrieve your form embed code to visually render the form with a custom Post Login Action by following these steps:

From the Form editor, select the Embed tab.
Select Copy.

Dashboard > Forms > Use Case > Embed Code

Create a custom Post Login Action to render your form by following these steps:

Navigate to Auth0 Dashboard > Actions > Flows > Login.
Select Custom.
Select the + icon to Build from scratch:
- Name: Enter Render Progressive Profile Form.
- Trigger: Select Login / Post Login.
- Runtime: Select Node 18 (Recommended).
Select Create.

To configure the custom Action:

Delete the existing code from the Code editor.
Paste the form embed code into the Code editor.
To add a Secret, select the Key icon from the left-side menu of the Code editor.
Select Add Secret.
- Key: Enter SHARED_CONTENT_TOKEN_SECRET.
- Value: Enter MY_SECRET_PASSWORD.
  Replace MY_SECRET_PASSWORD with a long random string to use in the Verify JSON web token connection Action and the custom Post Login Action.
Select Create.
Select Deploy.
Drag and Drop the Render Progressive Profile Form Action to the Login flow.
Select Apply.

Test implementation

Test the implementation by following these steps:

Log in with an existing user whose user_metadata attributes company_name and job_title do not have values.
The custom Post Login Action in the Login flow will render the form and prompt for the information.
Select Auth0 Dashboard > User Management > Users, locate the user and verify that the user_metadata attributes company_name and job_title contain information.

Customize