> For the complete documentation index, see [llms.txt](https://t1t.gitbook.io/t1c-js-belfius-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t1t.gitbook.io/t1c-js-belfius-guide/master-1/core/client-configuration.md).

# Client Configuration

## Client Configuration

### Introduction

The T1C-JS can be downloaded (see [downloads](/t1c-js-belfius-guide/master-1/core/source-code.md)). 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:

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

The following example creates a Promise that will resolve with an instance of a `GCLClient`:

```javascript
GCLLib.GCLClient.initialize(config, function(err, client) {
    // client is now ready to use
});
```

Additional configuration can be passed to the library as a JSON object:

```javascript
GCLLib.GCLClient.initialize({dsUrl:"https://accapim.t1t.be"}, function(err, client) { 
    // ...
});
```

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):

```javascript
GCLLib.GCLClient.initialize({dsUrl:"https://some.domain/"}, callback);
```

Additionally an **api-key** must be passed to the `initialize` function:

```javascript
GCLLib.GCLClient.initialize({apiKey:"somekey"}, callback);
```

#### 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                                                                                                                                                                         |
| ------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dsUrl`                  | `https://some.domain:8443/` | Proxy address to use in order to send requests towards the Distribution Service                                                                                                     |
| `oauth_client_id`        | `client_id`                 | Client ID for SPA consumers                                                                                                                                                         |
| `oauth_client_secret`    | `client_secret`             | Client secret for SPA consumers                                                                                                                                                     |
| `gclUrl`                 | `some_url`                  | Override default URI for T1C-GCL resources                                                                                                                                          |
| `apiKey`                 | `some_api-key`              | Valid api-key, provided by the T1C-DS (Distribution Service)                                                                                                                        |
| `jwt`                    | `jwt_token`                 | Valid JWT, provided by the T1C-DS (Distribution Service)                                                                                                                            |
| `allowAutoUpdates`       | `boolean`                   | Allow automatic update of plugins                                                                                                                                                   |
| `forceHardwarePinpad`    | `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. |
| `defaultSessionTimeout`  | `number`                    | Default timeout in seconds for a newly opened session. Can be overridden in the openSession call.                                                                                   |
| `defaultConsentDuration` | `number`                    | Default number of days for which consent will be granted. Can be overridden in the getConsent call                                                                                  |
| `defaultConsentTimeout`  | `number`                    | 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:

```javascript
var gclConfig = new GCLLib.GCLConfig();
gclConfig.gclUrl = "http://localhost:10080/v1";//override config for local dev
gclConfig.allowAutoUpdate = true;
```

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:

```javascript
GCLLib.GCLClient.initialize(gclConfig, callback);
```

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                                                                                                                      |
| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `no security token` | non-administration mode          | The T1C-GCL allows all non-administrative requests.                                                                              |
| `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.                                                  |
| `OAuth2`            | 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.

![Fail Silent](https://3049356757-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9hsLHAoFyYqgfdRqBE%2F-L9hsPXcyobfXS3sL-Q0%2F-L9hsfWDiJcG5J80tl_n%2FFail-Silent%20communication%20diagram.jpg?generation=1523335746722224\&alt=media)

### 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
GCLLib.GCLClient.initialize({jwt:"eyJhbGciOiJSUzzpwO8MRGeLH...CTp0kRIIXz6bxTHFnqFX28oXk"}, callback);
```

The following sequence diagram denotes the interaction explained above:

![JWT token generation](https://3049356757-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9hsLHAoFyYqgfdRqBE%2F-L9hsPXcyobfXS3sL-Q0%2F-L9hsfYUvVXVMCjGYn2S%2FGCL%20Token%20Issuance%20Back-end%20Initiated.png?generation=1523335746534176\&alt=media)

#### 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"
}
```

### 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:

1. A [cuid](https://www.npmjs.com/package/cuid) is generated, this will result in a string starting with "c" and followed by >=24 characters
2. Take the first 8 characters following the starting "c" (this is a base36 encoded string)
3. Decode the 8 character string, and then calculate modulo 97; this is our check digit
4. The check digit is appended to the end of the cuid to form the `X-Authentication-Token`
5. Token is saved in browser local storage and sent along with all requests
6. GCL can validate token integrity using the check digits

This should guarantee a) token integrity and b) token randomness.