Consent

Introduction

The Trust1Connector requires a user consent to function. This consent will be stored in the browsers localstorage for that user.

The consent token is stored with a domain specific key;t1c-consent-{{applicationDomain}}::{{apiUrl}}

When executing the consent flow, the user will be provided with a consent token which can be pasted into his clipboard. This token has to be passed with the Consent function which will perform a verfication (the token pasted in the clipboard - form the application context - should match with the token available on the clipboard for the T1C).

The consent can be configured to have an expiration date, when this expiration date has been exceeded, a new consent will be asked towards the user.

Consent dialog for implicit consent

Upon installation of the Trust1Connector, a user will not be able to retrieve any data from the connector without first giving its consent, agreeing to give access to his/her card reader of filestorage. Without this consent, all requests will return a 401/404 Unauthorized response with error No valid consent found or at initialisation of the Trust1Connector SDK an error No valid consent found. The application should detect these errors and use it to trigger the consent dialog.

The application shows this code word on screen and provide a button for 'copy-to-clipboard'. When the user has copied the code word to the clipboard (on user click button event), an implicit consent request can be executed towards the T1C. The T1C will grab the pasted code word from the user system clipboard and if both match, an implicit user consent has been granted for the calling application. The relation between the application and the local T1C instance is 'approved'. At this point the Trust1Connector returns a verified consent object that is stored in the browser's localstorage. This object is used to validate the consent and retrieve the necessary information for the Trust1Connector to function. This object will be re-used the next time the user wants to use the Trust1Connector until the consent expires.

Generating a random clipboard value

The clipboard value is a random value that is used to determine which agent you are running. This clipboard value needs to be pseudorandom so that we dont accidently find different agent.

The Javascript has an exposed function that creates this value for you.

The function is statically available on the T1CClient class and has the following interface.

public static generateConsentToken(): string

This will return the randomly generated value as a string value immediatley.

To call this;

# regular imported javascript via script tag
T1CSdk.T1CClient.generateConsentToken()

# Import loaded via NPM
import {T1CClient} from "t1c-sdk-js";

T1CClient.generateConsentToken()

If you decide not to use this function, the value needs to be prefixed with `::t1c::miksa::

User clipboard remark

Initially the concept was based on copying programmatically the code word, from the application context, to the user system clipboard. Although, through CAB forum, this not allowed; A user interaction is mandatory. The application should provide a 'copy-to-clipboard' button or alike in order to 'trigger' a user action. Once this action has been done, the T1C can be triggered to execute the consent.

Currently, the need for a user interaction is a known limitation (aka. clipboard.js). As this is the case, the W3C has a project ' Clipboard APIs' to propose a solution for a new clipboard API in browsers. The use case for 'Remote clipboard synchronisation' as a use case included in this draft proposal. As this is a draft, and not yet supported by the browsers, we can not perform an automatic 'paste' ('copy' in terms of the browser) to the clipboard.

Sending an implicit consent request can be done as follows:

T1CSdk.T1CClient.initialize(config).then(res => {
    client = res;
    console.log("Client config: ", client.localConfig)
    core = client.core();
}, err => {   
     if(err.code == 814501 || err.code == 814500) {
        console.log(err)
        client = err.client
        $('#consentModal').modal('show', {
            keyboard: false
        });
        $('.consent-token').text(client.core().generateConsentToken());
    } else if (err.code == 112999) {
        // Unavailable
    } else {
        console.error("T1C error:", err)
    }
}); 

The code below is an example of a javascript event handler on a consent button.

$('#consentModal .btn-primary').on('click', (ev) => {
    const tokenNode = document.querySelector('.consent-token');
    var range = document.createRange();
    range.selectNode(tokenNode);
    window.getSelection().addRange(range);
    try {
        document.execCommand('copy');
    } catch (err) {
        console.log('Oops, unable to copy');
    }
    window.getSelection().removeRange(range);
    const clipboardData = tokenNode.textContent;
    const validityInDays = 365
    
    client.core().getImplicitConsent(clipboardData, validityInDays).then(consentRes => {
        client = consentRes // replace the client and other set variables of the T1C
        core = client.core();
        core.version().then(versionResult => console.log("T1C running on core " + versionResult));
        $('#consentModal').modal('hide');
    }, err => {
        console.error(err)
    })
});

This call has 1 required and 2 optional parameters:

1. Code Word (required): a code word in string format that will be shown in the consent dialog.

2. Consent duration in days (optional): Allows the application the specify how long this consent is to be valid if granted. If not provided, the default value is 365 days.

3. Callback function (optional): function to be called with the result of the consent request.

The response of the consent will be an updated T1C Client which you after this point can use to continue your use-case(s).

The response can also be a 400 Bad Request with status code 814501 "Invalid consent" or 814500 "No agents registered" which means that the request has been sent with the unique code but the Registry cannot not find the user associated with it by checking the clipboards of all connected users.

This could mean that there is no T1C API client present or it is not running correctly.