LogoLogo
v3.7.x
v3.7.x
  • Introduction
  • Concept
  • Prerequisites
  • Trust1Connector JS SDK
  • Changelog
  • Core
    • Setting up the SDK
    • Initialize Trust1Connector
    • Readers
    • Core Service
    • Downloading latest Trust1Connector
    • Consent
    • Authenticated client
    • Module/container setup
    • Status codes / error handeling
    • Quick-Migration Guide (v2 -> v3)
  • Token
    • Token typing models
    • Generic token
    • Belgian eID
    • Aventra MyEID PKI
    • Idemia Cosmo One v8.2
    • Oberthur Cosmo One v7.3
    • Diplad (BeLawyer)
    • Chambersign*
    • Camerfirma*
    • Certigna*
    • Certinomis*
    • Jcop3*
    • Airbus
    • Eherkenning
    • Safenet*
    • Luxembourg ID
    • LuxTrust
    • Other PKCS11 Compatible Tokens*
  • Payment
    • Payment typing models
    • EMV*
    • Crelan
  • FIle
    • File exchange
  • HSM
    • Remote loading
  • Other
    • Print
    • Wacom*
  • Miscellaneous
    • Prerequisites New Token/Smart Card
    • Prerequisites Support
    • Troubleshooting
      • Changing Device date/time
      • Enable Debug Logging
      • Connector Connection Issues
      • Mac OSX Sonoma
    • Installation FAQ
    • Removal of Trust1Connector
Powered by GitBook
On this page
  • Introduction
  • Mode of operations
  • Single Instance Without Consent
  • Single Instance With Consent
  • Multi-user Instance With Consent
  • Creating the configuration object
  • T1CConfigOptions
  • Authenticated client
  • Initializing the Trust1Connector SDK
  • Enforcing consent flow in a optional consent enabled Trust1Connector
  • Clipboard
  • Retrieve JWT token
  • Trust1Connector environments

Was this helpful?

Export as PDF
  1. Core

Initialize Trust1Connector

PreviousSetting up the SDKNextReaders

Last updated 1 year ago

Was this helpful?

Introduction

For initialisation of the T1C you need to prepare your application first by and importing them in such a way that you can call for the Javascript functions when you need them. When you've succesfully and installed the Trust1Connector you can initialize and use the Trust1Connector

Mode of operations

The Trust1Connector's architecture is created so that we can support a wide range of system setups. This means we can both support single users using the Trust1Connector but also systems where multiple users make use of the same hardware, we call this shared environments.

Additionally to shared environments, we support remote desktops as an extension on shared environments.

Since Trust1Connector version 3.6.1 we can provide integrators the support to initialise the Trust1Connector in different ways.

Single Instance Without Consent

Please contact support if you need support for this modus. As this is not the default mode and requires the Trust1Connector to be run in a specific context

Using this operation mode, the integrator can decide to use the Trust1Connector and inforce that no consent is needed. making it very straightforward for the end-user to utilise any functionality the Trust1Connector offers.

In this mode we cannot support multiple instances of the Trust1Connector. Meaning shared environments and multiple users logged in on the same system can create unexpected behaviour.

Single Instance With Consent

This is the default mode of operation and goes hand-in-hand with instances. A consent is required to both request the user's permission to use the Trust1Connector on his system and also to correctly determine which instance of the Trust1Connector needs to be used.

The Consent provides support to use the Trust1Connector with multiple users on the same system ().

Using Single Instance with consent as an operational mode, enforeces users to consent unregarded the environment - be it single device or multi user environment. Validity of the consent can be determined by the application.

Multi-user Instance With Consent

This mode support shared environments such as Citrix, terminal server and remote desktop.

Creating the configuration object

We will prepare the SDK's configuration Object, this object is used to pass information about which default port the Trust1Connector is running on, JWT key, API url, ... which is needed to properly contact and use the Trust1Connector.

Retrieving JWT tokens should be handled in your own backend to maximize security

Now we can create a complete Configuration Options object to be passed to the Trust1Connector.

T1CConfigOptions

The T1C config options is a class that can be used to create a valid configuration object to initialize the Trust1Connector. Below you can find a class definition.

class T1CConfigOptions {
  constructor(
    public t1cApiUrl?: string,
    public t1cApiPort?: string,
    public t1cProxyUrl?: string, // deprecated
    public t1cProxyPort?: string, // deprecated
    public jwt?: string,
    public applicationDomain?: string, // "rmc.t1t.be"
  ) {}
}

t1cProxyUrl and t1cProxyPort are deprecated since 3.5.x and only used in 3.4.x versions.

Parameters

t1cApiUrl: string Optional The URL that connects to the local Trust1Connector instances. This can be either localhost or a domain that directs towards localhost. By default this will be https://t1c.t1t.io

t1cApiPort: string Optional The port defined to be used for the Trust1Connector. By default this is 51983

