Reconnaître vos utilisateurs connectés

1. Le principe en une phrase

À chaque affichage d’une page, votre serveur fabrique un petit jeton qui dit « c’est Jeanne Durand, jeanne.durand@exemple.fr », le signe avec une clé de signature que seuls Tikivio et vous connaissez, et le pose sur la balise du widget. Tikivio vérifie la signature : un jeton modifié, trop vieux ou déjà servi est refusé, et le widget revient alors à la saisie de l’adresse.

2. Générer la clé de signature

1. Un administrateur de l’organisation ouvre Paramètres › Widget › Réglages, carte « Clé de signature » (/o/<votre-organisation>/parametres/widget/reglages), et clique sur « Générer la clé ».
2. La clé s’affiche une seule fois, avec un exemple prérempli à donner au développeur. Copiez-la dans la configuration du serveur (variable d’environnement, coffre de secrets), jamais dans une page, un script du navigateur, un dépôt de code ou un e-mail.
3. Vérifiez que l’adresse du site où s’affiche le widget (par exemple https://erp.exemple.fr) figure dans les origines autorisées du widget : sinon le widget ne s’affiche pas du tout.

3. Fabriquer le jeton

Le jeton se fabrique sur le serveur, à chaque affichage de page (il ne sert qu’une fois) :

texte     = email + "|" + nom + "|" + expiration + "|" + nonce
signature = HMAC-SHA256(clé = clé de signature, message = texte), en hexadécimal minuscule
jeton     = base64url(texte, sans « = » final) + "." + signature

Puis ajoutez-le à la balise du widget, sans rien changer d’autre. Avant :

<script async src="https://app.tikivio.com/widget/tikivio.js" data-tikivio="IDENTIFIANT_PUBLIC"></script>

Après (une seule chose en plus, data-tikivio-token, recalculé à chaque affichage) :

<script async src="https://app.tikivio.com/widget/tikivio.js" data-tikivio="IDENTIFIANT_PUBLIC" data-tikivio-token="JETON"></script>

Dans une application d’une seule page, appelez plutôt Tikivio.setHostToken(jeton) après la connexion. Le jeton ne passe jamais dans une adresse.

PHP

// Tikivio widget: sign the signed-in user's email, on your server only.
$key   = getenv('TIKIVIO_SIGNING_KEY');
$name  = str_replace('|', '', $user->name);
$exp   = time() + 300;               // 5 minutes (15 at most)
$nonce = bin2hex(random_bytes(12));  // new for every token
$payload = "$user->email|$name|$exp|$nonce";
$token = rtrim(strtr(base64_encode($payload), '+/', '-_'), '=')
       . '.' . hash_hmac('sha256', $payload, $key);

Node.js (16 ou plus récent)

import { createHmac, randomBytes } from 'node:crypto';

// Tikivio widget: sign the signed-in user's email, on your server only.
const key = process.env.TIKIVIO_SIGNING_KEY;
const name = user.name.replaceAll('|', '');
const exp = Math.floor(Date.now() / 1000) + 300;  // 5 minutes (15 at most)
const nonce = randomBytes(12).toString('hex');     // new for every token
const payload = `${user.email}|${name}|${exp}|${nonce}`;
const token = Buffer.from(payload, 'utf8').toString('base64url')
  + '.' + createHmac('sha256', key).update(payload, 'utf8').digest('hex');

Python 3

import base64, hashlib, hmac, os, secrets, time

# Tikivio widget: sign the signed-in user's email, on your server only.
key = os.environ["TIKIVIO_SIGNING_KEY"].encode()
name = user.name.replace("|", "")
exp = int(time.time()) + 300            # 5 minutes (15 at most)
nonce = secrets.token_hex(12)           # new for every token
payload = f"{user.email}|{name}|{exp}|{nonce}".encode()
token = (base64.urlsafe_b64encode(payload).rstrip(b"=").decode()
         + "." + hmac.new(key, payload, hashlib.sha256).hexdigest())

C# (.NET 6 ou plus récent)

using System.Security.Cryptography;
using System.Text;

// Tikivio widget: sign the signed-in user's email, on your server only (.NET 6 or later).
var key = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("TIKIVIO_SIGNING_KEY")!);
var name = user.Name.Replace("|", "");
var exp = DateTimeOffset.UtcNow.ToUnixTimeSeconds() + 300;  // 5 minutes (15 at most)
var nonce = Convert.ToHexString(RandomNumberGenerator.GetBytes(12)).ToLowerInvariant();
var payload = Encoding.UTF8.GetBytes($"{user.Email}|{name}|{exp}|{nonce}");
// C#: ToLowerInvariant() is required, Tikivio only accepts a lowercase signature.
var token = Convert.ToBase64String(payload).TrimEnd('=').Replace('+', '-').Replace('/', '_')
    + "." + Convert.ToHexString(HMACSHA256.HashData(key, payload)).ToLowerInvariant();

4. Ça ne marche pas : les erreurs courantes

Quand le jeton est refusé, le widget ne bloque pas la personne : il lui demande son adresse, comme sans jeton. La console du navigateur (onglet Réseau, appel /session/hote) donne la raison :

Le widget ne s’affiche pas du tout ? Ce n’est pas le jeton : l’adresse du site manque dans les origines autorisées, ou le widget est désactivé.

5. Renouveler la clé de signature

Renouvelez-la si vous pensez qu’elle a pu fuiter, ou quand la personne qui la gardait quitte l’équipe. « Régénérer la clé » rend l’ancienne inutilisable immédiatement : les jetons signés avec elle sont refusés et les sessions ouvertes par votre site se ferment (celles ouvertes par code e-mail restent). Préparez donc le changement de configuration de votre serveur, régénérez, puis posez la nouvelle clé aussitôt. Entre les deux, le widget continue de marcher : il demande simplement l’adresse et un code, comme sans jeton.

6. Ce que le jeton prouve, et ce qu’il ne prouve pas

Le jeton prouve que votre serveur a déclaré cette personne : Tikivio fait confiance à votre site pour l’adresse e-mail transmise. N’y mettez que l’adresse de la personne réellement connectée. Les autres règles du widget (limites, pièces jointes, demandes visibles) restent les mêmes ; le détail technique complet est dans Installer le widget.