User Onboarding Made Easy

In this lab, you will:

• Configure additional signup steps using Forms.

• Integrate these additional steps into the Auth0 signup and authentication processes.

• Test the additional steps when a new user signs up.

Lab Setup

To use this lab, you need an Auth0 account and a basic understanding of Forms.

Create an Auth0 Account

If you already have an Auth0 account, you can log in to your tenant and continue to the next step.

Otherwise, sign up for a free Auth0 account.

During the sign-up process, you create something called an Auth0 Tenant, representing the product or service to which you are adding authentication.

Forms

Forms is a new feature of the Auth0 identity platform that allows you to use a visual editor to add custom steps and business logic to your authentication flow.

You can now create customizable Forms to gather user information, which you can trigger conditionally as your users advance through the signup and authentication flow you've designed for your app.

Please get acquainted with Forms by reading the documentation.

Create a Form from Scratch

Ensure that you are logged in to the Auth0 Dashboard and follow these steps to create a Form:

• Head to the Auth0 Dashboard.

• Click the "Actions" item on the left-hand menu.

• Click the "Forms" option to open the Form editor in a new tab.

• Click the "Create Form" button and select the "Start from scratch" option.

By default, a new Form using the "Start from scratch" option contains a Start node, a Step node, and an Ending screen node, as shown below:

The Form also has "Blank form" as its default name, which is located on the left-hand side of the title bar. Update that name to something meaningful by clicking on it and entering the following value:

User onboarding Form

Click out of the text field to update it.

Now that your Form has a proper name, let's get you started to build it up!

Configure the Step Node

Notice that your default Step node has a label just below it: "New step". That is the Form node's alias.

You can create Forms that are as simple or as complex as you need them to be. However, regardless of the number of nodes that you have on the Form board, it's a good practice to give each Form node a meaningful alias to help you and others identify them in the Form board, fostering collaboration and self-documentation.

Name your Form node

You can give any Form node an alias by clicking on its title bar, which opens a settings modal that includes an "Alias" field. Go ahead and do that for your default Step node and use the following value as its alias:

Common Data

Click the "Save" button to close the modal. Let's call this Step node "Common Data" as it will collect data that applies to any user. In a later section, you'll learn how to collect different types of data based on how your users interact with the Form.

With the Step node properly aliased, let's get started with adding the components to the Step node that actually collect such data. You'll use block components to enhance the user interface of the Form, such as adding a title or navigation buttons, and field components to collect the user data.

On the left hand, there's a sidebar that gives you different options to customize your Form. The first button has a grid-like icon. That's the "Components" button that opens the Form components palette. Click it.

Use a block component to add a form title

Recall that the Step node is the graphical interface visible to users. Let's use a Block component to add a title to the Form.

Locate the "Blocks" section in the components palette. Then, drag and drop a "Rich Text" block component into the "Common Data" Step node.

The "Block settings" modal comes up, which allows you to configure the design and content of this component.

In the "Rich text" textarea, enter the following message:

Tell us more about yourself

Next, click the "H2" button present at the bottom of the text area to make it a headline.

Finally, click the "Save" button.

Your "Common Data" Step node should now show the skeleton of a form component with a title and a "Continue" button.

Use field components to gather user information

Now, you'll add Field components to the Step node to collect the user's full name and ask them a question.

Gather input data

Locate the "Fields" section in the components palette. Then, drag and drop a "Text" field component into the "Common Data" Step node, right below the form title (the Rich Text block component).

The "Field settings" modal comes up, which allows you to configure the design and content of this component. Fill the setting values as follows:

full_name

Full name

Enter your full name

Check the following boxes:

• Label: When checked, the Form shows the label you created for this text field.
• Required: When checked, the Form requires the user to complete this text field before they can submit the Form.

Then, click the "Save" button.

Your Step node now should show the skeleton of a form component with a title, a text field, and a "Continue" button.

Ask a question

Head back to the "Fields" section in the components palette. Then, drag and drop a "Boolean" field component into the "Common Data" Step node, right below the "Full name" text field.

The "Field settings" modal comes up again. Fill the setting values as follows:

is_student

Are you a student?

Ensure that the "Label" and "Required" checkboxes are marked.

The "False label" represents the label that the false value should have in the Form, while the "True label" represents the label that the true value should have.

Click the "Save" button to keep going.

Accessing form data

So far, you have set up two Field components that collect user data. Where does that data go?

