Customisation

Authentication

Preventing unauthenticated access to your avatars

Overview

Trulience offers developers the ability to generate encryption keys, enabling the creation of JWT tokens for the verification of requests originating from legitimate client applications.

Customers have the flexibility to generate multiple encryption keys, applying them to various avatars within their accounts. This functionality enables customers to create and assign distinct encryption keys to different avatars, ensuring a tailored and secure approach to token generation.

This feature provides enhanced control and security, allowing customers to customize their encryption strategy based on the specific requirements of each avatar within the Trulience platform.

Create Encryption Keys

Log in to your Trulience account.
Click the ‘Encryption Keys’ link in the navigation bar at the top of the page.
Give your encryption key a name and click the CREATE ENCRYPTION KEY button.

Trulience uses asymmetric encryption keys. Upon creation of the encryption key, the private key is shown on screen. Copy it and save it in a safe place. The private key must be kept secret to ensure that only authorised personnel can access it. Trulience does not store the private key so it will not be viewable again once this screen is closed.

Trulience stores the corresponding public key and uses it to verify the JWT Token sent from the client.

Apply an Encryption Key to a Specific Avatar

Click the ‘Avatar Creator’ link in the navigation bar at the top of the page.
Select and edit the avatar that you want to apply an encryption key to.
Go to the ADVANCED tab and select the ‘Encryption’ drop-down.
Set the relevant encryption key for your avatar.

Creating a JWT Token

The JWT Token can be created by using a standard token generator. The token generator is a hosted endpoint that executes code to generate tokens.

Refer to the sequence diagram below for a comprehensive overview of the process of generating and applying encryption keys to generate a JWT Token.

Token Generator Requirements

The token generator should follow these rules:

Accept two parameters:
- secret_key: The encryption key created in Trulience account.
- custom_data: URL Encoded custom JSON data to be sent. Key-value pairs should be taken from this JSON and added to the payload, so that it’s part of the token.
Use the RS256 algorithm to generate the token.
The generated token should have an expiry.

Token Generator Example

This javascript code snippet demonstrates how you can generate your own tokens:

const njwt = require('njwt');
const fs = require('fs');
const path = require('path');

const PRIVATE_KEY_FILE = 'private_key.pem';
const privateKeyPath = path.join(__dirname, PRIVATE_KEY_FILE);

function generateJwtTokenFromFile(customData = null) {
    let privateKey;
    try {
        privateKey = fs.readFileSync(privateKeyPath, 'utf8');
        console.log(`Successfully read private key from file '${PRIVATE_KEY_FILE}'.`);
    } catch (error) {
        if (error.code === 'ENOENT') {
            console.error(`Error: Private key file '${PRIVATE_KEY_FILE}' not found. Please ensure the file exists.`);
        } else {
            console.error(`Error: An exception occurred while reading the private key file: ${error.message}`);
        }
        return null;
    }

    const payload = {
        sub: "Token from local Node.js script"
    };

    if (customData && typeof customData === 'object') {
        Object.assign(payload, customData);
        console.log(`Custom data added to payload: ${JSON.stringify(customData)}`);
    }

    try {
        const token = njwt.create(payload, privateKey, 'RS256');
        token.setExpiration(new Date().getTime() + (60 * 60 * 1000));
        const compactToken = token.compact();
        console.log("JWT Token generated successfully.");
        return compactToken;
    } catch (error) {
        console.error(`Error: An exception occurred while generating the JWT Token: ${error.message}`);
        return null;
    }
}

(async () => {
    const myCustomData = {
        user_id: 1111,
        email: "abc@xyz.com"
    };

    const tokenWithCustomData = generateJwtTokenFromFile(myCustomData);
    if (tokenWithCustomData) {
        console.log("\nGenerated JWT (with custom data):\n", tokenWithCustomData);
    }
})();

This example demonstrates how to implement a token generator that adheres to the specified rules. Ensure your implementation keeps the encryption key secure and integrates custom data correctly into the JWT payload. Note that the private key is using PKCS#8 format, the file should look like this:

-----BEGIN PRIVATE KEY-----
<Your_private_key_here>
-----END PRIVATE KEY-----

Using a JWT Token

If you are using the Trulience client within an iFrame, pass the JWT token to the client as a parameter in the URL as shown below:

https://www.trulience.com/avatar/<your_avatar_id>?token=<your_jwt_token_here>

If you are using the Trulience SDK instead, then use the setToken() method while creating the Trulience object.

Use Your Custom UserID

To uniquely identify each user using your IDs instead of Trulience IDs, set the userId as a long value with the key userId contained in the custom_data sent to the token generator. The Trulience Gateway (“TG”) will validate the JWT token and use the userId if it is available in the token.

Avoid Unauthorized Access

A JWT token can be provided in an authentication request to verify the legitimacy of the client and safeguard against unauthorised sources. This verification is accomplished by creating a JWT token using the encryption keys before including it in the authentication request. The token is subsequently validated by the TG.

Upon successful validation, it can be confidently asserted that the request has originated from a valid source, granting permission to utilise the avatar. Conversely, if the decryption process fails, the authentication is deemed unsuccessful and the user is denied access to the avatar.

Customers are required to generate encryption keys and apply them to their avatars within the avatar configuration. This crucial step ensures a secure and reliable method for authenticating requests and adds an extra layer of protection to the avatar access process.

The sequence diagram below depicts a general flow of how this works:

Default Avatar Security

To ensure the security of all avatars, a default encryption key and corresponding token will be provided by Trulience. This token, generated using the default encryption key, is required for accessing the avatars.

Users have the option to edit the avatar settings to specify a different encryption key or choose not to use any encryption key at all (which we do not recommend).

In summary:

If the default encryption key is selected in the dashboard, the default token can be used.
If a different encryption key is selected, a token generated with that specific key will be required.