Client Configuration

Introduction

The T1C-JLIB can be downloaded (see downloads). In order to use the T1C-JLIB, the library must be initialized with an api-key. The api-key is a key received upon subscription. The T1C-JLIB is a client library for native or Java applications. As a reminder, the T1C-GCL can be used from a web context using the T1C-JS, or by addressing directly the T1C-GCL interface.

The api-key will be translated into an JWT token in order to perform administration functionality (container management).

Initialize the client library

To initialize the Java client library, the library must included in your project, for example as a Maven dependency

<dependendies>
    <!--Trust1Connector Java Library-->
    <dependency>
        <groupId>com.t1t.t1c</groupId>
        <artifactId>Connector</artifactId>
        <version>${version.t1c.lib-java}</version>
    </dependency>

    <!--Google JSON needed for t1c-lib-java-->
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>${version.gson}</version>
    </dependency>
</dependencies>
...
<repositories>
    <repository>
        <id>t1t-releases</id>
        <url>https://repo.t1t.be/repository/maven-releases/</url>
    </repository>
</repositories>

The following example creates a client instance with a configuration object

LibConfig conf = new LibConfig();
conf.setEnvironment(Environment.DEV);
conf.setDsUri(DS_URI); // "https://accapim.t1t.be/trust1team/gclds/v1"
conf.setOcvUri(OCV_URI); // "https://accapim.t1t.be/trust1team/ocv-api/v1"
conf.setGclClientUri(URI_T1C_GCL); // "https://localhost:10443/v1"
conf.setApiKey(API_KEY);
conf.setHardwarePinPadForced(false);
conf.setDefaultPollingIntervalInSeconds(5);
conf.setDefaultPollingTimeoutInSeconds(10);
conf.setSessionTimeout(60);
conf.setDefaultConsentDuration(2);
conf.setDefaultConsentTimeout(35);
conf.setClientFingerprintDirectoryPath("/usr/local/t1c");
T1cClient t1cClient = new T1cClient(conf);

Configuration Options

Upon initialization, a configuration object can be provided as parameter to the T1cClient constructor.
The possible configuration parameters upon initialization are:

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-JLIB/GCL:

Fail-Silent network principle

When a network call fails, a com.t1t.t1c.exceptions.RestException is thrown. When calling external services, care should be taken to handle these exceptions, but the occurrence of one does not impair further functionality. There is one exception: device registration must be done online, with a connection towards the T1C-DS.

Admin Functionality

The Java client needs to be initialized during start-up with a valid token in order to enable administrator functionality.

OAuth2 Client credentials

OAuth2 client credential profile will be provided soon. The T1C-JLIB 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.

JSON Web Token

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: xxxx-xxxx-xxxx-xxxx-xxxx' 'https://apim.t1t.be/t1c/ds/token'

The JWT can be passed to the Java library:

LibConfig configuration = new LibConfig();
configuration.setEnvironment(Environment.DEV);
//
// Other configuration params
//
configuration.setJwt("eyJhbGciOiJSUzzpwO8MRGeLH...CTp0kRIIXz6bxTHFnqFX28oXk");
T1cClient t1cClient = new T1cClient(configuration);

// Or it can be set through the client itself
t1cClient.exchangeApiKeyForToken();

JWT Refresh Endpoint

The T1C-JLIB 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.
You can force a refresh JWT request by using the following function:

t1cClient.refreshJwt();

Security Notice

JWT and OAuth will be supported from version 2.0.0 and higher. The current T1C-JLIB requires api-key to request administration functionality.

Client Fingerprinting

The library will send a client identification token along with all requests, in the X-Authentication-Token header. The token is constructed as follows:

1. A 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 as a file on the 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.