# Client Configuration

## Introduction

The T1C-JS can be downloaded (see [downloads](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:

```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.    |
| `pkcs11Config`           | `ModuleConfig object`       | Configuration object that contains the paths to driver files to be used for PKCS11                                                                                                  |
| `osPinDialog`            | `boolean`                   | Controls whether or not the PIN code (for non-pinpad readers) should be entered using an OS dialog or provided by the application                                                   |

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://1766811608-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9hsLHDKsMEIM_b7evx%2F-L9hsQTuhZzirhBbjRTJ%2F-L9hsbitN4n6TYA_UdCP%2FFail-Silent%20communication%20diagram.jpg?generation=1523335729025716\&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://1766811608-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-L9hsLHDKsMEIM_b7evx%2F-L9hsQTuhZzirhBbjRTJ%2F-L9hsblbgZc5KtvmROpX%2FGCL%20Token%20Issuance%20Back-end%20Initiated.png?generation=1523335728978425\&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.
