🔑Single Sign-On

Quelques lignes de code pour une expérience utilisateur en or !

Permettez à vos utilisateurs d'accéder à votre Spot via votre propre source d'authentification, sans créer de compte MeltingSpot séparé.

MeltingSpot propose deux modes d'authentification SSO, activables indépendamment depuis les settings de votre Spot (Paramètres > Single Sign-On) :

• Authentification SSO avec URL : MeltingSpot renvoie l'utilisateur vers votre page de login, qui le renvoie ensuite vers MeltingSpot avec un token signé.

• Authentification SSO programmatique : Votre backend ou nos SDKs échangent directement un token signé contre une session, sans redirection navigateur.

Les deux modes reposent sur le même token JWT et la même clé secrète SSO (visible en haut de la page de settings, champ "Authentifiez vos utilisateurs avec la clé SSO ci-dessous"). Seule la façon dont ce token est transmis à MeltingSpot diffère.

Générer un token SSO

Que vous utilisiez le mode "URL d'autorisation" ou le mode "Programmatique", vous devez générer un JSON Web Token (JWT) signé en HS256 avec la clé secrète SSO de votre Spot.

1. Installer la librairie JWT

Installez la librairie qui permet de créer le token en question :

Node.js

npm install --save jsonwebtoken

Python

pip install PyJWT

PHP

composer require firebase/php-jwt

C#

dotnet add package System.IdentityModel.Tokens.Jwt
dotnet add package Microsoft.IdentityModel.Tokens
dotnet add package Newtonsoft.Json

1. Créer le token

Ensuite, générez le token en intégrant les informations nécessaires à l'identification de l'utilisateur. Vous aurez besoin de la clé privée que vous pouvez trouver dans les settings de votre Spot.

Node.js

const jwt = require('jsonwebtoken');
const privateKey = 'YOUR_PRIVATE_KEY';
function createToken(user) {
  const userData = {
    sub: user.id, // Your own user ID
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    title: user.title, // optional
    avatarUrl: user.avatarUrl, // optional
    lang: user.lang, // optional
    timezone: user.timezone, // optional
    groups: {
      join: ["groupsId",...],
      leave: ["groupsId",...], 
    }, //optional
    domains: {
      set: { default: "https://some-default-url.com/for/this/member", customContext: "https://some-custom-context-url.com/for/this/member",...},
      unset: ['default', 'customContext']
    }, //optional
    customPropertiesValues: {
      "customPropertiesSlug1": ["valeurSlug",...],
      "customPropertiesSlug2": valeur,
    }, //optional
  };
  return jwt.sign(userData, privateKey, { algorithm: "HS256" });
}

Python

import jwt

private_key = "YOUR_PRIVATE_KEY"

def create_token(user):
  user_data = {
    'sub': user.id, # Your own user ID
    'firstName': user.firstName,
    'lastName': user.lastName,
    'email': user.email,
    'title': user.title, # optional
    'avatarUrl': user.avatarUrl, # optional
    'lang': user.lang, # optional
    'timezone': user.timezone, # optional
    'groups': {
      'join': ["groupsId",...],
      'leave': ["groupsId",...],
    }, #optional
    'domains': {
      'set': { default: "https://some-default-url.com/for/this/member", customContext: "https://some-custom-context-url.com/for/this/member",...},
      'unset': ['default', 'customContext']
    }, #optional
    'customPropertiesValues': {
      "customPropertiesSlug1": ["valeurSlug",...],
      "customPropertiesSlug2": valeur,
    }, #optional
  }
  return jwt.encode(user_data, private_key, algorithm='HS256')

PHP

<?php
use Firebase\JWT\JWT;

$privateKey = 'YOUR_PRIVATE_KEY';

