Consent

If consent has been enabled for the local installation of Trust1Connector, a user will not be able to retrieve any data from the connector without first giving explicit consent, agreeing to give access to his/her card reader. 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 as a cue to trigger the consent dialog. The consent request contains a code word (randomly generated by an algorithm of choce by the application) which will be shown in the dialog. The idea is that the application will show 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.

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:

1. Title (required): this is a string containing the title for the consent dialog that will be shown to the user

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

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

4. Alert level (optional): Allows the "severity" of the popup to be set. Defaults to warning. Valid values are: information, question, warning, error.

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

6. Consent Type (optional): Specifies which type of consent is being requested. Valid values are reader and file_exchange.

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

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

Consent components

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.

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.