t1cProxyUrl: string Optional - Deprecated The URL that connects to the local Trust1Connector Proxy instances. This can be either localhost or a domain that directs towards localhost. By default this will be https://t1c.t1t.io

t1cProxyPort: string Optional - Deprecated The port defined to be used for the Trust1Connector Proxy. By default this is 51983

jwt: string Optional The JWT token that is used to authenticate towards the Trust1Connector. This should be retrieved from the DS and is only needed when the Trust1Connector is configured to work with a DS and requires JWT validation

applicationDomain: string Optional The domain of the application that is using the Trust1Connector. This is used to make sure the consent is only available for a specific web-application. This prevents various clients to interfere with eachother. This domain also tags the Distribution service transactions being sent to the Distribution service. This makes it easy to distinguish between applications/tags for the transactions

// ...

let environment = {
    t1cApiUrl: 'https://t1c.t1t.io',
    t1cApiPort: '51983',
    t1cProxyUrl: 'https://t1c.t1t.io',
    t1cProxyPort: '51983',
    jwt: 'eyJraWQiOiJ0MWNkcyIsImFsZyI6IlJTMjU2In0..._Mg2PfdhCMQ',
    applicationDomain: 'test-app'
};

const configoptions = new T1CSdk.T1CConfigOptions(
        environment.t1cApiUrl,
        environment.t1cApiPort,
        environment.t1cProxyUrl,
        environment.t1cProxyPort,
        environment.jwt,
        environment.applicationDomain
    );
config = new T1CSdk.T1CConfig(configoptions);

// ...

When a remote DS is used you can set the following field with the correct DS url, this will in turn use the DS's capabilities of acting as a Trust1Connector proxy for enchanced security.

// When remote DS is used set the following parameter
config.dsUrl = "https://acc-ds.t1t.io";

Authenticated client

Initializing the Trust1Connector SDK

// ...

T1CSdk.T1CClient.initialize(config).then(res => {
    client = res;
    console.log("Client config: ", client.localConfig);
    core = client.core();
    core.version().then(versionResult => console.log("T1C running on core "+ versionResult));
}, err => {
    if (err.code == 814500 || err.code == 814501) {
        client = err.client;
        // (new) Consent is required
    }
    else if(err.code == 112999) {
        // Could not connect with the Trust1Connector
    } else {
        // an uncatched error occured
        console.error("T1C error:", err)
    }
});

// ...

When either no consent is present or its invalid you will receive a invalid client object (line 8 in example above) that can be used to trigger the getImplicitConsent function in the Core serivce.

The signature of the getImplicitConsent function is as follows;

public getImplicitConsent(codeWord: string, durationInDays?: number, 
    callback?: (error?: T1CLibException, data?: T1CClient) => void
): Promise<T1CClient>

This function expects:

codeword: string The string value that is saved to the user's clipboard needs to be sent to the Consent function.

durationInDays: number Optional Amount of days that the consent is valid.

callback: (error?: T1CLibException, data?: T1CClient) Optional Callback when you're not using ES

Below is a small javascript example of how you can trigger the getImplicitConsent function

client.core().getImplicitConsent(document.querySelector(".clipboard-data").innerHTML).then(res => {
    console.log("Consent Executed")
    client = res;        
    // Use the client for your use-cases
}, err => {
    // Failed, use the error client to retry the consent
    this.client = err.client;
    console.error(err.description ? err.description : err)
})

After this you will have a client that can be used to execute the rest of the functionality that the Trust1Connector has to offer.

Full example

// Global client to be used over the entire application
const client = null

// Prepare the configuration
let environment = {
    t1cApiUrl: 'https://t1c.t1t.io',
    t1cApiPort: '51983',
    t1cProxyUrl: 'https://t1c.t1t.io',
    t1cProxyPort: '51983',
    jwt: 'eyJraWQiOiJ0MWNkcyIsImFsZyI6IlJTMjU2In0..._Mg2PfdhCMQ',
    applicationDomain: 'test-app'
};

const configoptions = new T1CSdk.T1CConfigOptions(
        environment.t1cApiUrl,
        environment.t1cApiPort,
        environment.t1cProxyUrl,
        environment.t1cProxyPort,
        environment.jwt,
        environment.applicationDomain
    );
config = new T1CSdk.T1CConfig(configoptions);

// Initialize the Trust1Connector with the previously created configuration object
T1CSdk.T1CClient.initialize(config).then(res => {
    client = res;
    console.log("Client config: ", client.localConfig);
    core = client.core();
    core.version().then(versionResult => console.log("T1C running on core "+ versionResult));
}, err => {
    if (err.code == 814500 || err.code == 814501) {
        // (new) Consent is required
    }
    else if(err.code == 112999) {
        // Could not connect with the Trust1Connector
    } else {
        // an uncatched error occured
        console.error("T1C error:", err)
    }
});
    
    

