Consent

Trust1Connector user consent (implicit or explicit)

Introduction

The Trust1Connector supports 2 different user consent mechanisms for applications:

explicit user consent: the user will be prompted with a consent token, which he can accept or deny, based on the token presented by the applications (both tokes must match to securely link the browser with the operating system)
implicit user consent: the user will be provided with a consent token which can be pasted into his clipboard. The T1C-GCL will implicitly retrieve the consent token form the clipboard and perform a verification (the token pasted in the clipboard - form the application context - should match with the token available on the clipboard for the T1C-GCL)

For an explicit consent, the user is performing the verification of the shared code word. Whilst for an implicit consent, the T1C is performing the verification of the shared code word.

When user consent is enabled upon installation, a user consent will be demanded for:

access to peripheral card readers
access to file system (user space)

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.

If the consent has been enabled 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 Unauthorized response with a specific error code. The application should detect this error code and use it to trigger the consent dialog.

The consent request contains a code word (randomly generated by an algorithm of choose by the application) which will be shown in the dialog. The application shows this code word on screen as well, and if both match, the user can be sure that he is granting consent for the correct application. And the relation between the application and the local T1C instance is 'approved'.

Sending a consent request can be done as follows:

GCLLib.GCLClient.initialize(config, function(err, client) {
    var coreService = client.core();

    // Execute some functions like reading data from an inserted card
    // When 401 is returned, get the consent like this    
    core.getConsent('Title for the popup dialog', 'code word to be shown in the dialog', 1, 'warning', 'bottom', 'reader', 20, callback);
});

This call has 2 required and 4 optional parameters:

Title (required): this is a string containing the title for the consent dialog that will be shown to the user
Code Word (required): a code word in string format that will be shown in the consent dialog.
Consent duration in days (optional): Allows the application the specify how long this consent is to be valid if granted. Defaults to 1; this can be overridden in the GCLConfig
Alert level (optional): Allows the "severity" of the popup to be set. Defaults to warning. Valid values are: information, question, warning, error.
Alert position (optional): Sets the positioning on screen of the consent popup. Defaults to standard (exact meaning of this varies between OS's). Valid values are: standard, center, left, right, top, top_left, top_right, bottom, bottom_left, bottom_right.
Consent Type (optional): Specifies which type of consent is being requested. Valid values are reader and file_exchange.
Timeout (optional): Sets the timeout of the consent popup in seconds. If the user did not respond within this timeout, no consent will be granted. Default value is 30 seconds.
Callback function (optional): function to be called with the result of the consent request.

Response:

{
  "data": true,
  "success": true
}

The data property indicates whether or not the user granted consent. If this is true, the application can retry the request for which it originally received the 401 Unauthorized reply.

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'.

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 executes the flow automatically, this is retrieval and verification of the code word.

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 synchronization' 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:

GCLLib.GCLClient.initialize(config, function(err, client) {
    var coreService = client.core();

    // Execute some functions like reading data from an inserted card
    // When 401 is returned, get the consent like this    
    core.getImplicitConsent('code word to be copied on the clipboard', 1, 'reader', callback);
});

This call has 1 required and 3 optional parameters:

Code Word (required): a code word in string format that will be shown in the consent dialog.
Consent duration in days (optional): Allows the application the specify how long this consent is to be valid if granted. Defaults to 1; this can be overridden in the GCLConfig
Consent Type (optional): Specifies which type of consent is being requested. Valid values are reader and file_exchange.
Callback function (optional): function to be called with the result of the consent request.

Response:

{
  "data": true,
  "success": true
}

The data property indicates whether or not the user granted consent. If this is true, the application can retry the request for which it originally received the 401 Unauthorized reply.

Once consent is given, it will be valid for the consent duration specified in the request. However, the consent is only valid for a specific combination of parameters, which we call the consent components.

The components are the following:

Username
Browser Identification Token
Origin/Referer header

The username is derived from the OS, and browser identification token is sent along with the consent request (automatically added by the library). The third component identifies the site that is requesting consent. Usually an Origin header is sent along with the request that identifies the site, but in some cases this may be missing. If no Origin header can be found, we will use the Referer header and extract the originating domain from it. The 'origin header' and the 'referer header' are parts of the CORS specifications applicable in web browsers.

All three of the components need to match an existing consent for it to be considered valid. As soon as one of the components does not match, it will be considered a different user which will need to give consent, and a 401 Unauthorized reply will be returned.

The browser identification token has tampering-prevention enabled, in order to enforce a new token when changes are done to the token, residing in the browser storage.

PreviousCitrix NextGeneric Interface

Last updated 6 years ago

Introduction

Consent dialog for explicit consent

Consent dialog for implicit consent

User clipboard remark

Consent components