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, this can be done using a script tag or when you are using the npm trust1connector package you can import the package completely or just the necessary exports.

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

import * as t1c from 'trust1connector';

import {GCLConfigOptions, GCLConfig, GCLClient} from 'trust1connector';

When using a regular script tag the library is globally exposed as GCLLIB, which means you will have to preface the classes with GCLLIB , like this:

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

var gclConfigOptions = new GCLConfigOptions(...);
var gclConfig = new GCLConfig(gclConfigOptions);

The configOptions object will allow you to specify and/or override the configuration to be used. Configuration options can be found below. All of the parameters of this object are explained in Configuration Options

Now that we have a GCLConfig, we can initialize the client library. The following example creates a Promise that will resolve with an instance of a GCLClient:

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

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 (default, type)	Description
apiKey	N/A, expects string	Valid API key, provided by the T1C-DS (Distribution Service). Either apiKey or gwJwt must be set for non-shared-environment installations! Initialisation will fail otherwise.
gwJwt	N/A, expects string	Valid JWT token to communicate over configured gateway. Either apiKey or gwJwt must be set for non-shared-environment installations! Initialization will fail otherwise
tokenExchangeContextPath	/apiengineAuth/v1 , expects string	Context path for exchanging apikey, defaults to /apiengineauth/v1
gclUrl	"https://localhost:10443/v2"	URI for the locally installed T1C-GCL component.
gwOrProxyUrl	"https://accapim.t1t.be:443", expects string	Gateway or Proxy address to use in order to send requests to backend services (DS, OCV, Token exchange,...). Will default to https://accapim.t1t.be:443 if not provided.
dsNamespace	"accapim.t1t.be", expects string	The namespace of the Distribution Service. This value will be correlated against a specific DS public key to determine the validity of JSON web tokens enabling the admin functionality. It must be the domain name hosting the DS.
dsContextPath	"/trust1team/gclds/v2", expects string	Path that will be appended to the gwUrl to reach the distribution service
ocvContextPath	"/trust1team/ocv-api/v1"	Path that will be appended to the gwUrl to reach the OCV service.
dsFileContextPath	"/trust1team/gclds-file/v1"	Path that will be appended to the gwUrl to download containers.
agentPort	N/A, expects number	Only used in shared environments. Specifies the port to be used to communicate with the selected agent.
implicitDownload	false, expects boolean	If set to true, the browser will automatically open a new window to download the latest T1C-GCL version if none is installed
forceHardwarePinpad	false, expects 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.
sessionTimeout	5, expects number	Timeout in seconds for a newly opened session. Can be overridden in the openSession call.
consentDuration	1, expects number	Number of days for which consent will be granted. Can be overridden in the getConsent call
consentTimeout	10, expects number	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.
pkcs11Config	N/A, expects Pkcs11ModuleConfig object	Configuration object that contains the paths to driver files to be used for PKCS11​
osPinDialog	false, expects boolean	Controls whether or not the PIN code (for non-pinpad readers) should be entered using an OS dialog or provided by the application
containerDownloadTimeout	30, expects number	Number of seconds to wait for container downloads to complete. If the timeout expires, initialisation of the client is aborted and an error is returned.
lang	"en", expects string	Language used in OS pop-up dialogs.
ProvidedContainers	Expects an array of containers e.g. [new T1CContainerId('beid-v2.1.1'),...]	An array of provided containers when the application does not provide a DS to dynamically fetch containers based on the application context.

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

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:

var configOptions = new GCLConfigOptions(...,gwJwt:"eyJhbGciOiJSUzzpwO8MRGeLH...CTp0kRIIXz6bxTHFnqFX28oXk", ...)
var config = new GCLConfig(configOptions)
GCLClient.initialize(config, 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"
}