Client Configuration
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.
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
});
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, expects ModuleConfig object | |
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. |
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
The JavaScript client needs to be initialized during start-up with a valid token in order to enable administrator functionality.
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.
The JavaScript client needs to be initialized during start-up with a valid token in order to enable administrator functionality.
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
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"
}
Last modified 2yr ago