function createToken($user) {
    global $privateKey;

    $userData = [
        'sub'                   => $user['id'],          // Your own user ID
        'firstName'             => $user['firstName'],
        'lastName'              => $user['lastName'],
        'email'                 => $user['email'],
        'title'                 => $user['title'] ?? null,      // optional
        'avatarUrl'             => $user['avatarUrl'] ?? null,  // optional
        'lang'                  => $user['lang'] ?? null,       // optional
        'timezone'              => $user['timezone'] ?? null,   // optional
        'groups'                => [
            'join'  => $user['groups']['join'] ?? [],
            'leave' => $user['groups']['leave'] ?? []
        ], // optional
        'domains'               => [
            'set'   => [
                'default'      => "https://some-default-url.com/for/this/member",
                'customContext'=> "https://some-custom-context-url.com/for/this/member",
                // add other domains if necessary
            ],
            'unset' => ['default', 'customContext']
        ], // optional
        'customPropertiesValues' => [
            "customPropertiesSlug1" => ["valeurSlug"],
            "customPropertiesSlug2" => "valeur"
        ] // optional
    ];

    return JWT::encode($userData, $privateKey, 'HS256');
}
?>

C#

using System;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.IdentityModel.Tokens;
using Newtonsoft.Json;

public class JwtTokenService
{
    private readonly string _privateKey;

    public JwtTokenService(string privateKey)
    {
        _privateKey = privateKey;
    }

    public string CreateToken(User user)
    {
        var claims = new List<Claim>
        {
            new Claim("sub", user.Id),
            new Claim("firstName", user.FirstName),
            new Claim("lastName", user.LastName),
            new Claim("email", user.Email)
        };

        if (!string.IsNullOrEmpty(user.Title))
            claims.Add(new Claim("title", user.Title));

        if (!string.IsNullOrEmpty(user.AvatarUrl))
            claims.Add(new Claim("avatarUrl", user.AvatarUrl));

        if (!string.IsNullOrEmpty(user.Lang))
            claims.Add(new Claim("lang", user.Lang));

        if (!string.IsNullOrEmpty(user.Timezone))
            claims.Add(new Claim("timezone", user.Timezone));

        if (user.Groups != null)
        {
            if (user.Groups.Join != null && user.Groups.Join.Length > 0)
                claims.Add(new Claim("groups.join", JsonConvert.SerializeObject(user.Groups.Join)));

            if (user.Groups.Leave != null && user.Groups.Leave.Length > 0)
                claims.Add(new Claim("groups.leave", JsonConvert.SerializeObject(user.Groups.Leave)));
        }

        if (user.Domains != null)
        {
            if (user.Domains.Set != null && user.Domains.Set.Count > 0)
                claims.Add(new Claim("domains.set", JsonConvert.SerializeObject(user.Domains.Set)));

            if (user.Domains.Unset != null && user.Domains.Unset.Length > 0)
                claims.Add(new Claim("domains.unset", JsonConvert.SerializeObject(user.Domains.Unset)));
        }
 
        if (user.CustomPropertiesValues != null)
        {
            foreach (var kvp in user.CustomPropertiesValues)
            {
                claims.Add(new Claim($"customPropertiesValues.{kvp.Key}", JsonConvert.SerializeObject(kvp.Value)));
            }
        }

        var tokenHandler = new JwtSecurityTokenHandler();
        var key = Encoding.UTF8.GetBytes(_privateKey);
        
        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = new ClaimsIdentity(claims),
            SigningCredentials = new SigningCredentials(
                new SymmetricSecurityKey(key), 
                SecurityAlgorithms.HmacSha256)
        };

        var token = tokenHandler.CreateToken(tokenDescriptor);
        return tokenHandler.WriteToken(token);
    }
}

public class User
{
    public string Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    public string Title { get; set; }
    public string AvatarUrl { get; set; }
    public string Lang { get; set; }
    public string Timezone { get; set; }
    public Groups Groups { get; set; }
    public Domains Domains { get; set; }
    public Dictionary<string, object> CustomPropertiesValues { get; set; }
}

public class Groups
{
    public string[] Join { get; set; }
    public string[] Leave { get; set; }
}

public class Domains
{
    public Dictionary<string, string> Set { get; set; }
    public string[] Unset { get; set; }
}

Au sein de votre token, vous pouvez utiliser les paramètres suivants :

