Ensemble de jetons fédérés

L'ensemble de jetons fédérés est un type de secret stocké dans le Secret Vault de Logto, utilisé pour gérer en toute sécurité les jetons d’accès (Access tokens) et de rafraîchissement (Refresh tokens) émis par des fournisseurs d'identité tiers fédérés. Lorsqu'un utilisateur s'authentifie via un connecteur social ou SSO d’entreprise, Logto stocke les jetons émis dans le coffre. Ces jetons peuvent ensuite être récupérés pour accéder aux API tierces au nom de l'utilisateur, sans nécessiter une nouvelle authentification.

Activer le stockage des jetons fédérés

Connecteurs sociaux

info:

Cette fonctionnalité est uniquement disponible pour les connecteurs prenant en charge le stockage des jetons. Les connecteurs actuellement pris en charge incluent : GitHub, Google, Facebook, OAuth 2.0 standard et OIDC standard. La prise en charge d'autres connecteurs sera déployée progressivement.

1. Accédez à Console > Connecteurs > Connecteurs sociaux.
2. Sélectionnez le connecteur social pour lequel vous souhaitez activer le stockage des jetons fédérés.
3. Dans la page "Paramètres", activez l’option Stocker les jetons pour un accès API persistant.

Connecteurs SSO d’entreprise

info:

Le stockage des jetons est disponible pour tous les connecteurs OIDC d’entreprise.

1. Accédez à Console > SSO d’entreprise.
2. Sélectionnez le connecteur SSO d’entreprise pour lequel vous souhaitez activer le stockage des jetons fédérés.
3. Dans l’onglet "Expérience SSO", activez l’option Stocker les jetons pour un accès API persistant.

Assurez-vous d’enregistrer vos modifications.

Stockage des jetons

Une fois le stockage des jetons fédérés activé, Logto stocke automatiquement les jetons d’accès (Access tokens) et de rafraîchissement (Refresh tokens) émis par le fournisseur d'identité fédéré chaque fois qu'un utilisateur s'authentifie via un connecteur social ou SSO d’entreprise. Cela inclut :

• Connexion et inscription sociale
• Connexion et inscription SSO d’entreprise
• Liaison de compte social via l’Account API

Les jetons stockés sont attachés à l'identité sociale ou SSO d’entreprise de l'utilisateur, ce qui leur permet de récupérer les jetons ultérieurement pour accéder aux API sans nécessiter une nouvelle authentification.

Vérification du statut de stockage des jetons

Vous pouvez vérifier le statut de stockage des jetons fédérés d’un utilisateur dans la Console Logto :

1. Accédez à Console > Utilisateurs.
2. Cliquez sur l'utilisateur que vous souhaitez inspecter. Cela vous amènera à la page de détails de l'utilisateur.
3. Faites défiler jusqu'à la section Connexions. Cette zone répertorie toutes les connexions sociales et SSO d’entreprise associées à l'utilisateur.
4. Chaque entrée de connexion affiche une étiquette de statut de jeton indiquant si des jetons sont stockés pour cette connexion.
5. Cliquez sur l'entrée de connexion pour afficher plus de détails, y compris les métadonnées du jeton d’accès stocké et la disponibilité du jeton de rafraîchissement (le cas échéant).

Vous pouvez également vérifier les identités tierces de l'utilisateur et le statut de stockage des jetons via la Management API :

• GET /api/users/{userId}/identities/{target}?includeTokenSecret=true : Récupérer l'identité sociale d'un utilisateur et le statut de stockage des jetons associé à l'identité par un connecteur cible donné (par exemple, github, google, etc.).
• GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true : Récupérer l'identité SSO d’entreprise d'un utilisateur et le statut de stockage des jetons associé à l'identité par un ID de connecteur SSO donné.

Statut de stockage des jetons

• Actif : Le jeton d’accès est stocké et actif.
• Expiré : Le jeton d’accès est stocké mais a expiré. Si un jeton de rafraîchissement est disponible, il peut être utilisé pour obtenir un nouveau jeton d’accès.
• Inactif : Aucun jeton d’accès n’est stocké pour cette connexion. Cela peut se produire si l'utilisateur ne s'est pas authentifié via cette connexion ou si le stockage du jeton a été supprimé.
• Non applicable : Le connecteur ne prend pas en charge le stockage des jetons.

Métadonnées des jetons

Pour l'intégrité et la sécurité des données, tous les jetons sont chiffrés avant d'être stockés dans le Secret Vault. Les valeurs réelles des jetons ne sont accessibles qu'à l'utilisateur final avec la bonne autorisation. Les développeurs, quant à eux, ne peuvent récupérer que les métadonnées de l'ensemble de jetons pour comprendre l'état des jetons stockés sans exposer de contenu sensible.