Every field component you configured has an id value, which becomes its property key in a fields object that your Form is storing on its context. Recall that you can use Flow nodes to use server-side business logic to perform actions on your form data. You'll be able to reference the fields data using the following template pattern: {{fields.<id>}}. You'll use that template pattern to compose JSON payloads that you can send to the server side. You'll see this in action in the next sections of this lab.

Create and Configure a Router Node

The bottom of the board offers a toolbar that you can use to quickly add nodes to your Form.

Click the "Router" button in that toolbar to add a Router node.

If you cannot see your new Router node, it may be hiding behind the existing Step node. Try moving the "Common Data" Step node until you find it.

By default, a Router node loads in your board having no connection to other nodes. Here, you'd like to position the Router node between your data-collection Step node and the Ending Screen node.

To do so, delete the connector line between those two nodes as follows:

• Click on the connector line.

• Click the button that comes up with the trash can icon.

Now, drag the Router node you just added between the Step node and the Ending screen node.

Then, click the connector dot on the right side of the Step node and drag your cursor until you reach the connector dot on the left side of the Router node. Do the same to connect the Router node with the Ending screen node.

The Router node is now connected to the logic flow of this form. Now, let's add some conditions or rules to the Router node that will allow you to take the user to a different Step node based on the value of the Boolean field component of the data-collection Step Node.

Click on the Router node to open the "Router settings" modal.

Start by giving the following "Alias" value to the Router node:

User Type Filter

You'll see a "Default case" rule listed in the modal. All router nodes must have a default case to ensure that there's always a next node to transition the user into as they go through the Form. The Form logic flow cannot stop at a Router node.

Click the "New Rule" button to add a new case.

Click on the new "Rule 1" entry to bring up a modal where you can define the logic of your conditional rule. To start, give the rule the following "Alias" value:

Student filter

The three fields below represent the three parts of a comparison statement: A [comparison operator] B.

You can compare any of the variable that you have defined in the Form thus far by clicking on the + button of the comparison fields.

For the first field, click that button and select the is_student variable.

For the second field, ensure that "is equal to" is selected.

For the third field, enter the following value that corresponds to the value the is_student Boolean field has when the selection is Yes:

true

You could create rules as complex as you'd like by specifying any number of comparison statements using different comparison operations and conditional operators that are available via the Or and And buttons.

For now, click the "Save" button to proceed.

You are back to the "Router settings" modal. Click the "Save" button once again to commit the changes to your Router node.

You'll notice that the Router node has a yellow notification icon on its title bar. You can also see the same notification on the top bar of the Forms board. That's a warning notification, which would indicate that something has not been configured correctly in the Form. If you hover over it, you'll find the following message:

Some rules are not linked to a node

That's right! The Default Case for your Router node is linking to the Ending screen node but the Router rule you just created is not linking to anything. Let's solve that.

Connect Router node rules to Step nodes

Let's expand this Form by connecting each case of the Router node with a Step node. If the user is a student, you'll collect the name of their college or university. If the user is not a student, you'll collect their job title and company name.

To do so, you'll need to connect each Router node case to a new Step node. Let's get started with that.

Drag the Ending screen node as far as possible from the Router node to create space to insert new Step nodes between them. Click the connector line between these nodes and delete it.

Create a Step node to collect student information

Now, click the "Step" button in the bottom toolbar to insert a Step node.

Drag the connector dot on the right side of the Router node that aligns with the "Student filter" case and connect it to the connector dot on the left side of the new Step node.

Notice how the warning on the Router node is not gone and now you also have a warning on the new Step node. Leave it as such for now.

Give this new Step node an alias by clicking on its title bar and entering the following value in the "Step settings" modal:

Student Data

Click the "Save" button.

The Step node alias shows up right below the node on the board. It's a helpful way to differentiate each node and makes it easy to communicate which node you are referring to.

We'll refer to this Step node as the "Student Data" Step node from now on to make instructions clear.

Let's ensure the different Step nodes feel part of the same Form. For that, add to the "Student Data" Step node a "Rich Text" block component to create the same title as on the previous node.

Configure the "Block settings" of that block component as you did for the one in the previous Step node. In the "Rich text" textarea, enter the following message:

Tell us more about yourself

Then, click the "H2" button to make it a headline.

Finally, click the "Save" button.

Locate the "Fields" section in the components palette. Then, drag and drop two "Text" field components into the "Student Data" Step node, right below the Form title. Fill the setting values for each text field as follows:

Major text field

college_major

What's your major?