Paramètre	Type	Description
sub	string	(requis) L'identifiant de votre utilisateur sur votre application. Ce champ doit être de 255 caractères maximum.
firstName	string	(requis) Le prénom de l'utilisateur (max. 255 caractères).
lastName	string	(requis) Le nom de l'utilisateur (max. 255 caractères).
email	string	(requis) L'email de l'utilisateur. Assurez-vous d'avoir validé que cet email est légitime (max. 255 caractères + le format de l'email doit être valide).
title	string	Le titre de l'utilisateur en format text (utilisé généralement pour préciser son job / son entreprise).
avatarUrl	string	Une URL qui pointe vers la photo de profil de l'utilisateur. Elle doit démarrer par https:// ou http:// et vous devez vous assurer que l'URL est valide.
lang	string	La langue par défaut de l'application pour cet utilisateur. MeltingSpot supporte : en, fr, de, it, es, pt, nl. Si la langue n'est pas spécifiée, la valeur par défaut est en.
timezone	string	Le fuseau horaire de l'utilisateur. Si aucun n'est précisé ou s'il n'est pas valide, la valeur par défaut appliquée sera Europe/Paris.
iat	number	La date à laquelle le token est généré.
exp	number	La date d'expiration du token. Bien que ce champ ne soit pas requis, nous recommandons qu'il soit fixé à +60s par rapport à l'instant où le token est généré. S'il n'est pas spécifié, le token sera valide indéfiniment, ce qui pourra poser des problèmes de sécurité.
groups: join	string[]	Les groupes dans lesquels vous voulez ajouter le membre. Il vous suffit de récupérer l'id des groupes en question depuis le menu de sélection des groupes dans la table audience.
groups: leave	string[]	Les groupes dont vous voulez retirer le membre. Il vous suffit de récupérer l'id des groupes en question depuis le menu de sélection des groupes dans la table audience.
customPropertiesValues	type de la propriété	Si vous avez des propriétés personnalisées, vous pouvez spécifier la valeur que vont prendre ces propriétés pour le membre.
domains: set	string[]	Si vous avez réalisé l'embed du Spot sur plusieurs domaines, spécifiez les domaines de redirection du membre. Il sera redirigé vers la clé de domaine default au clic sur un email de notification.
domains: unset	string[]	Si vous avez réalisé l'embed du Spot sur plusieurs domaines et spécifié des domaines de redirection du membre, vous pouvez les retirer via ce paramètre (URL d'un logiciel pour lequel le membre n'a plus de licence, site web dont l'URL a changé...). Vous devrez réutiliser les clés définies dans l'objet set.

Mode 1 : Authentification SSO avec URL d'authorisation

Ce mode délègue le login à votre propre page d'authentification via une redirection navigateur.

Vous avez 2 parcours principaux :

Depuis votre application

1. Au sein de votre application, votre utilisateur clique sur un lien "Académie".

2. Au clic sur ce lien, votre application génère un "token" grâce au script présenté ci-dessus.

3. L'utilisateur est redirigé vers votre Spot et transmet au passage le token.

4. Si le token est validé, l'utilisateur est connecté et identifié grâce aux données que vous aurez incorporées dans le token (comme son prénom, son nom et son email).

Depuis votre Spot

1. Si vous activez le SSO, un utilisateur sur votre Spot va pouvoir choisir entre s'inscrire avec son email + mot de passe ou s'inscrire via SSO. S'il choisit le SSO, il est redirigé vers une page de votre application où il devra être identifié (ce qu'on appelle l'URL d'autorisation).

2. Depuis cette page, l'utilisateur doit se connecter s'il n'est pas connecté ou créer son compte s'il n'en a pas. S'il est déjà connecté sur cette page, vous n'aurez pas nécessairement besoin de lui demander de s'identifier à nouveau.

3. Votre application génère un token (cf. le script ci-dessus)...

4. ...et l'envoie à votre Spot tout en redirigeant votre utilisateur sur la page du Spot où il était précédemment.