• createdAt : L’horodatage de la première création de la connexion et du stockage initial de l’ensemble de jetons dans le Secret Vault.
• updatedAt : La dernière fois que l’ensemble de jetons a été mis à jour.
  • Si aucun jeton de rafraîchissement n’est disponible, cette valeur sera identique à createdAt.
  • Si un jeton de rafraîchissement est présent, cette valeur reflète la dernière fois où le jeton d’accès a été rafraîchi.
• hasRefreshToken : Indique si un jeton de rafraîchissement est disponible. Si le connecteur prend en charge l'accès hors ligne et que la requête d’autorisation est correctement configurée, Logto stocke le jeton de rafraîchissement lorsqu’il est émis par le fournisseur d'identité en même temps que le jeton d’accès. Lorsque le jeton d’accès expire et qu’un jeton de rafraîchissement valide existe, Logto tente automatiquement d’obtenir un nouveau jeton d’accès à l’aide du jeton de rafraîchissement stocké chaque fois que l'utilisateur demande l'accès au fournisseur connecté.
• expiresAt : L’heure d’expiration estimée du jeton d’accès en secondes. Elle est calculée à partir de la valeur expires_in renvoyée par le point de terminaison de jeton du fournisseur d'identité. (Ce champ n’est disponible que si le fournisseur inclut expires_in dans la réponse du jeton.)
• scope : La portée (Scope) du jeton d’accès, indiquant les permissions accordées par le fournisseur d'identité. Ceci est utile pour comprendre quelles actions peuvent être effectuées avec le jeton d’accès stocké. (Ce champ n’est disponible que si le fournisseur inclut scope dans la réponse du jeton.)
• tokenType : Le type du jeton d’accès, généralement "Bearer". (Ce champ n’est disponible que si le fournisseur inclut token_type dans la réponse du jeton.)

Récupération des jetons

Une fois le stockage des jetons activé et les jetons stockés en toute sécurité dans le Secret Vault de Logto, les utilisateurs finaux peuvent récupérer leurs jetons d’accès tiers depuis votre application cliente en intégrant l’Account API de Logto.

• GET /my-account/identities/:target/access-token : Récupérer le jeton d’accès pour une identité sociale en spécifiant le connecteur cible (par exemple, github, google).

• GET /my-account/sso-identities/:connectorId/access-token : Récupérer le jeton d’accès pour une identité SSO d’entreprise en spécifiant l’ID du connecteur.

info:

Découvrez comment activer et accéder à l’Account API en utilisant le jeton d’accès émis par Logto.

Rotation des jetons

Les points de terminaison de récupération des jetons renvoient :

• 200 OK : Si le jeton d’accès est récupéré avec succès et est toujours valide.
• 404 Not Found : Si l'utilisateur ne possède pas d'identité sociale ou SSO d’entreprise associée à la cible ou à l’ID de connecteur spécifié, ou si le jeton d’accès n’est pas stocké.
• 401 Unauthorized : Si le jeton d’accès est expiré.

Si le jeton d’accès est expiré et qu’un jeton de rafraîchissement est disponible, Logto tente automatiquement de rafraîchir le jeton d’accès et renvoie le nouveau jeton d’accès dans la réponse. Le stockage du jeton dans le Secret Vault est également mis à jour avec le nouveau jeton d’accès et ses métadonnées.

Suppression du stockage des jetons

Le stockage des jetons fédérés est directement lié à chaque connexion sociale ou SSO d’entreprise de l’utilisateur. Cela signifie que l’ensemble de jetons stocké sera automatiquement supprimé dans les cas suivants :

• L'identité sociale ou SSO d’entreprise associée est supprimée du compte de l'utilisateur.
• Le compte utilisateur est supprimé de votre tenant.
• Le connecteur social ou SSO d’entreprise est supprimé de votre tenant.

Révocation des jetons

Vous pouvez également supprimer manuellement l’ensemble de jetons tiers d’un utilisateur pour révoquer l’accès :

• Depuis la Console : Accédez à la page de détails de l'identité de l'utilisateur. Faites défiler jusqu'à la section Jeton d’accès (si le stockage des jetons est disponible) et cliquez sur le bouton Supprimer les jetons à la fin de la section.
• Via la Management API :
  • DELETE /api/secret/:id : Supprimez un secret spécifique par son ID, qui peut être obtenu à partir des détails de l'identité utilisateur.

La révocation de l’ensemble de jetons obligera l'utilisateur à se réauthentifier auprès du fournisseur tiers pour obtenir un nouveau jeton d’accès avant de pouvoir accéder à nouveau aux API tierces.