Check the following boxes: Label: and Required.

Click the "Save" button.

College text field

college_name

What college are you attending?

Check the following boxes: Label: and Required.

Click the "Save" button.

Finally, let's give users the ability to go back to the previous Step node in case entered incorrect information or made a wrong selection.

Locate the "Blocks" section in the component palette and drag a "Previous button" block component into the "Student Data" Step node just below the "Continue" button.

Click the "Save" button in the "Block settings" modal to accept the default values.

Create a Step node to collect employee information

Let's create the Step node for the default case: when is_student is not true. That is, the boolean is false.

Instead of creating the Step node from scratch, let's clone the "Student Data" Step node and modify its text fields to satisfy the employee data collection use case.

Click the "Clone" button on the title bar of the "Student Data" Step node, which is located to the left of the "Delete" button, which has a trash can icon.

The "Settings" modal for the "Student Data" Step node may come up. If that's the case, collapse it to close it. Instead, you'd want to click on the title bar of the Step node clone to give it a meaningful alias:

Employee Data

Click the "Save" button.

We'll refer to this new Step node as the "Employee Data" Step node from now on.

Place that "Employee Data" Step node below the "Student Data" Step node.

Drag the connector dot on the right side of the Router node that aligns with the "Default Case" and connect it to the connector dot on the left side of the "Employee Data" Step node.

Notice how the warning on the Router node disappeared. You still have the warnings on the other not connected nodes.

You'll keep the same Rich Text field component from the cloned Step node.

Click on each Text field component from the clone to update their "Field settings" values as follows:

Job title text field

company_job_title

What's your job title?

Check the following boxes: Label: and Required.

Click the "Save" button.

Company text field

company_name

What company do you work for?

Check the following boxes: Label: and Required.

Click the "Save" button.

Click also the Publish button to save the changes to your Form so far.

Link Step and Route nodes with Flow nodes

So far, you have created a flow that collects personal data from a user using Step nodes. You learned how to use a Router node to identify which of your users are students and which are employees. Each Router node case links to a Step node that collects different types of information. However, the Step nodes that follow the Router node are not linked to any other nodes, which would break the logic flow of your Form.

You now have the user's full name and information on where they work or where they study. Now, you need to store that information somewhere! Auth0 provides a comprehensive system for storing metadata in the Auth0 user profile. You can quickly and easily store user-specific information, such as preferences, that do not impact the application's core functionality in the user_metadata object available to each user of your Auth0 tenant. You can use a Flow node to handle that action on the server side. You'll learn how to do so in the next section.

Create a Flow to Update User Metadata

Flows are the visual representation of the server-side logic that occurs when a Form is processed. Flows consist of a series of actions that you can add and configure as necessary.

Flows can be added to your Form in different scenarios, such as between a multi-step Form, before Form submission, and after Form submission:

• Between a multi-step Form: run between Form steps when the user clicks on a continue button.

• Before Form submission: run after a user submits a Form, but before the user receives a failure or success response.

• After Form submission: run after the user successfully submits a Form.

In this lab, you'll create a Flow that uses the Auth0 Update User Action to update the user_metadata and add it to your Form. This Flow will run after the Form submission.

The Auth0 Update User Action under the hood will update a user calling the Auth0 Management API. For this API call to work, the Auth0 Update User Action will need to get and provide an access token with the right scopes to update the user_metadata. So, how do we get and provide an access token for the Auth0 Update User Action to work as expected? The answer is by adding a connection with the credentials for a Machine-to-Machine application that is authorized to get access tokens for the Auth0 Management API.

So, let's break down those steps as follows:

1. Create a Machine-to-Machine Application to get access tokens for the Auth0 Management API with the right scopes to update the user_metadata.

2. Add a connection from the vault page with the M2M application's credentials.

3. Define the server-side logic to process the Form using a Flow.

4. Add a Flow Node to the Form.

Create a Machine-to-Machine (M2M) Application to get access tokens for the Auth0 Management API

The Auth0 Update User Action that updates the user_metadata will need to provide an access token for authorization purposes to the Auth0 Management API. This token is a JSON Web Token (JWT) containing specific grant permissions, also known as scopes.

For this, you'll start by creating an M2M application authorized to call the Auth0 Management API in the Auth0 Dashboard and get three configuration values: the Auth0 Domain, the Auth0 Client ID, and the Auth0 Client Secret.

Get the Auth0 Domain, Client ID, and Client Secret

• Open the Applications section of the Auth0 Dashboard.

