Le type d'association OAuth est compatible avec deux flux OAuth 2.0 standards dans l'industrie : le flux implicite et le code d'autorisation. Dans le flux de code implicite, Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Une fois la connexion établie, vous renvoyez un jeton d'accès de longue durée à Google. Ce jeton d'accès est ensuite inclus dans chaque requête envoyée de l'Assistant à votre action.
Nous vous recommandons d'associer OAuth lorsque les conditions suivantes s'appliquent:
- Vous disposez déjà d'un serveur OAuth 2.0, et vous ne pouvez pas étendre votre point de terminaison d'échange de jetons afin d'accepter les protocoles d'association automatique et de création de comptes à partir d'un jeton d'ID (c'est-à-dire ajouter les paramètres
intent=getetintent=createdans les requêtes adressées à ce point de terminaison).
Pour vérifier que l'association OAuth est la solution adaptée à vos besoins, consultez la page Choisir votre type d'association de compte.
Termes clés
Avant de découvrir le fonctionnement de l'association OAuth, familiarisez-vous avec les termes suivants:
user.verificationStatus:propriété définie par le système pour indiquer si la session en cours comporte un utilisateur validé.user.accountLinkingStatus:propriété définie par le système pour indiquer si l'utilisateur de la session en cours est associé à une identité.Scène système d'association de comptes:scène prédéfinie qui implémente le flux de confirmation pour l'association de comptes et peut être personnalisée pour répondre à des cas d'utilisation spécifiques.
Flux avec code d'autorisation:au cours de ce flux OAuth 2.0, Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Si la connexion aboutit, votre service crée un code d'autorisation, puis le renvoie à Google. Google envoie ce code d'autorisation à votre point de terminaison d'échange de jetons, qui vérifie l'authenticité du code et renvoie un jeton d'accès et un jeton d'actualisation.
Ce flux nécessite deux points de terminaison:
- Point de terminaison d'autorisation:point de terminaison chargé de rechercher ou d'obtenir le consentement des utilisateurs pour l'accès aux données. Ce point de terminaison effectue les opérations suivantes :
- Présente l'interface utilisateur de connexion aux utilisateurs qui ne sont pas déjà connectés.
- Consignent le consentement à l'accès demandé sous la forme d'un code d'autorisation de courte durée.
- Point de terminaison d'échange de jetons:ce point de terminaison est utilisé pour obtenir des chaînes chiffrées appelées jetons qui autorisent l'utilisateur de l'action à accéder à votre service. Ce point de terminaison est responsable de deux types d'échanges :
- Échange un code d'autorisation contre un jeton d'actualisation de longue durée et un jeton d'accès de courte durée. Cet échange se produit lorsque l'utilisateur passe par le flux d'association de compte.
- Échange un jeton d'actualisation de longue durée contre un jeton d'accès de courte durée. Cet échange se produit lorsque Google a besoin d'un nouveau jeton d'accès, car celui-ci a expiré.
- Point de terminaison d'autorisation:point de terminaison chargé de rechercher ou d'obtenir le consentement des utilisateurs pour l'accès aux données. Ce point de terminaison effectue les opérations suivantes :
Flux de code implicite:lors de ce flux OAuth 2.0, Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Si la connexion aboutit, vous renvoyez un jeton d'accès de longue durée à Google. Ce jeton d'accès est ensuite inclus dans chaque requête envoyée de l'Assistant à votre action. Ce flux ne nécessite qu'un point de terminaison d'autorisation.
Jeton d'accès:jeton qui autorise votre service à accéder à certaines données d'un utilisateur. Les jetons d'accès sont associés à chaque utilisateur et ne doivent pas être devinés.
Jeton d'actualisation:jeton échangé contre un nouveau jeton d'accès lorsqu'un jeton d'accès de courte durée a expiré.
Fonctionnement
Cette section décrit le flux général du code d'autorisation OAuth et les flux implicites. La section suivante, Flux d'association OAuth, décrit les différents flux pouvant survenir avec OAuth.
Le flux avec code d'autorisation peut être résumé comme suit:
- Votre action demande à l'utilisateur s'il souhaite associer son compte à votre service.
- Une fois que l'utilisateur a accepté d'associer des comptes, Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Si le flux démarre sur un appareil vocal uniquement pour une action, Google transfère cette exécution sur un téléphone.
- L'utilisateur se connecte (s'il n'est pas déjà connecté) et autorise Google à accéder à ses données avec votre API (s'il ne l'a pas déjà fait).
- Votre service crée un code d'autorisation et le renvoie à Google en redirigeant le navigateur de l'utilisateur vers Google à l'aide du code d'autorisation joint à la requête.
- Google envoie le code d'autorisation à votre point de terminaison d'échange de jetons, qui vérifie l'authenticité du code et renvoie un jeton d'accès et un jeton d'actualisation. Le jeton d'accès est un jeton de courte durée que votre service accepte comme identifiants pour accéder aux API. Le jeton d'actualisation est un jeton de longue durée que Google peut stocker et utiliser pour acquérir de nouveaux jetons d'accès lorsqu'ils expirent.
- Une fois que l'utilisateur a terminé le flux d'association de comptes, chaque requête ultérieure envoyée de l'Assistant à votre webhook de fulfillment contient un jeton d'accès.
Le flux de code implicite peut être résumé comme suit:
- Votre action demande à l'utilisateur s'il souhaite associer son compte à votre service.
- Une fois que l'utilisateur a accepté d'associer des comptes, Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur.
- L'utilisateur se connecte (s'il n'est pas déjà connecté) et autorise Google à accéder à ses données avec votre API (s'il ne l'a pas déjà fait).
- Votre service crée un jeton d'accès et le renvoie à Google en redirigeant le navigateur de l'utilisateur vers Google à l'aide du jeton d'accès associé à la requête.
- Une fois que l'utilisateur a terminé le flux d'association de comptes, Google appelle les API de votre service et associe le jeton d'accès à chaque requête. Votre service vérifie que le jeton d'accès autorise Google à accéder à l'API, puis termine l'appel d'API.
Voici le flux de base avec code d'autorisation:
- Votre action demande à l'utilisateur s'il souhaite associer son compte à votre service.
- Une fois que l'utilisateur a accepté d'associer des comptes, Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Si le flux démarre sur un appareil vocal uniquement pour une action, Google transfère cette exécution sur un téléphone.
- L'utilisateur se connecte (s'il n'est pas déjà connecté) et autorise Google à accéder à ses données avec votre API (s'il ne l'a pas déjà fait).
- Votre service crée un code d'autorisation et le renvoie à Google en redirigeant le navigateur de l'utilisateur vers Google à l'aide du code d'autorisation de courte durée joint à la requête.
- Google envoie le code d'autorisation à votre point de terminaison d'échange de jetons, qui vérifie l'authenticité du code et renvoie un jeton d'accès et un jeton d'actualisation. Le jeton d'accès est un jeton de courte durée que votre service accepte comme identifiants pour accéder aux API. Le jeton d'actualisation est un jeton de longue durée que Google peut stocker et utiliser pour acquérir de nouveaux jetons d'accès lorsqu'ils expirent.
- Une fois que l'utilisateur a terminé le flux d'association de comptes, chaque requête ultérieure envoyée de l'Assistant à votre webhook de fulfillment contient un jeton d'accès.
Flux d'association OAuth
Cette section passe en revue les différents flux pouvant être liés à l'association OAuth.
Chaque flux contient ces étapes courantes après que l'utilisateur a appelé votre action:
Dans le flux ci-dessus, vous passerez à la scène du système d'association de comptes et fournirez une justification personnalisée. L'Assistant demande à l'utilisateur s'il souhaite associer son compte à votre service et lui présente un écran contenant les autorisations demandées. Lorsque l'utilisateur donne son consentement, Google le redirige ensuite vers le point de terminaison d'autorisation de votre service dans le navigateur. L'utilisateur se connecte (ou, selon votre configuration, crée un compte) et autorise votre action à accéder à ses données.
Les flux qui suivent ce point diffèrent selon que vous avez implémenté ou non le flux implicite ou le flux de code d'autorisation. Ces flux sont décrits dans les sections suivantes.
Flow 1: l'utilisateur se connecte avec un flux implicite
Une fois que l'utilisateur s'est connecté et que ses identifiants ont été validés, votre service crée un jeton d'accès de longue durée et le renvoie à Google. À ce stade, l'identité de l'utilisateur dans votre action est liée au compte avec lequel il s'est connecté, et le jeton d'accès est associé à chaque appel d'API effectué par Google vers les API de votre service.
Flux 2: l'utilisateur se connecte avec un flux avec code d'autorisation
Une fois que l'utilisateur s'est connecté et que ses identifiants ont été validés, votre service crée un code d'autorisation et le renvoie à Google.
Ce code d'autorisation est envoyé au point de terminaison d'échange de jetons, qui renvoie à la fois un jeton d'accès et un jeton d'actualisation. À ce stade, l'identité de l'utilisateur dans votre action est liée au compte avec lequel il s'est connecté, et chaque requête ultérieure envoyée par l'Assistant à votre traitement contient un jeton d'accès.