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:
The following example creates a Promise that will resolve with an instance of a GCLClient
:
Additional configuration can be passed to the library as a JSON object:
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):
Additionally an api-key must be passed to the initialize
function:
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 |
|
| Proxy address to use in order to send requests towards the Distribution Service |
|
| Client ID for SPA consumers |
|
| Client secret for SPA consumers |
|
| Override default URI for T1C-GCL resources |
|
| Valid api-key, provided by the T1C-DS (Distribution Service) |
|
| Valid JWT, provided by the T1C-DS (Distribution Service) |
|
| Allow automatic update of plugins |
|
| 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. |
|
| Default timeout in seconds for a newly opened session. Can be overridden in the openSession call. |
|
| Default number of days for which consent will be granted. Can be overridden in the getConsent call |
|
| 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:
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:
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 |
| non-administration mode | The T1C-GCL allows all non-administrative requests. |
| key authentication opaque token | This option is available for SPA's where additional infrastructure contraints applies. All communication must be done over HTTPS |
| JSON Web token, signed RS256 | This option is available when a back-end exchanges the api-key for a valid JWT. |
| 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:
The JWT can be passed to the JavaScript library:
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:
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:
A cuid is generated, this will result in a string starting with "c" and followed by >=24 characters
Take the first 8 characters following the starting "c" (this is a base36 encoded string)
Decode the 8 character string, and then calculate modulo 97; this is our check digit
The check digit is appended to the end of the cuid to form the
X-Authentication-Token
Token is saved in browser local storage and sent along with all requests
GCL can validate token integrity using the check digits
This should guarantee a) token integrity and b) token randomness.
Last updated