• Click on the Create Application button and fill out the form with the following values:

Update User_metadata

• Select Machine to Machine Applications as the application type:

Application Type

Machine to Machine Applications

• Click on the Create button.

• In the Authorize Machine to Machine Application modal, select the Auth0 Management API.

• Select the following set of permissions (or scopes) to grant the M2M app access to update the Auth0 User Metadata:

  • update:users
  • update:users_app_metadata

• Click Authorize:

An Auth0 Application page loads up.

As such, click on the "Settings" tab of your Auth0 Application page and locate the "Basic Information" section.

Don't close this page, you'll use the Domain, Client ID, and Client Secret values in the next section to create a connection for the M2M application.

Add a connection from the vault page with the M2M application's credentials

The Vault is a set-and-forget tool to store and organize all your connections in a secure way, so you don't have to place your credentials every time when configuring a new Form and Action. You can also reuse the same connection for multiple Forms and Flows.

The connection will generate an access token with an expiration time and a refresh token for the M2M application. The connection stores both tokens and generates a new access token before it expires.

Follow these steps to create a connection for the M2M Application:

• Head back to the Auth0 Dashboard.

• Navigate to Actions > Forms to open the Forms page.

• In the Forms page, click on the {tenantName} dropdown at the top left corner and select the Vault option.

• Click on the Add Vault Connection button.

• Select the Auth0 option and click on Continue.

• Enter a name for the connection:

Update User_metadata M2M

• Click the Continue button.

• Fill out the Add Vault Connection form with the Domain, Client ID, and Client Secret of the M2M application you created in the previous section.

• Click on the Add Vault Connection button.

Define the server-side logic to process the Form using a Flow

Now that you have set up the M2M application and created a connection for it, you're ready to define the server-side logic to process your Form using Actions within a Flow.

Let's start by creating a Flow:

• From the Auth0 Dashboard. Navigate to Actions > Forms to open the Forms page.

• On the Forms page, click on the Flows tab at the top of the navigation bar.

• Click the Create Flow button.

The Flow also has "New flow" as its default name, which is located on the left-hand side of the title bar. Update that name to something meaningful by clicking on it and entering the following value:

Update user_metadata

Then, you'll need to add actions to define the server-side logic to process your Form data.

First, you'll add an If/then condition action that checks the {{fields.is_student}} flag value to conditionally update the information for students or employees:

• Below the Start Action, click the + icon to add an Action to your Flow.

• Select the If/then condition option from the List of actions panel on the right-hand side.

• Fill the If/then condition setting values as follows:

is_student_clause

Is a student?

For the Condition section, copy and paste the following variable for the first field.

{{fields.is_student}}

For the second field, ensure that "is equal to" is selected.

For the third field, enter the following value to be compared to the value of the is_student Boolean field:

true

• Click the Save button.

Now, we need to add an action that updates the user_metadata whether the is_student Boolean field is true or false. If the condition is true, it means it's a student, so you'll use the information from the Common Data and Student Data Step nodes to update the user_metadata with an Auth0 Update User Action. Otherwise, it means it is an employee, so you'll use the information from the Common Data and Employee Data Step nodes.

• Below the TRUE label, click the + icon to add an Action to update the user_metadata.

• Select the Auth0 Update User option from the List of actions panel on the right-hand side.

• Complete the fields below for the Auth0 Update user action as follows:

Update Student Data

For the Vault Connection field, select the connection "Update User_metadata M2M" you created in the previous section with the M2M Application's credentials.

For the User ID field, copy the following:

{{context.user.user_id}}

For the Body field, copy and paste the payload with the Auth0 user properties that you want to add or replace. Learn more about the payload that you can pass here.

{
  "user_metadata": {
    "full_name": "{{fields.full_name}}",
    "college_major": "{{fields.college_major}}",
    "college_name": "{{fields.college_name}}"
  }
}

• Click on the Save button to continue.

You'll follow similar steps to update the user_metadata when the user is an employee:

• Below the FALSE label, click the + icon to add an Action to update the user_metadata.

• Select the Auth0 Update User option from the List of actions panel on the right-hand side.

• Complete the fields below for the Auth0 Update user action as follows:

Update Employee Data

For the Vault Connection field, select the connection "Update User_metadata M2M" you created in the previous section with the M2M Application's credentials.

For the User ID field, copy the following:

{{context.user.user_id}}

For the Body field, copy and paste the payload with the Auth0 user properties that you want to add or replace. Learn more about the payload that you can pass here.

