Integration of a consent model

The consent templates can be integrated as iframe into any HTML site, so as to achieve seamless integration.

snippets are deliberately kept as simple as possible (no error checking, session management, etc. ).

Contents of this documentation:

1 Kinematics
2 Obtaining an authentication token
3 Obtaining a consent form URL
4 Presentation of the form
5 Integration with iframeResizer
6 Triggering a reload of the parent frame
7 Source code
8 References
9 To find out more

Kinematics

Once the integration has been carried out, the kinematics are as follows:

obtaining an authentication token;
obtaining a form URL;
presentation of the form;
sending the form, after which:
- optional: display of the consent receipt;
- optional: sending a message to the parent frame to trigger a site reload;
- optional: redirection to a new URL;

Obtaining an authentication token

The authentication token can be obtained via an HTTP request, although it is advisable to use an Oauth2 framework allowing automatic renewal of session tokens.

Example using PHP:

function getToken()
{
    $auth_url = "https://auth.fairandsmart.com/auth";
    $auth_client_id = "fsorg";
    $auth_username = "mysecretidentity@example.com";
    $auth_password = "MySecretPassword";
    $token = "";

    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $auth_url . "/realms/" . $auth_realm . "/protocol/openid-connect/token");
    curl_setopt($curl, CURLOPT_POSTFIELDS, "grant_type=password&client_id=" . $auth_client_id . "&username=" . urlencode($auth_username) . "&password=" . urlencode($auth_password));
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($curl);
    curl_close($curl);

    return json_decode($response)->access_token;
}

At the end of this snippet, the token variable will contain the authentication token.

Obtaining a consent form URL

The form is obtained via an HTTP request; at the end of the operation, a consent form URL is obtained that can be integrated for example in the snippet.

It is necessary to indicate an identifier that will allow the form to be relayed to its user (uuid below).

function getFormUrl($uuid, $token)
{
    $api_url = "https://core.fairandsmart.com/api";
    $organisation_id = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
    $model_id_or_alias = "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY";
    
    $host = $_SERVER['HTTP_HOST'];
    $port = "";
    $proto = isset($_SERVER['HTTPS']) ? "https" : "http";

    $context = [
        "userid" => $uuid,
        "country" => "FR",
        "language" => "fr",
    ];

    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $api_url . "/organisations/" . $organisation_id . "/consents/" . $model_id_or_alias . "/endpoint");
    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($context));
    curl_setopt($curl, CURLOPT_HTTPHEADER, array("Authorization: Bearer $token", "Content-Type: application/json"));
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($curl);
    curl_close($curl);
}

At the end of this snippet, the variable $url contains the consent form url.

This example does not cover call variants; the following fields can be filled in according to the desired use:

callback: The URL to which the user will be redirected after the entry;
optoutEmail: email address to which a consent modification link will be sent;
optoutEmailLink: modification link in the email sent;
receipt: boolean indicating whether a consent receipt must be presented at the end of the entry;
iframe: authorises the injection of the iframe-resizer library in the form;
iframeEventsTargetOrigin: activates the transmission of events between iframe and the parent frame and indicates which should be the origin of the latter (see Triggering a reload of the parent frame);

Refer to https://core.fairandsmart.com/doc/api.html#operation/getConsentEndointJson for more information and an exhaustive list of possible parameters (language of the form, country of residence etc.).

Presentation of the form

Once the URL has been obtained, it can be presented to the user, for example by HTTP redirection (HTTP 3xx) or via an iframe.

For example in the case of an iframe:

<html>
    <body>
        <iframe width="700" height="500" src="<?php echo getForm(getToken()) ?>"></iframe>
    </body>
</html>

Integration with iframeResizer

as of version 19.04.02 (core 3.7.x)

iframeResizer is a javascript library for the seamless integration of an iframe within a site.

in this case the HTTP call to generate the form's URL must contain the "iframe" parameter set to "true".

Triggering a reload of the parent frame

as of version 19.09.01 (core 5.1.x)

In the case of integration by iframe, it may be desired to trigger a reload event for the parent frame.

in this case the HTTP call to generate the form's URL must contain the callback parameter set to the URL to be called and iframeEventsTargetOrigin set to the origin of the parent frame.

Source code

Find a more complete version of this code on github: https://github.com/fairandsmart/consent-iframe-integration- test

References

API documentation: https://core.fairandsmart.com/doc/api.html
iframeresizer: GitHub - davidjbradshaw/iframe-resizer: Keep iFrames sized to their content.
inter-domain communication: https://developer.mozilla.org/fr/docs/Web/API/Window/postMessage

fair[&]smart for organizations