5. Si le Spot valide le token, alors l'utilisateur est connecté. S'il n'existait pas avant, un nouveau membre est créé grâce aux informations que vous aurez inclues dans le token (comme son prénom, nom et email).

Implémentation

1. Activer le SSO depuis les settings de votre Spot

Pour commencer, vous devez activer le SSO depuis les settings de votre Spot :

1. Ajoutez une URL d'Autorisation. Cette URL est celle d'une page vers laquelle est redirigé un utilisateur qui souhaite se connecter à votre Spot depuis votre Spot (Cf le deuxième point du parcours "Depuis votre Spot"). 👀 Si vous souhaitez effectuer des tests en local, utilisez dans l'URL 127.0.0.1 car les URL localhost sont bloquées par notre système.

2. Copiez la clé privée.

3. Activez le SSO lorsque les scripts ci-dessous ont été intégrés à votre app.

2. Génération du Token

Voir la section Générer un token SSO

3. Redirection vers MeltingSpot

Une fois le token utilisateur créé, vous devez rediriger l'utilisateur vers une URL en passant le token en paramètre. Cette URL vous est fournie en paramètre (redirectUrl) lorsque l'utilisateur atterrit sur votre URL d'autorisation. De base, elle ressemble à ceci :

https://go.meltingspot.io/spot/<Your Spot ID>/sso/jwt

Vous devez ajouter le token en paramètre de la façon suivante :

https://go.meltingspot.io/spot/<Your Spot ID>/sso/jwt?ms_token=<Your generated SSO Token>

Dans la plupart des cas, l'URL de redirection que nous fournissons (redirectUrl) contient aussi un paramètre referrerUrl qui permet de renvoyer l'utilisateur sur la page où il se trouvait lorsqu'il s'est connecté en mode SSO.

Vous pouvez forcer la valeur de ce paramètre, mais pour être valide, la valeur doit représenter un chemin relatif à https://go.meltingspot.io et à votre Spot (ex: ?referrerUrl=/spot/129487c9-6acc-43d9-ab96-182ded763538/lives).

Votre Spot ID est la chaîne de caractère suivant spot/ dans l'url de votre Spot (ex : go.meltingspot.io/spot/129487c9-6acc-43d9-ab96-182ded763538 -> le Spot ID est 129487c9-6acc-43d9-ab96-182ded763538).

Embed / widgets + SSO = ❤️

Une fois l'authentification SSO configurée pour votre Spot, il vous est possible de transmettre le token JWT authentifiant l'utilisateur dans les scripts d'installation de l'embed du Spot ou de widgets. Cela permettra à chaque utilisateur dans votre espace de pouvoir afficher l'embed ou un widget en étant directement connecté. A l'affichage de l'embed, vos membres n'auront donc plus à cliquer sur 'Continuer avec SSO' pour s'inscrire ou se connecter 😉

Pour cela, il vous faut ajouter dans les paramètres du script d'installation de l'embed ou du widget le paramètre authToken.

Mode 2 — Authentification SSO programmatique

Ce mode permet à votre backend ou à notre SDK Coach d'échanger directement un token signé contre une session MeltingSpot, sans redirection navigateur.

Configuration

Dans l'onglet "Authentification SSO programmatique" des settings SSO, il n'y a qu'un seul réglage : un switch Activer l'authentification par programmation (SDK)

Utilisation de l'auto-join dans le SDK Coach

Une fois ce mode activé, transmettez le token JWT généré (section "Génération du token") en tant que authToken à notre SDK Coach et ajoutez la mention autoJoin :