// when the user has clicked on the clipboard/consent button we execute the getImplicitConsent function
document.querySelector(".clipboard").addEventListener("click", (ev) => {
    if (client != null) {
        client.core().getImplicitConsent(document.querySelector(".clipboard-data").innerHTML).then(res => {
            console.log("Consent Executed")
            client = res;        
            // Use the client for your use-cases
        }, err => {
            this.client = err.client;
            console.error(err.description ? err.description : err)
        })
    }

})

Enforcing consent flow in a optional consent enabled Trust1Connector

When your instance of the Trust1Connector has the optional consent mode enabled but still want to enforce the consent flow you can use the following explicit consent initialisation.

This will ignore the enabled feature of having the consent being optional and will require a valid consent to operate the Trust1Connector.

// ...

T1CSdk.T1CClient.initializeExplicitConsent(config).then(res => {
    client = res;
    console.log("Client config: ", client.localConfig);
    core = client.core();
    core.version().then(versionResult => console.log("T1C running on core "+ versionResult));
}, err => {
    if (err.code == 814500 || err.code == 814501) {
        client = err.client;
        // (new) Consent is required
    }
    else if(err.code == 112999) {
        // Could not connect with the Trust1Connector
    } else {
        // an uncatched error occured
        console.error("T1C error:", err)
    }
});

// ...

Clipboard

To provide a consent, we suggest you use the clipboard functionality available in browsers. The most supported way is via document.exeCommand and below you can find an example of this.

The code below is an example of how you can integrate a copy command in the webbrowser

const tokenNode = document.querySelector('.consent-token');
var range = document.createRange();
range.selectNode(tokenNode);
window.getSelection().addRange(range);
try {
    // Now that we've selected the anchor text, execute the copy command
    document.execCommand('copy');
} catch(err) {
    console.log('Oops, unable to copy');
}

// Remove the selections - NOTE: Should use
// removeRange(range) when it is supported
window.getSelection().removeRange(range);
const clipboardData = tokenNode.textContent;

Retrieve JWT token

GET https://ds.t1t.io/v3_5/tokens/application

This endpoint will return a valid JWT token to use for a certain period based on the API-key you provide in the `apikey` header

Headers

Name
Type
Description

apikey

string

API-key received from Trust1Team

{
    "success": true,
    "data": "eyJraWQiOiJ0MWNkcyIsImFsZyI6IlJTMjU2In0...v8_Mg2PfdhCMQ"
}
{
    "message": "No API key found in request"
}
{
    "success": false,
    "description": "Invalid API key",
    "code": 1005,
}

Trust1Connector environments

The Trust1Connector has a Develop, Acceptance and production version. The difference between them is mainly the Distirbution service connection and the port number they use.

These port numbers are linked to the Trust1Connector distributed by Trust1Team. If you have a custom installation these will be different. Please contact your distributor for more information.

The port numbers of the Trust1Connector are;

Environment
Port number
Distribution service

Production

51983

https://ds.t1t.io

Acceptance

51883

https://acc-ds.t1t.io

Develop

51783

None

Just like the this mode requires a consent to both ask permission to the user and determine the correct instance of the Trust1Connector Agent/API.

When the Trust1Connector is configured with a Distribution Service in mind you can provide a valid JWT token in the configuration object. .

Now we can continue to use the config variable to and retrieve a T1CClient

If you need to set up the Trust1Connector with a valid JWT token you can follow the documentation on the to from the DS.

When you have a valid token you can provide this in the Configuration. This will make sure the Trust1Connector is usable until the token becomes unvalid. At which point you can your token to continue to use the Trust1Connector. More information on how to retrieve,use and refresh a token can be found on the .

Initialization of the Trust1Connector in many cases requires a user consent, the exception being when no registry is configured (either local or central) and if the Trust1Connector is run in a enabled. More information can be found . The registry allowed us to create a Trust1Connector that works in any environment, without the need for Administrative rights from the users, wether it be Standalone, Multi session, RDP, Citrix, ...

To Initialize the Trust1Connector a is required(when a central or local registry is present) or when the . When no consent can be found the error codes 814500 or 814501 will be thrown. This means that either the previous consent is not valid anymore or no consent was given yet.

More information regarding the consent can be found on the which explains it in more detail.

If you have the enabled the consent error will not appear but will either give a valid Client to use or a 112999 error, depicting it could not find any active instance of the Trust1Connector.

The Consent requires a user action to . This data is used by the T1C registry to make sure you're targetting the correct instance of the Trust1Connector. More information about this can be found here.

There is also a but this is not fully supported yet

Consent page
clipboard API
adding the SDK JS files to your project
downloaded
multi user
even at the same time
single instance with consent mode
You can retrieve such token via the Distribution Service based on the API key you received
initialize
here
specific single modus
Consent
modus is set to optional consent
optional consent mode
copy some data to its clipboard
Authenticated Client page
Authenticated Client page
retrieve a valid token
refresh