Use Cases

Device

Register Device

After the installing the Trust1Connector API or Proxy (T1C), during it's first startup, the application will generate a key pair and certificate. The public key of the device installation must be registered with the DS as a first step in order to facilitate signed and encrypted communication to between an device installation and the DS. For this purpose, the T1C installer is packaged with an API key (which is generated when creating a new version through the DS API, see Create Or Update Version under management) with which it can obtain an access token to register its certificate with the DS. When the certificate is registered, the DS issues a unique identifier for the device installation. Upon reception of its identifier, the T1C device installation will store its key pair and certificate in a keystore keyed to that identifier and discard the installation API key. All subsequent communication between the T1C device installation and the DS is done through JWE, tokens signed with the device installation private key and encrypted with the DS public key (or vice versa for the response from the DS).

Update

At every startup, the T1C will contact the DS and request information about the latest available version. This results in the following behaviour

• If the device installation version is the same as the latest version, no action is taken

• If the latest version from the DS has the property recommended marked as true, an OS dialog will be shown informing the user that a new version is available, with a download link appropriate for the device OS

• If the latest version from the DS has the property mandatory marked as true, an OS dialog will be shown informing the user that his current installation can no longer be used and request that they download the new version through the provided link. The T1C application will then shut down, in order to force the user to upgrade if they wish to continue using T1C-enabled applications.

If the latest version is not recommended or mandatory but the device installation is not the latest version, the device installation will then request information on its current version. If the response from the DS has the version's allowed property marked as false, the device installation will display a message with a download link and shut down in a similar manner as when the latest version's mandatory property is marked as true

Download

The DS will provide an endpoint to download a OS-appropriate installer, which will be determined by parsing the User-Agent-header value when sent by the T1T-SDK-JS client (or an implementation of your own) using a browser. This is a best effort functionality, i.e. Trust1Team can't categorically guarantee a correct response due the fact that browsers' User-Agent values do not always accurately describe the client device. As an alternative, the DS also provides an endpoint where you can download the OS-appropriate version of your choice.

The DS is also responsible for serving installer packages to the end users. When creating a new version (see Create Or Update Version), URI's can be defined for OS-specific installers (either as a filesystem URI or an URL). The DS then streams the file contents over the gateway to the client device.

Synchronization

Through the DS, various settings and configurations can be managed. Whether it is to update the CORS allowlist through the Context Config or updating the device installations' SSL Keystore Config, for this information to reach the T1C device installations an exchange must take place.

Once per hour, the T1C device installation sends a digest of its Contex Config and SSL Keystore Config to the DS. If it doesn't match the digest on record in the DS (e.g. because the CORS allowlist has been changed or there is an update available for the SSL keystore), it sends the correct values back to the T1C device installation which then overwrites its current values with the new ones.

The T1C device installation also sends an update to the DS of its own state containing the following information:

• Labels: The labels of the applications that have executed requests to the T1C device installation. This is obtained from the application JWT received in the request (see Create or Update Label)

• Status: The device status which can be UPDATABLE, ERROR, ACTIVE, or ACTIVE

• User Agents: The user agents that have executed requests to the T1C device installation. This is obtained from the User-Agent header received in the request

• Transactions: A list transaction counters that have been executed per label, module, and use case. This data is used for billing and analytics

The synchronization is a required action for the T1C device installation. If it fails to synchronize a configurable amount of times in a row, it will shut down until it is able to synchronize with the DS.

Increment Use Case Counter

The DS receives use case counters from T1C device installations during the synchronization process. The counters are stored in 2 ways:

1. Per Device: For analytics and to be able to detect outliers, the counters are stored per device, label, module and use case.This data is kept for 1 month and then reset, while older records that have not been updated in the previous period are removed

2. Per Label: For analytics and billing purposes, the device counters received during synchronization are aggregated per label, module, use case and day of the month. Each month, the data is flattened to an archive as entry for a 1-month period and the label counters are reset. This means that the counter data can be queried granularly per organization, label, module and/or use case for each day of the current month, and only on a monthly basis for the preceding months.

Info

The DS provides an endpoint that can queried to receive information on the platform. Currently it returns the following information:

• Version

• Uptime

Administration

Manage Organizations

An organization is a container entity to group labels. You can retrieve, create, update or delete organizations.

Manage Labels

A label is associated with an API key, which allows applications to obtain a valid access token from the DS in order to obtain access to the T1C device installations' endpoints. You can retrieve, create, update or delete labels

Manage Versions

A version is associated with an installation API key for T1C device installation packages, and various configurations. You can retrieve, create, update or delete versions, and manage the associated configurations.

Generate JWT

The DS will generate an expirable access token for a label or a version, either for a consuming T1C application consumer or device installation registration respectively, if presented with an API key registered to the label or version.

Demographics

The DS will contain a frontend application with an analytics and demographics dashboard for logged in users, displaying device information breakdowns (OS, browser, ...), transactions overview, etcetera.