Client Configuration

Client Configuration

Introduction

The T1C-JS can be downloaded (see downloads). In order to use the T1C-JS, the library must be initialized with an api-key. The api-key is a key received upon subscription. The T1C-JS is a client library for web based consumers. As a reminder, the T1C-GCL can be used from a native applications context using a native client, or addressing directly the T1C-GCL interface. In order to work with an api-key in a browser context, 2 type of consumers can be distinguished:

• SPA (Single Page Application) integration: this is a web application without any back-end

• Web Application integration: this is a web application with a back-end implementation

For an SPA, an api-key (thus the access token to the Distribution Service) is considered unsafe in a browser context. For SPA's, Trust1Team configures extra security measures on infrastructure level. A mutual authentication is required and additional policies are applied (IP restriction policy, ...).

The api-key will be translated into an JWT token in order to perform administration functionality (plugin management). Additionally the JWT can only be stored in an HTTPS-only cookie and must not be stored in the browser's local storage.

Initialize the client library

To initialize the JavaScript client library, the library must be loaded into your HTML page:

<script src="../GCLLib.js" charset="utf-8"></script>

The following example creates a Promise that will resolve with an instance of a GCLClient:

GCLLib.GCLClient.initialize(config, function(err, client) {
    // client is now ready to use
});

Additional configuration can be passed to the library as a JSON object:

GCLLib.GCLClient.initialize({dsUrl:"https://accapim.t1t.be"}, function(err, client) { 
    // ...
});

The dsUrl option passed to initialize function in the example above is the targeted Distribution Service. When using a proxy, the proxy address can be provided at initialization of the T1C-JS. Be sure to use an URI without context-path when initializing the library (the library is managing context paths). For example, in order to use the Distribution Service in acceptance (ACC):

GCLLib.GCLClient.initialize({dsUrl:"https://some.domain/"}, callback);

Additionally an api-key must be passed to the initialize function:

GCLLib.GCLClient.initialize({apiKey:"somekey"}, callback);

Configuration Options

Upon initialization, a JSON object can be provided as parameter to the initialize function. The possible configuration parameters upon initialization are:

Key	Value	Description
dsUrl	https://some.domain:8443/	Proxy address to use in order to send requests towards the Distribution Service
oauth_client_id	client_id	Client ID for SPA consumers
oauth_client_secret	client_secret	Client secret for SPA consumers
gclUrl	some_url	Override default URI for T1C-GCL resources
apiKey	some_api-key	Valid api-key, provided by the T1C-DS (Distribution Service)
jwt	jwt_token	Valid JWT, provided by the T1C-DS (Distribution Service)
allowAutoUpdates	boolean	Allow automatic update of plugins
forceHardwarePinpad	boolean	When enabled, will force the use of the hardware pinpad if is available. All calls made with a ("software") pin parameter will be rejected on readers with pinpads, and vice versa.
defaultSessionTimeout	number	Default timeout in seconds for a newly opened session. Can be overridden in the openSession call.
defaultConsentDuration	number	Default number of days for which consent will be granted. Can be overridden in the getConsent call
defaultConsentTimeout	number	Default number of seconds to wait for the user to respond to a consent popup. If the timeout expires, the consent popup disappears and T1C will consider this a refused consent.
lang	language identifier	Unicode local identifier. Denotes the language to use for displaying modals to the end user. Defaults to 'en'

The T1C-JS contains a GCLConfig object which can be used for configuration purpose:

var gclConfig = new GCLLib.GCLConfig();
gclConfig.gclUrl = "http://localhost:10080/v1";//override config for local dev
gclConfig.allowAutoUpdate = true;

Notice that we only override some properties; this overrides the default values. In the following example we pass the configuration object to the initialize function:

GCLLib.GCLClient.initialize(gclConfig, callback);

The token is used in administration flows, but is never blocking the T1C-GCL communication. This is a fail-safe mechanism has been provided to ignore administration request when services are not available. The following security options can be provided, depending on the infrastructure/architecture of the application using the T1C-JS/GCL:

