Conversational Actions will be deprecated on June 13, 2023. For more information, see Conversational Actions sunset.

Association de comptes avec OAuth

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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 permanent à Google. Ce jeton d'accès est désormais inclus dans chaque requête envoyée par l'Assistant à votre action.

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

  • Le point de terminaison authorization, chargé de présenter l'UI de connexion aux utilisateurs qui ne sont pas encore connectés et d'enregistrer le consentement pour l'accès demandé sous la forme d'un code d'autorisation temporaire.
  • Le point de terminaison token exchange, qui est responsable de deux types de places de marché :
    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 a lieu lorsque l'utilisateur suit le flux 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 simple à mettre en œuvre, Google recommande que les jetons d'accès émis à l'aide du flux implicite n'expirent jamais, car l'utilisation du jeton d'expiration de jeton avec le flux implicite oblige l'utilisateur à réassocier son compte. Si vous avez besoin d'expirer le jeton pour des raisons de sécurité, nous vous recommandons vivement d'utiliser le flux de code d'authentification.

Implémenter l'association de comptes OAuth

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, puis sélectionnez Association de comptes.
  3. Activez le bouton à côté de l'option Association de comptes.
  4. Dans la section Création de compte, sélectionnez Non, je souhaite autoriser la création de comptes uniquement 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 auprès de Google pour identifier les requêtes provenant de Google.
    • Insérez les URL de vos points de terminaison Autorisation et Token Exchange.
  1. Cliquez sur Enregistrer.

Implémenter votre serveur OAuth

Pour prendre en charge le parcours implicite OAuth 2.0, votre service rend un point de terminaison d'autorisation disponible via HTTPS. Ce point de terminaison est chargé d'authentifier et d'obtenir le consentement des utilisateurs pour l'accès aux données. Le point de terminaison d'autorisation présente une interface utilisateur de connexion aux utilisateurs qui ne sont pas déjà connectés 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 à appeler ces API en leur nom.

Voici à quoi ressemble une session de flux implicite OAuth 2.0 lancée par Google:

  1. Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. L'utilisateur se connecte s'il ne l'a pas déjà fait 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 effectue 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 envoie l'utilisateur à 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 comptabilité transmise à Google et inchangée 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 à https://myservice.example.com/auth, une requête pourrait 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 inattendues 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 correspond à l'ID figurant 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é, terminez la procédure de connexion ou d'inscription à 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 être n'importe quelle valeur de chaîne, mais il doit représenter l'utilisateur et le client de manière unique, et ne doit pas être devinable.

  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: le 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 d'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 reçoit le jeton d'accès et confirme 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 AppRequest.

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

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 associer votre compte dans votre action :
    1. Cliquez sur Scenes (Scènes).
    2. Cliquez sur l'icône add (+) pour ajouter une scène.
  3. Dans la scène nouvellement créée, 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 pourra pas effectuer l'association de comptes pendant la conversation et devrait revenir à une fonctionnalité qui ne nécessite pas d'association de comptes.
    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'association de comptes ou une scène servant de point d'entrée à une 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.

Une fois la sauvegarde effectuée, 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 Scenes (Scènes), sélectionnez la scène 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 réussi à associer le compte.
  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 revenir à la scène d'origine.
  3. Cliquez sur Enregistrer.

  1. Sous Conditions, cliquez sur Si l'utilisateur annule ou ignore l'association de comptes.
  2. Configurez la procédure à suivre si l'utilisateur refuse d'associer son compte. Par exemple, vous pouvez envoyer un message de confirmation et rediriger les utilisateurs vers des scènes qui n'exigent pas d'association de comptes.
  3. Cliquez sur Enregistrer.

  1. Sous Conditions, cliquez sur En cas d'erreur système ou réseau.
  2. Configurez la manière dont le flux doit se poursuivre si l'association du compte ne peut pas aboutir en raison d'erreurs système ou réseau. Par exemple, vous pouvez envoyer un message de confirmation et rediriger les utilisateurs vers des scènes qui n'exigent pas d'association de comptes.
  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.