Impersonation

L'impersonation te permet de te connecter temporairement en tant qu'un de tes utilisateurs SSO, directement depuis le dashboard Saasy. C'est un outil indispensable pour le support technique : au lieu de demander des captures d'écran ou des identifiants, tu vois exactement ce que ton utilisateur voit.

Comment ca marche

Le flux d'impersonation repose sur un code one-time sécurisé :

1. Un collaborateur autorisé sélectionne un utilisateur SSO dans le dashboard et saisit une raison (obligatoire, minimum 10 caractères).
2. Saasy génère un code unique valable 2 minutes.
3. Le code est envoyé à ton URL d'impersonation (configurée dans les paramètres) en paramètre de requête.
4. Ton serveur reçoit le code, l'échange contre les données de l'utilisateur via l'API Saasy en fournissant le secret d'impersonation.
5. Ton serveur crée une session pour cet utilisateur et te connecte en tant que lui.
6. Chaque impersonation est loguée avec l'identité du collaborateur, l'utilisateur ciblé, la raison, la date et l'adresse IP.

Activer l'impersonation

1. Connecte-toi au dashboard Saasy.
2. Va dans Paramètres > Impersonation.
3. Coche la case Activer l'impersonation.
4. Configure l'URL d'impersonation — c'est l'URL de ton application qui recevra le code one-time.
5. Choisis la durée maximale de session (15, 30 ou 60 minutes).
6. Clique sur Enregistrer.

Saasy génère automatiquement un secret d'impersonation lors de l'activation. Copie-le et stocke-le dans les variables d'environnement de ton serveur.

Configurer ton serveur

Ton serveur doit exposer une route qui :

1. Reçoit le code one-time en query parameter.
2. L'échange auprès de l'API Saasy pour obtenir les données de l'utilisateur.
3. Crée une session temporaire pour cet utilisateur.

Endpoint d'échange

POST https://api.saasy.fr/api/w/auth/impersonate/exchange

Body JSON :

{
  "code": "le-code-recu-en-query-param",
  "secret": "ton-secret-d-impersonation"
}

L'endpoint d'échange exact est affiché dans Paramètres > Impersonation avec un bouton copier.

Exemple d'intégration

const express = require('express');
const axios = require('axios');
const app = express();

app.get('/auth/impersonate', async (req, res) => {
  const { code } = req.query;

  try {
    const response = await axios.post(
      'https://api.saasy.fr/api/w/auth/impersonate/exchange',
      {
        code,
        secret: process.env.SAASY_IMPERSONATION_SECRET,
      }
    );

    const user = response.data.data;

    // Créer une session temporaire pour l'utilisateur
    req.session.userId = user.externalId;
    req.session.email = user.email;
    req.session.impersonated = true;
    req.session.cookie.maxAge = user.maxDuration * 60 * 1000;

    res.redirect('/');
  } catch (error) {
    res.status(401).send('Code invalide ou expiré');
  }
});

Données retournées

L'échange du code retourne les informations de l'utilisateur SSO :

Gérer les permissions

Par défaut, seul le propriétaire de l'application peut utiliser l'impersonation. Pour autoriser d'autres collaborateurs :

1. Va dans Paramètres > Équipe.
2. Pour chaque collaborateur, coche la case Peut impersonner.

Impersonner un utilisateur

1. Va dans la page Utilisateurs de ton application.
2. Clique sur le bouton Impersonner à côté de l'utilisateur souhaité, ou ouvre la fiche utilisateur et clique sur le bouton Impersonner en haut de page.
3. Saisis une raison (minimum 10 caractères) expliquant pourquoi tu impersonnes cet utilisateur.
4. Clique sur Confirmer.
5. Un nouvel onglet s'ouvre avec l'URL d'impersonation et le code one-time.

Historique et audit

Chaque impersonation est automatiquement enregistrée. Consulte l'historique dans Paramètres > Impersonation :

• Effectué par : le collaborateur qui a initié l'impersonation.
• Utilisateur : l'utilisateur SSO impersonné.
• Raison : la justification fournie.
• Date : horodatage de l'impersonation.
• IP : adresse IP du collaborateur.

Bonnes pratiques

• Toujours fournir une raison explicite — "debug" ne suffit pas. Décris le problème que tu diagnostiques (ex : "L'utilisateur signale que la page de facturation ne charge pas depuis le 5 mars").
• Limiter la durée de session — Utilise la durée la plus courte possible. 15 minutes suffisent pour la plupart des diagnostics.
• Limiter les permissions — N'autorise l'impersonation qu'aux collaborateurs qui en ont réellement besoin (support technique, développeurs).
• Régénérer le secret régulièrement — Si un collaborateur quitte l'équipe ou si le secret est compromis, régénère-le immédiatement depuis les paramètres.
• Informer l'utilisateur — Dans certaines juridictions, tu es tenu d'informer l'utilisateur qu'un membre de ton équipe a accédé à son compte. Pense à afficher un bandeau dans ton application lorsque la session est impersonnée.

Dépannage

Le code est expiré

Le code one-time n'est valable que 2 minutes. Si ton serveur met trop de temps à l'échanger, le code expirera. Vérifie :

• Que ton URL d'impersonation est correcte et accessible.
• Que ton serveur échange le code immédiatement à la réception, sans délai (pas de file d'attente, pas de middleware lent).
• Que l'horloge de ton serveur est synchronisée (NTP).

Secret invalide

Si l'échange retourne une erreur 401 :

• Vérifie que tu utilises bien le secret de l'application concernée.
• Vérifie qu'il n'y a pas d'espace ou de caractère parasite dans ta variable d'environnement.
• Si le secret a été régénéré, mets à jour ta variable d'environnement avec la nouvelle valeur.

L'utilisateur n'est pas trouvé

L'impersonation ne fonctionne qu'avec les utilisateurs SSO. Si l'utilisateur ciblé n'a jamais été identifié via SSO (par exemple un utilisateur guest), le code ne pourra pas être échangé. Vérifie que l'utilisateur apparaît bien dans la liste des Utilisateurs avec un externalId.