Key	Value	Description
no security token	non-administration mode	The T1C-GCL allows all non-administrative requests.
api-key	key authentication opaque token	This option is available for SPA's where additional infrastructure contraints applies. All communication must be done over HTTPS
jwt	JSON Web token, signed RS256	This option is available when a back-end exchanges the api-key for a valid JWT.
OAuth2	OAuth2 Client Credential profile	This option is a better alternative for SPA's dealing with security constraints in a browser context.

Fail-Silent network principle

Failing silently is the equivalent of returning an empty response maintaining a short network-timeout. This prevents blocking operational functionality from administration functionality. There is one exception: device registration must be done online, with a connection towards the T1C-DS.

Fail Silent

Single Page Applications - Admin Functionality

The JavaScript client needs to be initialized during start-up with a valid token in order to enable administrator functionality.

Api-key (key-authentication)

For an SPA, an api-key (access token to the Distribution Service) is considered unsafe in a browser context. For SPA's, Trust1Team configures extra security measures on infrastructure level. A mutual authentication is required and additional policies are applied (IP restriction policy, ...).|

Plugins can be:

• private plugins: customer oriented plugins (Belgian eID, EMV, ...)

• public plugins: community plugins (Calypso, Mobib, Moneo, ...)

The api-key translates the consumer context for the Distribution Service in order to distribute plugins. Based on the api-key a valid JWT is generated.

OAuth2 Client credentials

OAuth2 client credential profile will be provided soon. The T1C-JS will be configured with a client_id and a client_secret following RFC6749. More details about this profile are explained in Client Credential Profile. Based on the generated access_token, using the client_id and client_secret, a valid JWT is generated.

Web Applications with back-end

The JavaScript client needs to be initialized during start-up with a valid token in order to enable administrator functionality.

JSON Web Token

For a Web Application consisting of a back-end, the api-key will never be exposed to the front-end. The api-key will be translated into an JWT token in order to perform administration functionality (plugin management). In order to exchange a consumer api-key with a valid JWT, an REST call must be performed to the Distribution Service:

curl -X GET --header 'Accept: application/json' --header 'apikey: 0ea9f7c2-df8b-483c-9dac-b020dbd42e14' 'https://apim.t1t.be/t1c/ds/token'

The JWT can be passed to the JavaScript library:

GCLLib.GCLClient.initialize({jwt:"eyJhbGciOiJSUzzpwO8MRGeLH...CTp0kRIIXz6bxTHFnqFX28oXk"}, callback);

The following sequence diagram denotes the interaction explained above:

JWT token generation

JWT Refresh Endpoint

The T1C-JS library required a JWT to send administration requests towards the T1C-GCL. The retrieval of a valid JWT happens in a fail-silent mode, and depends on the type of initialization of the library. When OAuth2 or api-key is used, a JWT request will be requested upon initialization. When a JWT token is used for initialization, no additional request will be performed. A JWT token has an expiration time. Before a JWT is expired, the T1C-JS library will request a refresh token automatically. You can force a refresh JWT request by using the following function:

POST https://{ocv-url}/security/jwt/refresh
Headers:
- apikey: 'apikey'
- content-type: 'application/json'
Body:
{
  "originalJWT": "originalAndNonExpiredJWT"
}

Security Notice

JWT and OAuth will be supported from version 2.0.0 and higher. The current T1C-JS requires api-key to request administration functionality.

Browser Fingerprinting

The library will send a browser identification token along with all requests, in the X-Authentication-Token header. The token is constructed as follows:

1. A cuid is generated, this will result in a string starting with "c" and followed by >=24 characters

2. Take the first 8 characters following the starting "c" (this is a base36 encoded string)

3. Decode the 8 character string, and then calculate modulo 97; this is our check digit

4. The check digit is appended to the end of the cuid to form the X-Authentication-Token

5. Token is saved in browser local storage and sent along with all requests

6. GCL can validate token integrity using the check digits

This should guarantee a) token integrity and b) token randomness.