T1C-JS Guide (v2)
v2.4.1
Search
⌃K

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 (container 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>
Once loaded, the script will expose a GCLLib global. This global will allow you to create a GCLConfig:
var gclConfig = new GCLLib.GCLConfig(configOptions);
The GCLConfigOptions object will allow you to specify and/or override the configuration to be used. Configuration options can be found in the Configuration Options below. You can create a GCLConfigOptions as follows:
var configOptions = new GCLLib.GCLConfigOptions(
gclUrl,
gwOrProxyUrl,
apiKey,
gwJwt,
tokenExchangeContextPath,
ocvContextPath,
dsContextPath,
dsFileContextPath,
pkcs11Config,
agentPort,
implicitDownload,
forceHardwarePinpad,
sessionTimeout,
consentDuration,
consentTimeout,
syncManaged,
osPinDialog,
containerDownloadTimeout,
localTestMode,
lang,
providedContainers
);
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:
GCLLib.GCLClient.initialize(gclConfig, function(err, client) {
// client is now ready to use
});

Configuration Options

Upon initialization, a GCLConfig object can be provided as parameter to the initialize function. The possible configuration options for this object are:
Key
Default Value
Description
apiKey
N/A, expects string
Valid API key, provided by the T1C-DS (Distribution Service). Either apiKey or gwJwt must be set for unmanaged 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 unmanaged installations! Initialisation will fail otherwise.
gclUrl
"https://localhost:10443/v2"
URI for the locally installed T1C-GCL component.
gwOrProxyUrl
"https://accapim.t1t.be:443"
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"
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"
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 Citrix environments. Specifies the port to be used to communicate with the selected agent.
implicitDownload
false
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
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
Timeout in seconds for a newly opened session. Can be overridden in the openSession call.
consentDuration
1
Number of days for which consent will be granted. Can be overridden in the getConsent call
consentTimeout
10
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, expectsModuleConfig object
Configuration object that contains the paths to driver files to be used for PKCS11
osPinDialog
false
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
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.
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.

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 (container 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/apiengineauth/v1/login/application/token'
The JWT can be passed to the JavaScript library:
GCLLib.GCLClient.initialize({gwJwt:"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"
}