🔐Authentication

To embed a Story, Tile, or Dashboard Builder within your environment, you’ll need to authenticate each embed. Our authentication system is designed to be both secure and flexible. Without duplicating your user database in Toucan, you can pass a user context that dynamically segments data.

Overview

Embed Manager

Embed Manager Interface The admin interface allows you to manage embeds and set up authentication. Path: Admin Area > Embed Manager > Embed Settings

Access Embed Manager from Admin Area

Embed Settings

Generate your client secret

Generate a client secret by clicking "Re-generate secret" in the Embed Manager.

Once generated, copy and store it securely, as it will disappear upon refreshing the page. Each new secret invalidates any previously issued tokens.

Cryptographic keys

You have two methods to manage authentication tokens securely:

1. RSA Key Pair Management: Generate and manage a single RSA key pair to sign JWT tokens. Recommended key strength: at least 2048 bits (in this example, we use 4096 bits).

   # Generate a private key
   openssl genrsa -out "toucan_priv.pem" 4096
   
   # Generate a public key
   openssl rsa -in "toucan_priv.pem" -pubout -out "toucan_pub.pem"

   Once generated, upload the public key to your Toucan admin area.

2. Using a JWKS Endpoint: For environments that support a JWKS endpoint (more information on JWKS), this option allows you to rotate keys for enhanced security.

JWKS method

Create JWT tokens with user context

To authenticate your embeds, create a JWT token signed with your private key. This JWT token does not pass through the user's browser; it links a user to their context through an opaque token sent to our authentication service.

Code example in JS

const fs = require('fs')
const jwt = require('jsonwebtoken')
​
​
const privateKey = fs.readFileSync('PATH_TO_YOUR_TOUCAN_EMBED_PRIVATE_RSA_KEY', 'utf8')
​
function signToken(payload) {
  try {
    return jwt.sign(payload, privateKey, { algorithm: 'RS512' });
  } catch (err) {
    throw err
  }
}
​
const token = signToken({
  sub: "toucan-embed-client",
  iss: "<YOUR-ISS>",
  aud: "https://OAUTH_SERVER_URL/TENANT_ID/oauth/oauth-token",
  exp: "<TIMESTAMP_IN_FUTURE>",
  jti: "<RANDOM_UNIQUE_ID>",
  embed_context: {
    "username": "YOUR_USER_EMAIL", // MANDATORY : user id
    "roles": ["USER"],  // MANDATORY
    "privileges": {  // MANDATORY : user access's right
      "APP-ID": ["PRIVILEGE"],
    },
    "groups": ["USER_GROUP"],  // user group
    "attributes": {  // everything else you want that can be used for custom permission, queries...
      "ENTITY_ID": "ENTITY_ID"
    },
    "secrets": { // Secrets will not be sent to the front or displayed, allowing data such as credentials or tokens used for authentication to be sent. 
      "TOKEN": "ACCESS_TOKEN_FOR_DATAWAREHOUSE"
    }
  }
})

Other code examples lie in your Embed Settings interface.

JWT Token's payload

• sub: subject of the JWT. Shared in your Embed Interface settings.

• iss: issuer of the JWT. Shared in your Embed Interface settings.

• aud: recipient for which the JWT is intended. Shared in your Embed Interface settings.

• exp: time after which the JWT expires, in timestamp. Should follow your own authentication expiration policy.

• jti: unique identifier; can be used to prevent the JWT from being replayed. You have to generate a random string.

• embed_context: object that represents the user and his context. Let's dive in.

  • username: it will represent your user. We recommend using the user's email but you could also use a unique identifier.

  • roles: USER or ADMIN. For your users, we recommend to let USER. For your SDK Key, for instance, ADMIN should be used. (cf. authenticate Embed SDK)

  • privileges: object that describes your user access's right to apps.

    • keys are Apps' IDs (cf. find Apps' IDs)

    • value is an enum on ["view", "validator", "contribute"] (more information in user management section)

  • groups: user groups defined in Toucan. Can be useful to define visibility rules based on user groups.

  • attributes: arbitrary variables that give additional context to the user. Most of the time, it includes information that allows data segregation on Live Data implementation.

  • secrets: variables used to send data to the Toucan tenant that will not be displayed. This section is used for variables that must remain secret, such as passwords or tokens.

Warning

As of today, we can't support a user context bigger than 3.5KB. Toucan won't raise an error if it exceeds it, it will truncate it. If you encounter odd issues, please use the "Check token" in Embed Settings to ensure that your user's context is complete and not truncated.

Generating the Opaque Token

To create an opaque token, use the JWT token crafted earlier. This token does not contain sensitive information but connects to the previously provided user context.

Curl example

curl --request POST -u "toucan-embed-client:CLIENT_SECRET"
  --url https://OAUTH_SERVER_URL/TENANT_ID/oauth/oauth-token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data scope=embed \
  --data assertion=JWT_TOKEN

Parameters

• CLIENT_SECRET: string retrieve after uploading your public key

• OAUTH_SERVER_URL: URL of our own authentication service. Shared in the Embed Settings interface.

• TENANT_ID: id of your tenant. Shared in the Embed Settings interface.

• JWT_TOKEN: token that represents your user, crafted in the previous step.

Once your opaque token is generated, pass it to the embed script in your application.

Example

Static insertion

<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token=_0XBPWQQ_7613519f-a24b-4987-920d-218f7e6df591" type="text/javascript"></script>

Programmatic insertion

(cf. Embed SDK and Embed SDK Authentication)

• SDK_AUTH_TOKEN: A token generated with admin rights to access all your embeds

• EMBED_ID: Can be found in the Dashboards tab of your apps, or directly in the Embed Manager.

const instance = await TcTcEmbed.initialize('SDK_AUTH_TOKEN');

await instance.insertEmbedById(
    'MY_EMBED_ID',
    document.getElementById('parent-container'),
    {
        token: '_0XBPWQQ_7613519f-a24b-4987-920d-218f7e6df591',
        ...
    }
);