Auth0 Forms – Adding Policy Versioning

Auth0 Forms is a tool designed to allow identity flows to be extended with customisable forms and logic, allowing use cases like progressive profiling, policy acceptance, payment collection and more within the hosted login flows you’ve come to know and love from Auth0. For more detail on forms please refer to my earlier post Auth0 Forms – Managing Privacy Policy Acceptance. In this post I will expand upon the work done there to add versioning of the policy to our form.

In the original post the setup was fairly basic. A user has either accepted the policy form or they have not. In this post we update this to add versioning to the form as well as pulling information from an external system. The steps we go through in this post are as follows.

1. Add a flow to retrieve a new policy version and text from external system.
2. Update the policies step to incorporate the policy data.
3. Update the user metadata with the policy version.
4. Add a Router to check the policy version and prompt if required.
5. Alter the user app_metadata update to incorporate the new information.
6. Check that everything is working.

Use a Flow to grab data from an external system

Note: I have used mock.io to host my JSON file but it could be stored anywhere. The sample file I used is as follows.

{
  "policy_version": 1.1,
  "policy_introduction": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
  "policy_link": "https://example.com/policy/v1"
}

1. Return to the Form created in the previous blog post and add a Flow by clicking Flow at the bottom of the edit dialog.
2. A new flow will be added to the canvas and a Flow settings tab opened. Click Create New Flow and give the flow a name as shown below.

2. Click Edit Flow once it has been created and a new window will open with a blank flow.
3. Click the + underneath the start node and HTTP request. This will be used to retrieve a JSON file from an external system that contains the policy version, introduction and link. Paste in the URL of your JSON file, add any headers/auth required and click Save down the bottom.

4. Now, in order to make the next step simpler hit Publish and then Test. This will populate data to make the next step simpler. You should see a successful execution and when you click View Details then select the HTTP Request from the action list and click on the Output tab you should see some header request details and the body of the JSON file retrieved successfully.

5. Switch back to the Edit tab and click + underneath the HTTP Request node and select Store share variable. Then click the plus to add the variable as shown below.

6. On the fields that pops up select Execution and type policy into the search box.

7. Click on body.policy_version and then put the name of the data field as policy_version. Repeat these steps for the policy_introduction and policy_link. You should end up with something like the below.

8. Before you move onto the next step save the node, reopen it and copy the three variable references by clicking the Copy Expression button as shown below and saving the values.

Update the policies step to incorporate data

1. Switch back to the form and select the New policies update step, highlighting the Rich Text block. Then copy and delete everything in the block below the header. Now, paste in the values copied for the policy version and introduction from the previous step. It should look like the blow.

2. Also, select the Legal block and update the policy link.

3. Now is a good time to test that what we have done so far is working. In order to launch the form when you log in you’ll need to use a new user comment out the check in the action created in the last blog like below

4. When you do this and login you should see the below.

Update the user metadata with the policy version.

In order to ensure that the correct version numbers are written to the user’s metadata we need to update the flow that performs this update. Switch to the Flows editor and select the applicable update flow. Select the Update user step and add the policy version number to the metadata like below.

Check Policy Versions with a Router

Now that we’re importing the policy from our source JSON file and updating the user metadata we’re going to add a router to only prompt the user if they need to accept the new policy version.

1. On the Form click Router at the bottom to add a new router node. On the popup that open click Rule 1 under the rules section and change the alias to Check Policy Version. In the top comparison box enter the new policy version reference we used above {{vars.policy_version}}, set the comparison to is different to and the bottom comparison box to {{context.user.app_metadata.privacy_policies_version}}. This takes advantage of the fact that the user metadata is always shared with the form via the context object.

2. Save this and then also update the alias for the router object and save again. Next, re-wire the connections so that after the router is after the Retrieve Policy flow node. Link the Check Policy Version node with the New Policies Update step and the Default Case node is linked directly to Ending Screen/Resume authentication flow step.

Testing it out

Now it is time to test it all out. Signup with new test user or navigate to User Management -> Users and select your test user. Scroll down to app metadata and if privacy_policies_version is present change the value to 0 and click save. You can now proceed to login with that user and you should get presented with the policy form as shown below.

Logout and log in again as the same user as above. You should get briefly redirected to the form and then logged in without needing to view or select the dialog.

Notes

Here we are pulling a policy version and file from within the Form, in reality it would make more sense to check the version from the action and not launch the form at all if the user had already accepted the current version. This was done simply because I wanted to play around with more complicated actions within Forms.