Authentication¶

Workflow¶

authentication-workflow

How to authenticate my users on Toucan embeds ?¶

Toucan authenticates embeds with a JSON Web token. We share a secret key with your app that you will use to be able to craft valid Toucan tokens. It’s available on the Admin Area -> Embed Manager -> Settings panel.

embed-manager

embed-setting-panel

encryption-key

The user model to encrypt looks like that:

{
  "username": "myemail@acme.com",
  // roles has to be an array of 1 role: 'USER' or 'ADMIN'
  "roles": ["USER"],
  "groups": ["group1", "group2"],
  "privileges": {
    "smallApp1": ["view"],
    "smallApp2": ["contribute"]
  },
  "attributes": {}
}

A Python function to craft it could look like that:

# pip install pyjwt
from datetime import datetime, timedelta
from typing import Any, Dict, List
import jwt

def craft_toucan_embed_token(
    username: str,
    small_apps_access: Dict[str, List[str]],
    groups: List[str] = [],
    extra_infos: Dict[str, Any] = {},
    expires_in: timedelta = timedelta(hours=1),
) -> str:
    user_payload = {
        'username': username,
        'roles': ['USER'],
        'privileges': small_apps_access,
        'groups': groups,
        'attributes': extra_infos,
    }
    payload = {
      **user_payload,
      'iat': datetime.utcnow(),
      'exp': datetime.utcnow() + expires_in
    }
    return jwt.encode(payload, '__TOUCAN_EMBED_ENCRYPTION_KEY__', algorithm='HS256').decode('utf8')

We are providing more code snippets for differents languages directly into our product.

embed-settings-snippet

We are also providing a tool in order to check the validity of your token. Go on the “Embed Manager” and go to the “Settings” panel.

check-token

Can I make an embed available for everyone ?¶

Yes, you can make an embed “public” in the export interface.

Warning

Note that if you use any app or settings requesters in your story’s configuration, you will not be able to use your story in public mode. Indeed, only the data of your story will be exposed for security reasons. Trick: use the same dataset for your global requesters and your public embedded story/tile.

make-it-public

That make it available as this demo here:

Data & Permissions¶

If it’s not already done, first take a look to how you can connect your data to Toucan Toco here. It will dertermine the way you can set users rights over your data.

Data & Permissions handled by you¶

Context: you’ve chosen to keep data in your own information system and connect to Toucan through Live Data. In that case, you also need to handle authorizations over your Data Mart/Data Lake.

We allow you to set any variables in the attributes property of our user model. It could be anything that you need to authorize your users as an apiToken to fetch over your backend.

Workflow¶

in-house-data-management

Example¶

{
  "username": "myemail@acme.com",
  "roles": ["USER"],
  "groups": ["acme"],
  "privileges": { "retail-data": ["view"] } ,
  "attributes": {
    "apiToken": "249014d9-2eec-4fd5-bc2d-0bef9e477cdd" // You provide that key, Toucan cannot decode it
  }
}

1- Your user logs in
2- With the secret_key shared by Toucan Toco, you craft a userToken and pass it down to the embed script.
3- The embed script requests data to Toucan Toco’s backend and proxy it to your backend (with attributes in the userToken)

(data connection interface to HTTPS API)

4- Your backend uses attributes to authenticate the user that is behind the request
5- Your backend returns the right data

To retrieve data without using attributes via the user token, you can set a default value directly in the parameters field.

Data & Permissions handled in Toucan¶

In this case, you load your data into Toucan Toco’s data store. (more information here)

Workflow¶

toucan-data-management

Your user logs in
With the secret_key shared by Toucan Toco, you craft a userToken and pass down to the embed script.
The embed script request data to Toucan Toco’s backend
Toucan Toco’s backend decrypt the userToken to autenticate it
Toucan Toco’s backend return the right data

You can also use groups in our user object to manage permissions but that implies that you created them in Toucan Toco beforehand.