{
  "user_metadata": {
    "full_name": "{{fields.full_name}}",
    "company_job_title": "{{fields.company_job_title}}",
    "company_name": "{{fields.company_name}}"
  }
}

• Click on the Save button to continue.

• Click on Publish to save the changes to your Flow.

You've created a Flow to handle the server-side logic of your Form. In the next section, you'll add it to your Form.

Add a Flow Node to the Form

Finally, you'll add a Flow node and connect it to the "Student Data" and "Employee Data" nodes and the Ending screen node to update the user_metadata and resume the authentication flow by following these steps:

• Head to the Auth0 Dashboard.

• Click the "Actions" tab on the left-hand menu.

• Click the "Forms" option to open the Forms page in a new tab.

• Select the Form you created earlier.

• Click the Flow button located at the bottom of the Form editor to create a Flow node.

• Link the Flow node to the right-side connector dots of the Student Data and Employee Data step nodes and the left-side connector dot of the Ending screen node as pictured below:

• Click the Flow node to configure it.

• Under the Flow option, select the Flow you created in the previous section: "Update user_metadata"

• Click the Publish button to save the latest changes for the Form.

Now you have enabled your Form to gather user data and store it in the user_metadata object. In the next steps, you'll learn how to integrate the Form you created into the Auth0 authentication process.

Retrieve the Code to Render Your Form

Before integrating the Form you created into the Auth0 authentication process, you need to learn how to render it via code. You can retrieve the basic code you need by following these steps:

• From the Form editor, click the <> Render tab. You will see a code block that implements a Post Login Action. You can see the ID that identifies the current Form and how it is rendered through the api.prompt.render() method.

• Click the Copy button.

Let's see in the next section how you can use the code you just copied to implement a Post Login Action.

Create a Custom Post Login Action

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

• Navigate to Auth0 Dashboard > Actions > Flows > Login.

• Under the Add Action panel on the right-hand side, select the Custom tab.

• Click the + icon and select the Build from scratch option.

• Fill out the form as follows:

  • Name: Enter Render Additional Signup Form.
  • Trigger: Select Login / Post Login.
  • Runtime: Select the recommended version.

• Click the Create button.

To configure the custom Action:

• Delete the existing code from the Code editor.

• Paste the code you copied in the previous section into the code editor.

• Edit the code to define the conditional logic that will render the Form, as shown below:

/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  const FORM_ID = 'REPLACE_WITH_YOUR_FORM_ID';

  if (
    !event.user.user_metadata.full_name &&
    !event.user.user_metadata.job_title
  ) {
    api.prompt.render(FORM_ID);
  }
}

exports.onContinuePostLogin = async (event, api) => { }

• Click the Deploy button.

• Click the Back to flow link at the top-left side of the editor.

• Under the Add Action panel on the right-hand side, select the Custom tab.

• Drag and Drop the Render Additional Signup Form Action to the Login flow.

• Click the Apply button.

Your Form is ready to gather data from users when they log in.

Test the Form

To test the Form you implemented throughout this lab, you need to:

• Sign up a new user or log in with an existing user to an application that uses the current Auth0 tenant. The custom Post Login Action in the Login flow will render the Form and prompt for the information.

• After logging in, select Auth0 Dashboard > User Management > Users, locate the user you used, and verify that its attributes full_name, job_title, and the others contain the information from the additional signup step.

Alternatively, you can test the implementation from within the Auth0 dashboard as follows:

• Select Authentication from the left-hand menu, then select one of the connection types shown below it.

• Locate the connection you want to test and select Try from its More Options menu (...).

• Sign up a new user or enter the credentials to authenticate as an existing user. If the credentials you provide are correct, you will see the Form you implemented in action:

• After logging in, select Auth0 Dashboard > User Management > Users, locate the user you used, and verify that its attributes full_name, job_title, and the others contain the information from the additional signup step.

Recap

This lab showed you how to add additional steps to the login and signup processes to complete the user profile using Forms.

You started by reviewing the basic concepts of Forms. Then, you created your first Form from scratch and learned how to add fields and blocks to arrange the UI.

You added Router and Step nodes to gather different user data based on their input.

You created a Flow to update the user metadata and attached it to a Flow node to complete the data-gathering process via Forms.

Finally, you crafted the code to render the Form you just created, put it in a Post Login Action, and tested it by logging in as an existing user or signing up a new user.

Now you have the foundations to build Forms to customize your users' signup and login experience.