Un magic link peut fonctionner parfaitement et pourtant ouvrir le mauvais espace client. Le problème apparaît lorsqu’une même personne appartient à plusieurs organisations, lorsqu’un rôle change pendant une session ou lorsqu’un backend confond encore identité authentifiée et action autorisée. La fluidité du passwordless ne corrige aucune de ces frontières à elle seule.
La première décision n’est donc pas le choix d’un composant visuel. Stytch sépare Consumer Authentication et B2B Authentication, puis propose dans son modèle B2B des Organizations, des Members et deux parcours d’entrée : la découverte d’organisations ou la connexion dans un tenant déjà connu. Ce choix structure les identifiants, les SDK, les redirections et les règles de session.
Contre-intuitivement, le point le plus délicat concerne la révocation. Stytch peut remettre un session_token opaque, vérifié par appel distant, et un session_jwt signé, vérifiable localement. Le second réduit la latence, mais sa validité cryptographique peut survivre quelques minutes à la révocation de la session sous-jacente. Cette fenêtre doit devenir une décision explicite par endpoint.
Le cadrage doit rendre ce contrat vérifiable. Pour relier ensuite Stytch au produit, au CRM, au billing et aux APIs internes, notre accompagnement d’intégrateur Stytch API traite l’implémentation et son exploitation. Les principes transverses restent regroupés dans notre expertise d’intégration API sur mesure.
Choisir Consumer Authentication ou B2B Authentication
Consumer Authentication correspond à une application où l’identité principale est un utilisateur. B2B Authentication ajoute une frontière de tenant : une Organization porte ses Members, ses méthodes de connexion et ses politiques. Utiliser l’API Consumer puis recréer les organisations dans une table applicative peut sembler plus rapide, mais cette simplification reporte toute la complexité sur les invitations, le SSO, le provisioning et l’autorisation.
La décision dépend du produit, pas de la taille actuelle du portefeuille clients. Un service B2C avec des groupes occasionnels peut rester Consumer. Un SaaS où chaque entreprise administre ses membres, impose des méthodes de connexion ou attend SSO et SCIM relève naturellement du modèle B2B. Le critère utile est la capacité du client à gouverner un périmètre isolé, pas le vocabulaire commercial affiché dans l’interface.
Changer de modèle après plusieurs intégrations coûte plus qu’une migration d’écran. Les IDs, les relations, les sessions et les permissions doivent être repris. Le cadrage initial doit donc produire une décision documentée : unité de tenant, règle d’appartenance, cas d’un utilisateur multi-organisation, identité externe stable et responsabilités laissées au backend.
Modéliser Organizations, Members et comptes métier
Une Organization représente le tenant dans Stytch. Elle peut porter un nom, un slug, des domaines autorisés et des paramètres d’authentification. Un Member représente une personne dans cette organisation, avec son statut, ses facteurs et ses rôles. Ce modèle ne dispense pas le produit de conserver son propre compte client, son abonnement, ses entités juridiques ou ses restrictions fonctionnelles.
Le mapping robuste emploie des identifiants stables dans les deux sens. L’Organization référence le tenant métier ; le Member référence l’utilisateur interne dans le contexte approprié. L’email sert au contact et à certains parcours de découverte, mais il ne doit pas devenir l’unique clé de rapprochement. Une adresse peut changer, être partagée ou appartenir à plusieurs organisations.
Il faut aussi définir qui fait foi pour chaque attribut. Stytch fait foi pour la session et les facteurs qu’il a vérifiés. Le produit fait généralement foi pour l’abonnement, le statut commercial et les droits propres au métier. Un IdP enterprise peut faire foi pour le cycle d’emploi. Sans ce tableau de responsabilités, chaque synchronisation risque de réécrire une information plus récente détenue ailleurs.
- Organization : tenant d’authentification et paramètres d’accès propres au client.
- Member : identité d’une personne à l’intérieur de cette organisation.
- Compte métier : client, abonnement, contrat, état opérationnel et données du produit.
- Permission : décision calculée au moment de l’action, à partir du rôle et du contexte courant.
Distinguer Discovery et connexion liée à une organisation
Le parcours Discovery convient à une page de connexion centralisée. Le Member s’authentifie d’abord sans choisir d’Organization. Le résultat intermédiaire permet ensuite de retrouver les organisations auxquelles il appartient, celles pour lesquelles une invitation existe ou celles qu’il peut rejoindre selon la configuration. La session complète n’est obtenue qu’après le choix ou la création du tenant.
Le parcours lié à une organisation s’applique quand le contexte est déjà connu, par exemple grâce à un sous-domaine, un slug ou une invitation. L’application fournit alors l’Organization concernée dès l’envoi du magic link ou de l’OTP. Après authentification, le backend reçoit directement la session du Member dans ce tenant.
Une erreur fréquente consiste à transformer Discovery en raccourci : prendre la première organisation renvoyée et y connecter automatiquement l’utilisateur. Ce choix produit des incidents rares mais graves lorsque l’ordre change ou lorsqu’un consultant intervient chez plusieurs clients. L’écran de sélection, l’expiration de l’état intermédiaire et le retour après erreur font partie du contrat de sécurité.
Le changement d’organisation mérite son propre scénario. Il ne doit pas seulement modifier un identifiant dans le frontend. Une nouvelle session contextualisée, ou un échange explicitement prévu, doit conduire le backend à recalculer le tenant, le rôle et les ressources visibles. Les caches applicatifs doivent être vidés ou partitionnés par Organization.
Sécuriser un magic link au-delà de sa consommation unique
Stytch documente ses magic links comme des jetons uniques et à durée limitée. Leur première consommation produit une authentification ; une seconde tentative ne doit pas recréer une session. Cette propriété réduit le risque de rejeu, mais elle ne protège pas à elle seule la redirection, le choix du tenant, le stockage des cookies ni la politique d’autorisation après connexion.
Les scanners de sécurité des messageries constituent un signal faible important. Certains ouvrent les URLs avant l’utilisateur afin de les analyser. Une implémentation qui consomme immédiatement le jeton au premier chargement peut créer une expérience où le lien semble déjà utilisé. Stytch prévoit des protections pour ce contexte, mais la recette doit quand même inclure les clients email et les redirections réellement utilisés par les entreprises ciblées.
Il faut distinguer l’événement « lien envoyé », l’événement « facteur authentifié » et l’événement « session créée ». Un support qui ne voit que l’envoi conclura à tort que l’utilisateur est connecté. Les journaux doivent conserver le request ID, la méthode, l’Organization attendue, le résultat de l’échange et l’erreur fonctionnelle affichée, sans stocker le jeton secret.
Arbitrer session token et session JWT
Après authentification, Stytch peut renvoyer deux représentations de la même session. Le session_token est opaque : le backend doit appeler Stytch pour le valider. Cette requête ajoute une dépendance réseau et de la latence, mais elle vérifie l’état courant de la session. Une révocation ou une expiration devient donc visible immédiatement lors du prochain contrôle réussi.
Le session_jwt est signé et se valide localement à partir du JWKS du Project. Cette option évite un appel distant sur chaque requête. Stytch documente une durée de vie fixe de cinq minutes pour ce JWT, indépendamment de la durée de la session sous-jacente. Pendant cette fenêtre, le token peut encore passer la validation locale même si la session a été révoquée.
Il n’existe pas de choix universel. Une consultation peu sensible peut accepter la fenêtre locale. Une exportation, un changement de coordonnées bancaires, une invitation d’administrateur ou la suppression d’une ressource peuvent justifier une validation distante au moment exact de l’action. Le bon livrable est une matrice d’endpoints qui indique la méthode, le risque, le fallback et le comportement en cas d’indisponibilité.
La rotation des clés complète ce dispositif. Le backend doit sélectionner la clé grâce au kid, mettre en cache le JWKS et accepter la période où ancien et nouveau jeux coexistent. Réinitialiser le client SDK à chaque requête ou figer une clé dans la configuration crée respectivement un coût inutile ou une panne future. La rotation doit être testée, pas seulement supposée prise en charge.
Matrice de décision pour valider chaque endpoint
Pour chaque endpoint, la fiche note en entrée le jeton accepté, en sortie la décision métier, la dépendance Stytch sollicitée et la journalisation conservée. Une lecture de tableau de bord, une invitation d’administrateur et une suppression de données ne peuvent pas partager la même tolérance à un droit ancien.
La même fiche attribue les responsabilités, fixe le seuil de latence, prévoit le repli en cas d’indisponibilité et décrit le monitoring attendu. Ces éléments permettent de refuser une action plutôt que de transformer silencieusement une panne d’authentification en autorisation par défaut.
- À faire d’abord : classer la sensibilité de l’action et la fraîcheur maximale acceptable du droit.
- À choisir ensuite : valider le JWT localement, interroger le session token ou combiner les deux selon le risque.
- À différer : l’optimisation de latence tant que les métriques ne montrent pas que l’appel distant gêne réellement le parcours.
- À refuser : une politique qui autorise par défaut lorsque Stytch, le JWKS ou le référentiel métier ne répond pas.
Appliquer le RBAC au bon endroit
Le RBAC Stytch structure une politique avec des rôles, des resources et des actions. Une permission relie une action à une ressource ; plusieurs rôles peuvent contribuer aux permissions d’un Member. Ce vocabulaire doit être traduit dans le métier : « administrateur » n’a de sens que si les actions réellement accordées sont connues et versionnées.
La vérification décisive reste côté serveur. Le frontend peut masquer un bouton pour améliorer l’expérience, mais il ne protège pas l’endpoint. Le backend authentifie la session, précise l’Organization et vérifie la permission avant l’effet. Les contrôles applicatifs supplémentaires restent nécessaires lorsque le droit dépend aussi du propriétaire d’un dossier, d’un plafond, d’un statut ou d’une règle contractuelle.
Un rôle large est souvent plus simple au lancement, puis devient une dette invisible. La bonne recette inclut donc un Member avec plusieurs rôles, un retrait de rôle pendant une session et une action inconnue de la politique. Elle vérifie aussi qu’un rôle valide dans l’Organization A n’ouvre aucune ressource dans l’Organization B.
Garder une source de vérité hors du fournisseur d’identité
Une plateforme d’authentification doit connaître assez de contexte pour produire une session utile, mais elle ne doit pas absorber tout le profil produit. L’abonnement, les règles de facturation, l’historique des changements et les données sensibles appartiennent généralement à des référentiels spécialisés. Les recopier dans des métadonnées ou des claims crée une seconde vérité difficile à corriger.
La projection minimale contient les identifiants nécessaires au rapprochement et les informations d’autorisation compactes. Le backend relit la donnée métier quand sa fraîcheur conditionne une action. Cette discipline évite qu’un changement d’offre reste sans effet parce qu’un ancien JWT porte encore un rôle, ou qu’une mise à jour CRM écrase une décision prise dans l’administration du produit.
Chaque écriture doit annoncer son sens. Une valeur absente signifie-t-elle « conserver », « effacer » ou « inconnue » ? Une désactivation du compte métier révoque-t-elle toutes les sessions ? Un Member supprimé doit-il aussi fermer les données du produit ? Ces questions précèdent le code, car leur réponse dépend du contrat, de la sécurité et parfois d’obligations de conservation distinctes.
Erreurs fréquentes : reprendre le parcours passwordless sans l’aggraver
L’authentification possède plusieurs états qui ne se résument pas à succès ou échec : lien expiré, lien déjà consommé, Organization introuvable, Member non autorisé, MFA requis, session expirée, permission refusée, JWKS non rafraîchi ou service distant indisponible. Une seule page « une erreur est survenue » transforme ces situations en tickets difficiles à diagnostiquer.
Le frontend affiche un message sûr et une prochaine action ; le backend conserve le contexte technique non sensible. Le request ID Stytch est précieux pour rapprocher une erreur avec le fournisseur. Il faut y ajouter la corrélation interne, l’Organization attendue, l’étape du parcours et la catégorie d’échec, mais jamais le magic link, le session token ou un secret.
Les retries automatiques doivent rester rares sur les opérations d’authentification. Réenvoyer un email, échanger deux fois un lien ou créer plusieurs Members peut amplifier l’incident. La reprise lit d’abord l’état courant, puis décide si elle peut répéter l’appel, proposer un nouvel envoi ou remettre le dossier au support. L’idempotence protège l’effet métier, pas seulement la requête HTTP.
Introduire invitations, JIT, SSO ou SCIM sans doublon
Un SaaS commence souvent par magic links, puis ajoute des invitations, le SSO et le provisioning. Ces méthodes doivent converger vers la même identité et la même membership. Si l’email SSO crée un second Member alors qu’une invitation existe déjà, l’entreprise obtient deux historiques, deux rôles et un départ impossible à appliquer proprement.
Le Just-in-Time provisioning simplifie l’entrée quand un domaine ou une connexion autorise l’adhésion. Il déplace toutefois la décision vers les règles d’éligibilité. Un domaine partagé, un sous-traitant ou une acquisition peut rendre une règle autrefois sûre trop large. Le JIT doit conserver une trace de la règle appliquée et permettre une exception explicite.
SCIM traite le cycle de provisioning depuis l’IdP ; le SSO traite l’authentification. Ils ne sont pas interchangeables. Un utilisateur peut encore disposer d’une session après une modification de rôle si le flux de déprovisioning, la révocation et les contrôles backend ne sont pas coordonnés. La migration enterprise doit inclure la fermeture, pas seulement le premier login réussi.
Jouer les contre-tests qui ouvrent les angles morts
Une recette pertinente commence par les contradictions. Elle ne se contente pas de créer une Organization, d’envoyer un lien et d’afficher une page privée. Elle force les états que le support rencontrera avec moins de contexte et davantage d’urgence.
- Multi-organisation : le Member choisit explicitement le tenant et ne voit aucune donnée du contexte précédent.
- Consommation unique : la seconde ouverture du magic link ne produit ni nouvelle session ni message ambigu.
- Rôle retiré : une action sensible est refusée selon la stratégie de fraîcheur documentée.
- Session révoquée : le session token échoue immédiatement et le JWT local suit la fenêtre assumée.
- Rotation JWKS : le nouveau
kiddéclenche un rafraîchissement contrôlé sans panne générale. - IdP dégradé : l’application refuse ou limite les actions selon une politique définie, sans inventer un droit.
Chaque cas décrit un état initial, une action, un résultat attendu et une preuve observable. La sortie du pilote exige aussi qu’une personne du support retrouve le dossier à partir d’un ticket, explique la décision et applique la procédure sans accès aux secrets ni correction directe en base.
Rendre chaque accès explicable par le support
Les métriques de connexion donnent une vision incomplète. Il faut suivre les échecs par étape, les échanges Discovery non terminés, les Members sans tenant métier, les refus RBAC, les sessions révoquées encore présentées, les erreurs de JWKS et le délai entre retrait de droit et refus effectif. Ces mesures relient la sécurité à une expérience concrète.
Le tableau de bord sépare panne fournisseur, erreur de configuration, donnée incohérente et refus attendu. Un pic de 403 peut révéler une attaque, une politique cassée ou simplement un frontend resté en retard. Sans cette distinction, l’équipe hésite entre rétablir, bloquer et corriger les permissions.
La procédure d’exploitation commence par le compte et l’Organization, puis remonte vers Member, facteur, session et permission. Elle prévoit révocation ciblée, révocation globale, correction de membership et escalade. Elle indique également ce qui ne doit jamais être fait : réactiver un compte sans propriétaire métier, contourner le RBAC ou copier un token dans un ticket.
Savoir quand le projet exige un intégrateur Stytch API
Une équipe produit peut configurer seule un parcours simple lorsque l’identité reste isolée et que les droits sont peu sensibles. L’intervention devient utile dès que Stytch doit dialoguer avec un CRM, un billing, un annuaire, plusieurs backends ou un modèle multi-tenant existant. Le coût principal n’est alors plus le formulaire de connexion, mais la cohérence des décisions distribuées.
Un projet d’intégration Stytch B2B doit produire un contrat d’identité, une matrice de validation des sessions, une politique RBAC, des contre-tests et une procédure d’exploitation. Le premier lot peut rester étroit : une méthode passwordless, deux Organizations, un rôle et une action sensible suffisent pour valider l’architecture.
Il vaut mieux différer SSO, SCIM ou plusieurs facteurs tant que le mapping Member-tenant reste ambigu. À l’inverse, il faut refuser une mise en production si une organisation peut être choisie implicitement, si un rôle retiré reste sans contrôle connu ou si le support ne sait pas révoquer et expliquer une session.
Guides complémentaires pour approfondir l’architecture
Les sujets suivants prolongent les décisions Stytch sans remplacer la documentation du Project ni la recette sur l’application réelle.
Isoler identités, droits et données entre tenants
L’analyse du multi-tenant SaaS approfondit le cloisonnement des caches, des ressources et des traces lorsqu’une même identité intervient dans plusieurs organisations.
Elle fournit les contrôles à rejouer lors d’un changement de tenant, d’une lecture mise en cache et d’un traitement asynchrone qui doit toujours transporter l’Organization correcte.
Fermer réellement une session compromise
L’analyse de la révocation de tokens aide à distinguer expiration, révocation, invalidation locale et contrôles supplémentaires sur les actions critiques.
Cette distinction permet de documenter le délai maximal accepté entre le retrait d’un accès et son refus effectif sur chaque catégorie d’endpoint.
Choisir le protocole d’un SSO entreprise
La comparaison SAML ou OpenID Connect précise les frontières de fédération lorsqu’un client B2B impose son fournisseur d’identité.
Elle aide aussi à séparer le protocole de connexion, la découverte de l’Organization et le cycle de provisioning afin de ne pas demander au SSO de résoudre les trois sujets.
Automatiser arrivées, mobilités et départs
Le dossier SCIM et cycle de vie des utilisateurs complète le login par le provisioning et le déprovisioning depuis les annuaires d’entreprise.
Il prépare les cas de mobilité, de départ et de groupe modifié, puis vérifie que la membership et les sessions suivent réellement la décision de l’IdP.
Conclusion : traiter la session comme une décision métier
Stytch simplifie l’authentification, mais la qualité du résultat dépend des frontières posées autour du service. Le produit Consumer ou B2B, le modèle Organization-Member, le parcours Discovery et la source des droits doivent être décidés avant que l’interface ne masque les ambiguïtés.
Le choix entre session token et JWT illustre cette responsabilité. La validation locale améliore la latence ; la validation distante reflète plus vite une révocation. Une architecture solide ne choisit pas un jeton par préférence technique : elle associe chaque action à une exigence de fraîcheur, un fallback et une preuve.
Si le projet doit relier Stytch à plusieurs référentiels ou sécuriser un SaaS multi-tenant, notre expertise Stytch pour les parcours B2B peut cadrer le premier lot, ses contre-tests et sa mise en exploitation. Le périmètre reste borné tant que le retrait d’un droit n’est pas aussi démontrable que son attribution.
Pour construire cette chaîne avec vos équipes produit, sécurité et support, notre accompagnement d’intégrateur Stytch API cadre le middleware, la recette et l’observabilité. Le passage en production reste conditionné à une révocation mesurable sur chaque parcours critique.
