Auth0

The Auth0 integration with DataGuard CPM allows users to manage their consent during sign up or sign in, utilizing our powerful progressive consent feature. This ensures that users are only shown consent options they haven't previously encountered. The integration manages citizen creation and authentication, and provides the option to use a pre-built consent widget page or host the widget on your own page.

Prerequisites

Before getting started, make sure you have access to the following:

1. The DataGuard CPM Platform.
2. An Auth0 account with administrative privileges.

If you don't have access to the DataGuard CPM Platform, please contact us.

Auth0 Setup

Step 1: Navigate to the Auth0 Marketplace

1. Log in to your Auth0 dashboard.
2. In the sidebar menu, click on Marketplace.
3. In the Marketplace, search for DataGuard under the Consent Management section.
4. Select the DataGuard integration.

Step 2: Configure the Integration

Once you have selected the DataGuard integration, you'll need to configure the following fields:

• Auth Host: The URL used to authenticate against your DataGuard API token. This will be different depending on your DataGuard environment:

• API Host: The DataGuard API host URL. This will be different depending on your DataGuard environment:

• Audience: The name of the DataGuard API being called. This will be different depending on your DataGuard environment:

• Client ID: The DataGuard Client ID issued to you. This can be found on the Credentials page in the DataGuard CPM UI.
• Application ID: The DataGuard Application ID issued to you. This can be found on the Credentials page in the DataGuard CPM UI.
• Redirect URL: The URL of the page containing the Progressive Consent Widget. You can either use our pre-built page or specify a URL to your own hosted page. See the "Progressive Widget Page" section below for more information.
• Identifier Property Path: A path to the property used as the user ID. By default, the user_id is used, but you may prefer to use a custom internal ID stored in the app_metadata.
• Client Secret: The DataGuard Client Secret issued to you, found on the Credentials page in the DataGuard CPM UI.

Step 3: Complete the Setup

Once the fields have been populated with the correct values, proceed with the following steps:

1. Click Create to add the integration to your Auth0 Library.
2. A pop-up will appear. Click Add to flow.
3. Drag the DataGuard Action into the desired location within your flow (typically during sign up or sign in).
4. Click Apply Changes to save your configuration.

Progressive Widget Page

The Redirect URL must point to a page containing the DataGuard consent widget. This URL is where users will be redirected during sign-up or sign-in to manage their preferences. Typically, this will be a Progressive Widget configured to display consent purposes the user hasn't interacted with before or purposes that are expiring soon.

Hosted Widget Option

You can use our hosted widget page, which is pre-configured and works out of the box. Set the Redirect URL to the following:

https://widgets.consentric.io/auth0-widget?templateId=<template-id>&ruleId=<rule-id>&returnUrl=<base64-encoded-url>

Make sure the URL host matches the environment you're using:

• Replace <template-id> with the Template Id. Refer to the Templates page for instructions on how to create your template.
• Replace <rule-id> with the Rule Id. Refer to the Rule Sets page for setting up rules.
• Replace <base64-encoded-url> with a base64-encoded URL to return the user to after they submit the widget. This should be the normal return URL for your Auth0 tenant.

Custom Widget Page

Alternatively, you can create your own custom page to host the widget. The custom page must do the following:

1. Extract the token from the URL: The token will be provided as a query string parameter (token) and should be passed to the widget.
2. Redirect back to Auth0 on submission: The widget should redirect the user back to Auth0 upon successful submission using the onSuccess event.
3. Handle empty widget loads: If there is nothing to load in the widget (for example, if there are no new consent purposes), the page should redirect back to Auth0 using the onEmptyLoad event.

Here’s an example of how to build your custom page:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8"/>
    <title>Consent and Preferences</title>
</head>

<body>
<div id="core-widget"></div>

<script src="https://scripts.consentric.io/capture-point.min.js" async=""></script>
<script>
    window.addEventListener('load', () => {
        const urlParams = new URLSearchParams(window.location.search);

        const returnToAuth0 = () => {
            window.location.href = '<auth0-url>/continue?state=' + urlParams.get('state');
        }
        
        StatefulWidget.load({
            id: 'core-widget',
            templateId: '<template-id>',
            ruleId: '<rule-id>',
            token: urlParams.get('token'),
            display: {
                location: 'centre',
                closeOnSubmit: false,
                displayCancelButtons: false,
            },
            events: {
                onSuccess: returnToAuth0,
                onEmptyLoad: returnToAuth0,
            }
        });
    });
</script>
</body>
</html>

Make sure the script URL matches the environment you're using:

• Replace <template-id> with the Template Id. Refer to the Templates page for instructions on how to create your template.
• Replace <rule-id> with the Rule Id. Refer to the Rule Sets page for setting up rules.
• Replace <auth0-url> with the URL to return the user to after they submit the widget. This should be the normal return URL for your Auth0 tenant.

Conclusion

Your Auth0 integration with DataGuard CPM is now complete. Users will be able to manage their consent during sign-up or sign-in, and you can choose to either use our hosted widget page or create a custom page to fully control the user experience. The progressive consent feature ensures that users are only shown relevant consent options based on their previous interactions.