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.

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.

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

Last updated