Associer un compte avec OAuth

Le type d'association OAuth est compatible avec deux flux OAuth 2.0 standards dans l'industrie : les flux de code implicite et d'autorisation.

Dans le flux de code implicite, Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Une fois connecté, vous renvoyez un jeton d'accès de longue durée à Google. Ce jeton d'accès est désormais inclus dans chaque requête envoyée à l'action par l'Assistant.

Dans le flux de code d'autorisation, vous avez besoin de deux points de terminaison:

• Le point de terminaison authorization, qui consiste à présenter l'interface de connexion aux utilisateurs qui ne sont pas déjà connectés et à enregistrer le consentement demandé pour l'accès demandé sous la forme d'un code d'autorisation temporaire.
• Le point de terminaison d'échange de jetons, responsable de deux types d'échanges :
  1. É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 suit la procédure d'association de comptes.
  2. É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é.

Bien que le flux de code implicite soit plus facile à mettre en œuvre, Google recommande que les jetons d'accès émis à l'aide du flux implicite n'expirent jamais, car l'expiration du jeton avec le flux implicite oblige l'utilisateur à associer de nouveau son compte. Si vous avez besoin d'un jeton expiré pour des raisons de sécurité, envisagez plutôt d'utiliser le flux de code d'autorisation.

Remarque :Choisissez le flux OAuth 2.0 que vous souhaitez implémenter. Si nécessaire, le contenu de ce guide est actualisé en fonction de votre choix.

Code d'autorisation Flux implicite

Implémenter l'association de comptes OAuth

Remarque :Si vous implémentez l'association de comptes pour gérer les informations financières, notez que des règles supplémentaires peuvent s'appliquer à votre action. L'examen de l'association des comptes avec vos comptes pour nous fournir des informations financières peut prendre jusqu'à six semaines. Tenez compte de ce délai dans la planification de votre déploiement. Pour faciliter le processus d'examen, assurez-vous de respecter les Règles concernant les services financiers avant d'envoyer votre action pour examen.

Configurer le projet

Pour configurer votre projet afin d'utiliser l'association OAuth, procédez comme suit:

1. Ouvrez la console Actions et sélectionnez le projet que vous souhaitez utiliser.
2. Cliquez sur l'onglet Développer et sélectionnez Associer un compte.
3. Activez le bouton à côté de Association de comptes.
4. Dans la section Création de compte, sélectionnez Non, je ne veux autoriser la création de comptes que sur mon site Web.

5. Dans Type d'association, sélectionnez OAuth et Implicit.

   

6. Dans Informations sur le client:

   • Attribuez une valeur à l'ID client émis par vos actions sur Google pour identifier les requêtes provenant de Google.
   • Insérez les URL de vos points de terminaison Autorisation et Token Exchange.

Remarque :Si vous souhaitez que votre ID client soit envoyé sous forme de chaîne encodée en base64, cliquez sur la flèche du menu déroulant à côté de Configurer votre client (facultatif), puis cochez la case Google pour transmettre le ClientID et le secret via l'en-tête d'authentification de base HTTP.

6. Cliquez sur Enregistrer.

Implémenter votre serveur OAuth

Pour permettre le flux implicite OAuth 2.0, votre service rend un point de terminaison d'autorisation disponible via HTTPS. Ce point de terminaison est chargé d'authentifier les utilisateurs et d'obtenir leur consentement pour l'accès aux données. Le point de terminaison de l'autorisation présente aux utilisateurs qui ne sont pas déjà connectés une interface de connexion et enregistre l'accès demandé.

Lorsque votre action doit appeler l'une des API autorisées de votre service, Google utilise ce point de terminaison pour obtenir l'autorisation de vos utilisateurs d'appeler ces API en leur nom.

Une session de flux implicite OAuth 2.0 classique initiée par Google présente le flux suivant:

1. Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. S'il ne l'est pas déjà, l'utilisateur se connecte et autorise Google à accéder à ses données avec votre API s'il ne l'a pas déjà fait.
2. Votre service crée un jeton d'accès et le renvoie à Google en redirigeant le navigateur de l'utilisateur vers Google avec le jeton d'accès associé à la requête.
3. 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.

Gérer les demandes d'autorisation

Lorsque votre action doit effectuer l'association de compte via un flux implicite OAuth 2.0, Google renvoie l'utilisateur vers votre point de terminaison d'autorisation avec une requête incluant les paramètres suivants:

Paramètres du point de terminaison d'autorisation
client_id	ID client que vous avez attribué à Google.
redirect_uri	URL à laquelle vous envoyez la réponse à cette requête.
state	Valeur de tenue de registres renvoyée à Google dans l'URI de redirection.
response_type	Type de valeur à afficher dans la réponse. Pour le flux implicite OAuth 2.0, le type de réponse est toujours token.

Par exemple, si votre point de terminaison d'autorisation est disponible à l'adresse https://myservice.example.com/auth, la requête peut se présenter comme suit:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

Pour que votre point de terminaison d'autorisation traite les requêtes de connexion, procédez comme suit:

