Embedding a story with user attributes

Introduction

The process of embedding a story is simple — just copy the HTML script (either iFrame or web component) and use it to embed content wherever needed with the generated token. Additionally, you can use user attributes to ensure that individuals only view content aligned with their access permissions. Before jumping into the tutorial, it's vital to handle a few prerequisites for a smoother process. Follow these steps:

1. Prepare Data Sources:

2. Create Your Story

Now that your story is ready. Let's delve into how the attributes work behind the scenes for three users: Max, Amy, and Ben. Each of them holds specific permissions:

• Max: Access to France

• Amy: Access to Belgium

• Ben: Access to both France and Belgium

When users log in, the website generates a Toucan opaque token to authenticate them on embedded content. This token grants access rights to a JWT token containing the user's country as an attribute. Toucan dynamically organizes and presents data based on these values and the user's rights. It's important to note that the dynamic organization occurs after users set up filtering steps, ensuring data is customized to their rights and specified attributes, such as country values.

Agenda

1. Generate a token with attributes

2. Filter your data based on attributes

Generate a token with attributes

One of the most crucial steps in the embedding process is the creation of a token. This process includes proving your identity, establishing a secure system, managing your content from an admin center, generating secret keys, and creating secure token to authenticate your embedded content.

For detailed information, please refer to: Authentication Documentation To break it down into a few steps:

1. Generate Client Secret:

   • Get a secret key for authentication
2. Cryptographic Keys:

   • Choose between using a single RSA key pair or a JWKS endpoint

   • If using RSA, generate a private and public key pair (2048-bit or more) and upload the public key to your admin space.
   • If using JWKS, set up an endpoint returning public keys for added security
3. Create JWT Tokens with User Context:

   • This involves creating a JWT token signed with your private key to authenticate your embeds.

   • The token contains information like user details, roles (USER or ADMIN), access rights, groups, attributes, and secrets.

   • Secrets are intended for safeguarding sensitive information, such as tokens used for authentication, enabling secure access to databases, APIs, and other systems.

   • Payload example:

     • 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" } }

   • In our case, we used the following payload,

     • 'embed_context': { 'username': "[e-mail]", 'workspace_id': workspace_id, 'roles': ["USER"], 'privileges': { small_app: ["toucan-tutorial"] }, 'attributes': { "country" : "France" } }

4. Create Opaque Token:

• This token does not contain sensitive information but links to the user context provided earlier.

• Use this under the HTML script that you get from Toucan

Filter your data based on attributes

Go to the story you have already created and add a step to apply user attributes:

• Select the dataset.

• Click "Edit."

• Add a filter step where the country is equal to the following syntax: {{ (user or {}).get('attributes', {}).get('country', 'Belgium') }} Note: This code checks if there's information about the country in the give user attribute and if it's available, it provides that country; otherwise, it defaults to 'Belgium'. More on advance syntax for variables.
• Save and publish the app.

• Next, go to production mode and copy the HTML script.

Test your HTML script on CodePen. Insert the token, and remember to adjust the height by adding it to the user CSS section.

For example:

body { height:100vh }

Click on Select the dataset below to apply the user attribute country in the story below:

Congratulations! You have successfully embedded your story in a test environment.