GDPR: Track consent with your custom UI
In this tutorial we will see how you can use auth0.js or the Auth0 APIs to ask for consent information and save the input at the user's metadata.
We will capture consent information, under various scenarios, and save this at the user's metadata.
All scenarios will save the following properties at the user's metadata:
consentGivenproperty, with true/false values, shows if the user has provided consent (true) or not (false)
consentTimestampproperty, holding the Unix timestamp of when the user provided consent
We will see four different implementations for this:
- one that displays a flag, works for database connections, and uses the auth0.js library to create the user (used by Single-Page Applications)
- one that displays a flag, works for database connections, and uses the Authentication API to create the user (used by Regular Web Apps)
- one that displays a flag, works for social connections, and uses the Management API to update the user's information (used either by SPAs or Regular Web Apps)
Option 1: Use auth0.js
This works only for database connections (we will use Auth0's infrastructure, instead of setting up our own database).
Copy the Client Id and Domain values. You will need them in a while.
Go to Dashboard > Connections > Database and create a new connection. Click Create DB Connection, set a name for the new connection, and click Save. Go to the connection's Applications tab and make sure your newly created application is enabled.
Set the Client ID and Domain values.
Go to Dashboard > Hosted Pages. At the Login tab enable the toggle.
At the Default Templates dropdown make sure that
Custom Login Formis picked. The code is prepopulated for you.
Set the value of the
databaseConnectionvariable to the name of the database connection your app is using.
To add a field for the
consentGivenmetadata, add a checkbox at the form. For our example, we will configure the checkbox as checked by default and disabled so the user cannot uncheck it. You can adjust this according to your business needs.
Edit the signup function to set the metadata. Note that we set the value of the metadata to a string with the value
trueand not to a boolean value, and we are using
toStringto convert the number to a string. This is due to a restriction of the Authentication API Signup endpoint which only accepts strings as values.
To see what the login widget will look like, click the Preview tab.
To test this configuration run the application and go to http://localhost:3000. Sign up with a new user. Then go to Dashboard > Users and search for your new user. Go to User Details and scroll down to the Metadata section. At the user_metadata text area you should see the
consentGivenmetadata set to
Option 2: Use the API (Database)
If you serve your login page from your own server, then you can call the Authentication API Signup endpoint directly once the user signs up.
For the same scenario we have been discussing so far, once you sign up a new user, you can use the following snippet to create the user at Auth0 and set the metadata. Remember to replace the value of the
consentTimestamp request parameter with the timestamp of when the user provided consent.
Note that we set the value of the metadata to a string with the value
true and not to a boolean value due to the API restriction that accepts strings as values, not booleans.
If setting boolean values is a requirement for you, you can use the Management API instead. In this scenario you sign up your user as usual, and then you call the Update User endpoint of the Management API to set the required metadata after the user has been created. For details on how to do that keep reading, the next paragraph uses that endpoint.
If you use social connections, then you cannot use the Authentication API to create the user at Auth0, since that endpoint works only for database connections.
What you have to do instead is let your user sign up with the social provider (which will create a user record at Auth0) and then use the Management API to update the user's information.
Before you call the Management API you need to get a valid token. For details see Get Access Tokens for Production.
Get a token from an SPA
The linked article uses the Client Credentials Flow to get a token, which you cannot use from an app running on the browser. What you can use instead is the Implicit Flow. Set the audience request parameter to
https://YOUR_DOMAIN/api/v2/ and the scope parameter to the scope
create:current_user_metadata. You can use the Access Token you will get at the response to call the Update User endpoint of the Management API.
Once you have a valid token, use the following snippet to update the user's metadata.
Note that in order to make this call you need to know the unique
user_id. You can retrieve this from the
sub claim of the ID Token, if you got one from the response. Alternatively, if all you have is the email, you can retrieve the Id by calling another endpoint of the Management API. For more information see Search Users by Email.
Option 4: Redirect to another page
If you want to display more information to your user, then upon signup you can redirect to another page where you ask for consent and any additional info, and then redirect back to finish the authentication transaction. This can be done with redirect rules. That same rule can be used to save the consent information at the user's metadata so you can track this information and not ask for consent upon next login.
For simplicity, we will use this sample consent form. This is a form we have hosted for you using a webtask, but later on we will see how to host your own version of this form (with your own URL). You can find the webtask's code at Auth0 Redirect Rules repo.
First, we will add the rule. Go to Dashboard > Rules and click Create Rule. At the Rules Templates select empty rule. Change the default rule's name (
empty rule) to something descriptive, for example
Redirect to consent form.
CONSENT_FORM_URLURL (we will configure this at the next step). Once the user hits Submit at the consent form, the rule runs again as part of the callback. At this point we persist the information at the
Go back to Dashboard > Rules, scroll down, and under Settings, create a Key/Value pair as follows:
If you want to work with your own implementation of the consent form webtask, you can host your own version of the webtask.js script. For instructions see Consent Form Setup.
To learn more about redirect rules, see Redirect Users from Rules.
To test this configuration:
- Run the application and go to http://localhost:3000
- Sign up with a new user. You will be navigated to the consent form.
- Check the I agree flag and click Submit
- Go to Dashboard > Users and search for your new user
- Go to User Details and scroll down to the Metadata section.
- At the user_metadata text area you should see the
consentGivenmetadata set to
true, and the
consentTimestampset to the Unix timestamp of the moment the user consented
That's it, you are done!