import { Coach } from '@meltingspot/coach';
await Coach.start({  spotId: 'YOUR_SPOT_ID',  authToken: 'CURRENT_USER_SSO_TOKEN', // le même JWT que pour l'authentification simple  autoJoin: true, // rejoint et valide automatiquement le membre sur le Spot});

Le Coach ré-authentifie l'utilisateur avec ce token, puis appelle en votre nom l'API de jonction automatique en lui repassant le même JWT signé. Le Spot en déduit prénom, nom, email, groupes, domaines et propriétés personnalisées directement depuis les claims du token — inutile de les renvoyer une seconde fois.

• autoJoin nécessite authToken : sans lui, l'option est ignorée (aucune jonction n'est tentée).

• L'auto-join respecte les règles habituelles de transition de statut : un membre déjà rejeté ou désactivé ne sera pas automatiquement débloqué.

• Si l'auto-join échoue, le démarrage du Coach échoue dans son ensemble et l'authentification est annulée — ce n'est pas un mécanisme "best-effort" silencieux, il doit être traité comme une erreur bloquante côté intégration.

Bon à savoir !

• Dois-je activer les deux modes ?

  Non, ils sont indépendants. Activez "URL d'autorisation" si vous voulez un bouton de connexion SSO classique sur votre site ; activez "Programmatique" si vous intégrez nos SDKs ou appelez notre API directement. Rien n'empêche d'activer les deux en parallèle.

• Dois-je générer un token différent pour l'auto-join ?

  Non. C'est exactement le même JWT, avec les mêmes claims et la même clé secrète que pour l'authentification programmatique classique. Seule différence : l'option autoJoin: true côté SDK Coach.

• En mode Programmatique, pourquoi mon utilisateur est authentifié mais pas membre du Spot ?

  En mode "Programmatique", authentification et jonction au Spot sont deux étapes distinctes (contrairement au mode "URL d'autorisation" où elles sont automatiquement liées). Utilisez autoJoin: true sur le Coach SDK, ou gérez la jonction séparément via votre intégration.

• En mode Programmatique, que se passe-t-il si un membre a déjà été rejeté ou désactivé ?

  L'auto-join respecte les règles de transition de statut existantes : il ne "débloque" pas un membre rejeté ou désactivé. Le membre doit être dans un état qui autorise l'acceptation pour que l'auto-join aboutisse.

• Que se passe-t-il quand un utilisateur rejoint un Spot en SSO ? Quelque soit le mode utilisé, à partir du moment où le token est correct, si le membre n'existe pas, nous créons un nouvel utilisateur sur la base des informations transmises dans le token et nous le connectons. S'il existe déjà, nous le connectons simplement sans mettre à jour ses informations.

• Que se passe-t-il pour les utilisateurs actuels lorsque j'active le SSO ?

  Quelque soit le mode, si vous activez le SSO alors que vous avez déjà des membres inscrits sur votre Spot : aucun souci, ils pourront continuer à utiliser les identifiants actuels (email + mot de passe). Ils pourront d'ailleurs s'identifier via SSO et ajouter cette méthode d'identification à leur profil du moment que l'email associé à leur compte SSO est la même que celle utilisée sur le Spot.

• Mon Spot est privé, comment sont gérées les inscriptions en mode SSO ? En mode "URL d'autorisation" : puisque l'utilisateur repasse par votre page de login avant de rejoindre le Spot, on considère qu'il a déjà été validé par vous — il est donc automatiquement accepté, même si le Spot est privé.

  En mode "Programmatique", ce n'est pas automatique : l'authentification seule ne fait pas rejoindre le Spot. Avec autoJoin: true, le membre est ajouté en respectant les règles de transition de statut habituelles (un membre déjà rejeté ou désactivé ne sera pas débloqué) — ce n'est donc pas une acceptation garantie comme en mode redirect.

• Que se passe-t-il si un utilisateur modifie son email dans mon application ? Lors de sa prochaine connexion au Spot, nous le considérerons comme un nouvel utilisateur. S'il veut pouvoir accéder à son ancien profil sur le Spot, il devra se connecter via email + mot de passe.

• Est-ce que je peux décider de la page d'atterrissage qu'ouvre un membre lorsqu'il se connecte en SSO ? Oui ! Lorsqu'un de vos utilisateurs accède à votre Spot depuis votre application vous pouvez utiliser le paramètre "referrerUrl" pour l'envoyer sur n'importe quelle page de votre Spot.

• Comment sont gérés les statuts des membres lorsqu'ils se connectent ou rejoignent un Spot via SSO ? -> Nous vous disons tout ici !