Réauthentification et renouvellement des jetons

Dans les scénarios où un jeton d’accès stocké a expiré ou lorsqu'une application doit demander des portées (Scopes) API supplémentaires, les utilisateurs finaux peuvent se réauthentifier auprès du fournisseur tiers pour obtenir un nouveau jeton d’accès — sans avoir besoin de se connecter à nouveau à Logto. Cela peut être réalisé via l’API de vérification sociale de Logto, qui permet aux utilisateurs de relancer un flux d’autorisation sociale fédérée et de mettre à jour leur ensemble de jetons stocké.

remarque:

La relance de l’autorisation fédérée est actuellement limitée aux connecteurs sociaux. Pour les connecteurs SSO d’entreprise, la réauthentification et le renouvellement des jetons nécessitent que l'utilisateur initie à nouveau un flux d’authentification complet Logto, car la réautorisation directe auprès du fournisseur SSO d’entreprise n’est pas prise en charge après la connexion.

1. L'utilisateur initie une demande de vérification sociale en appelant le point de terminaison POST /api/verification/social. L'utilisateur peut spécifier des portées personnalisées pour demander des permissions supplémentaires au fournisseur tiers.

   curl -X POST https://<your-logto-domain>/api/verification/social \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
       "state": "<state>",
       "connectorId": "<logto_connectorId>",
       "redirectUri": "<redirect_uri>",
       "scope": "<custom_scope>"
     }'
   • authorization header : Le jeton d’accès de l'utilisateur émis par Logto.
   • connectorId : L’ID du connecteur social dans Logto.
   • redirectUri : L’URI vers laquelle rediriger l'utilisateur après l’authentification. Vous devrez enregistrer cet URI dans les paramètres de l’application du fournisseur.
   • scope : (Optionnel) Portées personnalisées pour demander des permissions supplémentaires au fournisseur tiers. Si non spécifié, les portées par défaut configurées dans le connecteur seront utilisées.

2. Logto crée un nouvel enregistrement de vérification sociale et retourne l’ID de vérification sociale ainsi que l’URL d’autorisation pour rediriger l'utilisateur vers le fournisseur tiers pour l’authentification.

   La réponse ressemblera à ceci :

   {
     "verificationRecordId": "<social_verification_id>",
     "authorizationUri": "<authorization_url>",
     "expiresAt": "<expiration_time>"
   }

3. Redirigez l'utilisateur vers l’URL d’autorisation. L'utilisateur s’authentifie auprès du fournisseur tiers et accorde les permissions.

4. Le fournisseur tiers redirige l'utilisateur vers votre application cliente avec un code d’autorisation.

5. Gérez le callback d’autorisation en transmettant le code d’autorisation au point de terminaison de vérification de Logto :

   curl -X POST https://<your-logto-domain>/api/verification/social/verify \
     -H "Authorization: Bearer <access_token>" \
     -d '{
       "verificationRecordId": "<social_verification_id>",
       "connectorData": {
         "code": "<authorization_code>",
         "state": "<state>",
         "redirectUri": "<redirect_uri>"
       }
     }'
   • authorization header : Le jeton d’accès de l'utilisateur émis par Logto.
   • verificationRecordId : L’ID de vérification sociale retourné à l’étape précédente.
   • connectorData : Le code d’autorisation et toute autre donnée retournée par le fournisseur tiers lors du callback.
   remarque:

   N’oubliez pas de valider le paramètre state pour prévenir les attaques CSRF.

6. Logto vérifie le code d’autorisation et l’échange contre un nouveau jeton d’accès et un jeton de rafraîchissement auprès du fournisseur tiers, puis retourne l’ID de vérification sociale dans la réponse.

7. Enfin, mettez à jour le stockage des jetons de l'utilisateur en appelant le point de terminaison PATCH /my-account/identities/:target/access-token avec l’ID de vérification sociale :

   curl -X PATCH https://<your-logto-domain>/my-account/identities/<target>/access-token \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{
       "socialVerificationId": "<social_verification_id>"
     }'
   • authorization header : Le jeton d’accès de l'utilisateur émis par Logto.
   • socialVerificationId : L’ID de vérification sociale vérifié retourné à l’étape précédente.

   Cela mettra à jour l’ensemble de jetons de l'utilisateur dans le Secret Vault de Logto avec le nouveau jeton d’accès et le jeton de rafraîchissement, permettant à l'utilisateur d’accéder aux API tierces sans avoir à se reconnecter à Logto.

   Le jeton d’accès mis à jour sera retourné.