1. Vérifiez les valeurs client_id et redirect_uri pour empêcher l'accès à des applications clientes non configurées ou mal configurées:

   • Vérifiez que client_id correspond à l'ID client que vous avez attribué à Google.
   • Vérifiez que l'URL spécifiée par le paramètre redirect_uri se présente sous la forme suivante :

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID est l'ID qui se trouve sur la page Paramètres du projet de la console Actions.

2. Vérifiez si l'utilisateur est connecté à votre service. Si l'utilisateur n'est pas connecté, suivez la procédure de connexion ou d'inscription de votre service.

3. Générez un jeton d'accès que Google utilisera pour accéder à votre API. Le jeton d'accès peut correspondre à n'importe quelle valeur de chaîne, mais il doit représenter l'utilisateur et le client de manière unique. Il ne doit pas être deviné.

4. Envoyez une réponse HTTP qui redirige le navigateur de l'utilisateur vers l'URL spécifiée par le paramètre redirect_uri. Incluez tous les paramètres suivants dans le fragment d'URL:

   • access_token: jeton d'accès que vous venez de générer
   • token_type: chaîne bearer
   • state: valeur d'état non modifiée de la requête d'origine. Voici un exemple de l'URL obtenue :

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Le gestionnaire de redirection OAuth 2.0 de Google recevra le jeton d'accès et confirmera que la valeur state n'a pas changé. Une fois que Google a obtenu un jeton d'accès pour votre service, Google l'associe aux appels suivants à votre action dans le cadre de la requête AppRequest.

Concevoir l'interface utilisateur vocale pour le flux d'authentification

Avertissement:N'invitez pas les utilisateurs à associer leur compte au début de la conversation avec votre action. Proposez plutôt un flux invité aux utilisateurs non authentifiés pour leur montrer comment fonctionne votre action, puis demandez l'association du compte uniquement s'il est nécessaire de continuer. Si les utilisateurs quittent l'action de manière cohérente en raison de problèmes d'association de comptes, Google ne la promouvoira pas activement, ce qui risque de réduire le trafic utilisateur de l'action.

Remarque :Vous devez utiliser Actions Builder pour créer une action qui implémente l'association de compte.

Vérifier si l'utilisateur est validé et lancer le processus d'association de comptes

1. Ouvrez votre projet Actions Builder dans la console Actions.
2. Créez une scène pour lancer l'association de compte dans votre action :
   1. Cliquez sur Scènes.
   2. Cliquez sur l'icône add (+) pour ajouter une scène.
3. Dans la scène que vous venez de créer, cliquez sur l'icône d'ajout pour Conditions.
4. Ajoutez une condition qui vérifie si l'utilisateur associé à la conversation est un utilisateur validé. Si la vérification échoue, votre action ne peut pas effectuer l'association de compte pendant la conversation et doit fournir un accès à une fonctionnalité qui ne nécessite pas d'association de compte.
   1. Dans le champ Enter new expression sous Condition, saisissez la logique suivante : user.verificationStatus != "VERIFIED"
   2. Sous Transition, sélectionnez une scène qui ne nécessite pas d'associer un compte ou une scène qui sert de point d'entrée à la fonctionnalité réservée aux invités.

1. Cliquez sur l'icône d'ajout pour Conditions.
2. Ajoutez une condition pour déclencher un flux d'association de comptes si l'utilisateur n'a pas d'identité associée.
   1. Dans le champ Enter new expression sous Condition, saisissez la logique suivante : user.verificationStatus == "VERIFIED"
   2. Sous Transition, sélectionnez la scène système Association de comptes.
   3. Cliquez sur Enregistrer.

Après l'enregistrement, une nouvelle scène système d'association de comptes appelée <SceneName>_AccountLinking est ajoutée à votre projet.

Personnaliser la scène d'association de comptes

1. Sous Scènes, sélectionnez la scène du système d'association de comptes.
2. Cliquez sur Envoyer une invite et ajoutez une courte phrase pour expliquer à l'utilisateur pourquoi l'action doit accéder à son identité (par exemple, "Pour enregistrer vos préférences").
3. Cliquez sur Enregistrer.

1. Sous Conditions, cliquez sur Si l'utilisateur a terminé l'association de comptes.
2. Configurez la procédure à suivre si l'utilisateur accepte d'associer son compte. Par exemple, appelez le webhook pour traiter toute logique métier personnalisée requise et revenez à la scène d'origine.
3. Cliquez sur Enregistrer.

1. Sous Conditions, cliquez sur Si l'utilisateur annule ou désactive l'association de comptes.
2. Configurez la procédure à suivre si l'utilisateur n'accepte pas l'association de son compte. Par exemple, envoyez un message d'accusé de réception et redirigez les utilisateurs vers des scènes qui nécessitent une association de compte.
3. Cliquez sur Enregistrer.

1. Sous Conditions, cliquez sur En cas d'erreur système ou réseau.
2. Configurez la procédure si le flux d'association de comptes ne peut pas être terminé en raison d'erreurs système ou réseau. Par exemple, envoyez un message d'accusé de réception et redirigez les utilisateurs vers des scènes qui nécessitent une association de compte.
3. Cliquez sur Enregistrer.

Gérer les demandes d'accès aux données

Si la requête de l'Assistant contient un jeton d'accès, vérifiez d'abord qu'il est valide (et qu'il n'a pas expiré), puis récupérez le compte utilisateur associé dans votre base de données.