🔐Authentication

To be able to embed a Story, a Tile, or a Dashboard Builder in your own environment, you'll have to authenticate them.

Our authentication system is flexible and secure. Without duplicating your user database in Toucan, you'll be able to pass a user context that will allow you to segregate data on the fly.

Overview

Embed Manager

You have an admin interface to manage your embeds and a settings page to set up the authentication. (Admin area>Embed Manager>Embed Settings).

Generate your client secret

You can obtain your client secret key by clicking on the "Re-generate secret" button. Your secret will then appear for you to copy and store securely.

If you're reloading the page, the secret will disappear and you'll have to regenerate a new one, which will invalidate any tokens already issued.

Cryptographic keys

We offer two ways to assert your authentication token. Either by managing a single RSA key pair or by using a JWKS endpoint if you rely on that system. (more information on JWKS). In any case, you'll have to sign your JWT token with the private key and share with us the public one.

1. Generate RSA key pair

In this case, you handle a single RSA key pair.

We recommend at least using a 2048-bit RSA key pair, 1024 ones aren't no secure enough anymore. In our example, we're using a 4096-bit RSA key pair.

# 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 your key pair is generated, you must upload your public one into your Toucan admin space.

2. Use a JWKS endpoint

In this implementation, you'll need to have an endpoint returning a set of public keys, which is a JWKS. It will allow you to rotate easily your public and private keys to increase even more the security.

Create JWT tokens with user context

This step consists of creating a JWT token signed with your private key in order to get your opaque token to authenticate your embeds. This means that the payload of the JWT token won't pass by your user's browser, it's the opaque token that links the user to his context.

In order to do that, your backend will have to implement a function to craft this token and send it 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.

Create your Opaque Token

Opaque tokens do not contain any sensitive information. Our authentication system will link it 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.

You can now pass your freshly generated opaque token to your embed script.

Example

Static insertion

// script
<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)

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

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

Last updated 7 months ago