# Client Configuration
## Client Configuration
### Introduction
The T1C-JS can be downloaded (see [downloads](https://t1t.gitbook.io/t1c-js-belfius-guide/core/source-code)). 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](https://www.npmjs.com/package/trust1connector) you can import the package completely or just the necessary exports.
```markup
```
```javascript
import * as t1c from 'trust1connector';
```
```javascript
import {GCLConfigOptions, GCLConfig, GCLClient} from 'trust1connector';
```
{% hint style="info" %}
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:
```javascript
GCLLIB.GCLClient.initialize(gclConfig, function(err, client) {
// client is now ready to use
});
```
{% endhint %}
```javascript
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](#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`:
```javascript
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.
### 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](https://tools.ietf.org/html/rfc6749). More details about this profile are explained in [Client Credential Profile](https://tools.ietf.org/html/rfc6749#section-1.3.4).\
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:
```bash
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:
```javascript
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 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:
```javascript
POST https://{ocv-url}/security/jwt/refresh
Headers:
- apikey: 'apikey'
- content-type: 'application/json'
Body:
{
"originalJWT": "originalAndNonExpiredJWT"
}
```