Authentication

Workflow

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. With this key, you will be able to craft valid Toucan tokens.

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": { "smallApp": { "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, str],
    groups: List[str] = None,
    extra_infos: Dict[str, Any] = None,
    expires_in: timedelta = timedelta(hours=1),
) -> str:
    user_payload = {
        'username': username,
        'roles': ['USER'],
        'privileges': {'smallApp': 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

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

check-token

Can I make an embed available for everyone ?

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

make-it-public

make-it-public

That make it available as this demo here:

Warning

That action will expose for everyone the story’s data! Make sure that you want to do so. Also, for now if a view/report or date appRequesters are setup on the application, you will not be able to use a public embed. Let us know your needs around this capability.

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

in-house-data-management

Example

{
  "username": "myemail@acme.com",
  "roles": ["USER"],
  "groups": ["acme"],
  "privileges": { "smallApp": { "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)
publish

(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

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

toucan-data-management

  1. Your user logs in
  2. With the secret_key shared by Toucan Toco, you craft a userToken and pass down to the embed script.
  3. The embed script request data to Toucan Toco’s backend
  4. Toucan Toco’s backend decrypt the userToken to autenticate it
  5. 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.