Add a Custom Policy Acceptance Form to Login

Sometimes, service policies change; Typically if the Terms of Services are updated. When organizations update their policies, it's crucial that their users are informed and agree to those changes. Integrating those consent processes during login can be daunting, especially if you want to avoid redirects or sending emails to your users.

Forms is a feature that allows you to create customizable forms that can extend your identity flows with additional steps and business logic. Using Forms will enable you to implement use cases such as custom policy acceptance. For instance, if you need to update your policies, you can define logic to check if users have accepted the latest policies and display a custom form to users requiring acceptance based on that. Tl;dr: Forms empowers you to craft custom privacy policy flows and securely store user consent in the app_metadata object.

This lab will walk you through creating an Update Policy form leveraging Forms and seamlessly integrating it into a Post Login Action. You will learn this in detail:

• Get to know Forms' UI and nodes
• Use steps, flows, and components to create an acceptance process, including the new policy and an input field to accept it
• Update the user's metadata to signalize consent
• Render the new forms by using Auth0 Actions

Prerequisites

Ensure you have the following in place:

• A Machine-to-Machine Application (“M2M” in short) with these scopes:
  • read:users
  • update:users
  • create:users
  • read:users_app_metadata
  • update:users_app_metadata
  • create:users_app_metadata
• A Vault connection is set up with your M2M application credentials.

Create Your Form

To begin, navigate to the Auth0 Dashboard > Actions and to Forms. Then, click Create Form and select Start from scratch to begin the form creation process. You'll be navigated to this editor.

In the center of your editor is your canvas, representing your form. It's made of so-called nodes:

• The start node for managing hidden fields
• step nodes for visible user data input fields
• flow nodes for defining custom logic and processing for server-side actions
• router nodes for setting up conditional logic based on variables
• The ending screen node for resuming the authentication flow post-submission
• ...and components

Build Your Form with the Updated, Custom Policy in It

Now, let's get to the central part of our lab, the actual form containing our new, updated policy. To build this part, you need to focus on the step node you see in the middle of the canvas. Such a step node is a visual representation of the form. They can contain any number of components, such as fields, blocks, and widgets where the user can fill in their data - and adding those is exactly what we'll do next.

For a name, you can choose any name you want, preferably descriptive. For example, I'll go with this:

Custom Policy Check

Then, we can directly begin by filling our form with life... well, the custom policy. We will choose components, which are located in the left sidebar first item. To set up your custom policy, you must add a Rich text field and a Legal field to your step.

First, find the Rich Text component; you can drag the Rich Text field into the step node:

After dropping it onto the step node, add your privacy policy update description as text. You can format it, too. In the next step of the process, you will be required to locate the Legal field and drag it into the designated step node. Once you have added the Legal field, set its ID to privacy_policies and indicate it is required:

privacy_policies

Additionally, you might want to input the text below or any other suitable text to capture the user's acceptance of the policy:

I agree to the Privacy Policy

This way, your form will look like this:

Last but not least, remember to hit Publish in the upper right corner of the page! 🚀

Add a Flow Node

You must add a flow node to handle your user's app_metadata update and resume the authentication process afterward. What's a "flow" in Forms, you might wonder? 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.

Let's start by adding a flow node to the current form. Select Flow at the bottom of the Form editor. Then, remove the link between the Step and Ending screen nodes.

You should define an alias to keep your form more comprehensible.

Set custom_policies

Next, connect your Flow node to both the Step and Ending Screen nodes as seen below:

Lastly, remember to click Save and then Publish to publish your changes. 👍

Associate the Flow Node to the Flow Itself

Now, let's associate the Update user flow node to your flow. First, click the Flow "Update app_metadata", then Edit flow to open the Flow editor in a new tab.

Below the Start Action, select the + icon to add an Update user action. A list of actions will open, it's most convenient to search for "Update user" in the search field or look for the Auth0 category. In the form to configure this "Update User" action, choose your vault connection (this is the M2M connection I mentioned in the prerequisites part of this lab) from the dropdown and set User ID to {{context.user.user_id}}.

{{context.user.user_id}}

For the body, use the following code to update the app_metadata with the are_privacy_policies_accepted and privacy_policies_timestamp properties:

{
  "app_metadata": {
    "are_privacy_policies_accepted": true,
    "privacy_policies_timestamp": "{{ functions.toTimestamp() }}"
  }
}

After this, there's nothing else to do but save your work to publish. ✅

Rendering the Form via Post Login Action

To actually display your form, you'll need to access the render code and use it inside an Auth0 Action. In the Form editor, you can find the Render option. Click on it and then copy the code provided.

Proceed by clicking Post Login Action which will be triggered after logging in. You'll be forwarded to Auth0 Action's area, where you can create a new Action by clicking the corresponding Create Action button. Select Build from scratch to start a new Action. I called my action "Render Custom Policy" in this example:

Render Custom Policy

As soon as you are in Auth0 Action's very own code editor, paste the code from the clipboard:

You can modify the code to define the conditional logic that will render the form. Here's an example:

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

  // The following line will contain our modification
  if (event.user.app_metadata.are_privacy_policies_accepted !== true) {
    api.prompt.render(FORM_ID);
  }
}

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

After this modification, you only need to deploy your changes by clicking Apply and add your new Action to the login flow by dragging the newly created Action into the flow.

Test Your Implementation

Time to see your hard work in action. Last, but not least, testing your implementation is a crucial step to get your custom policy form into production while ensuring there are no errors and all requirements are fulfilled.

First, open your application and log in with a user whose app_metadata lacks a "are_privacy_policies_accepted" value. This way, you can watch as your post-login Action displays the form. To proceed, accept the new policy as a real user would most-likely do.

After showing consent by checking the checkbox and proceeding with the login, check the user's app metadata in the Auth0 Dashboard. You should see a "are_privacy_policies_accepted" attribute set to true, along with a timestamp.

Recap

Congratulations! You have successfully established an updated policy form using Forms! 🎉 You could efficiently use Forms to collect and store user consent for privacy policy updates, improving your app's compliance and user experience. In detail, you've learned how to:

• Set up form steps to create and display the custom policy and capture acceptance
• Modify the authentication flow to update the user's metadata and resume authentication after the nodes were displayed or executed
• Render the form by using Auth0 Actions and react to the user's metadata
• Use your newly created form by an Auth0 Action in the post-login flow