Connecter une application Chat à d'autres services et outils

Cette page explique comment connecter une application Google Chat à un service ou un outil en dehors de Google Chat. Bien que les applications Chat soient puissantes en elles-mêmes, elles fonctionnent souvent de concert avec d'autres systèmes et nécessitent des applications associées pour connecter des comptes, autoriser l'accès aux données, afficher des données supplémentaires ou configurer les préférences utilisateur.

Pour authentifier les utilisateurs avec un service tiers ou un flux OAuth, votre application Chat effectue les étapes suivantes :

1. Détecter quand une autorisation ou une configuration est requise
2. Renvoyez une carte d'autorisation de base qui invite l'utilisateur à se connecter ou à configurer le service.
3. Redirigez l'utilisateur vers l'URI d'achèvement pour que Google Chat relance automatiquement l'interaction d'origine une fois que l'utilisateur a terminé l'autorisation.

Prérequis

Détecter qu'une autorisation est requise

Lorsqu'ils interagissent avec votre application Chat, il est possible que les utilisateurs ne soient pas autorisés à accéder à une ressource protégée pour diverses raisons, par exemple :

• Un jeton d'accès pour se connecter au service tiers n'a pas encore été généré ou a expiré.
• Le jeton d'accès ne couvre pas la ressource demandée.
• Le jeton d'accès ne couvre pas les habilitations requises pour la requête.

Votre application Chat doit détecter ces cas afin que les utilisateurs puissent se connecter et autoriser l'accès à votre service.

Si vous développez dans Apps Script, vous pouvez utiliser la bibliothèque OAuth2 pour Google Apps Script (ou la version OAuth1), où la fonction hasAccess vérifie si l'utilisateur a autorisé l'accès à un service. Vous pouvez également définir le paramètre muteHttpExceptions sur true lorsque vous utilisez des requêtes UrlFetchApp.fetch pour inspecter le code de réponse et le contenu dans l'objet HttpResponse renvoyé.

Inviter les utilisateurs avec une carte d'autorisation de base

Lorsque votre application Chat détecte qu'une autorisation ou une configuration est requise, renvoyez une réponse AuthorizationError pour afficher une fiche d'autorisation de base privée à l'utilisateur.

L'image suivante montre un exemple de carte d'autorisation de base de Google :

Pour inviter les utilisateurs à utiliser une carte d'autorisation de base, renvoyez un objet AuthorizationError :

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Remplacez les éléments suivants :

• AUTHORIZATION_URL : URL HTTPS de l'application Web qui gère l'authentification, l'autorisation ou la configuration.
• RESOURCE_DISPLAY_NAME : nom à afficher de la ressource ou du service protégés. Ce nom est affiché pour l'utilisateur dans l'invite d'autorisation. Par exemple, si votre RESOURCE_DISPLAY_NAME est Example Account, l'invite indique que l'application a besoin d'une autorisation pour accéder à votre Example Account.

Remplir la demande de configuration

Dans Chat, l'utilisateur peut effectuer le processus d'autorisation et demander à Chat de réessayer automatiquement l'interaction d'origine sans actualisation manuelle. Chat est compatible avec la nouvelle tentative automatique si le déclencheur est Message, Ajouté à l'espace ou Commande d'application.

Pour ces déclencheurs, votre application Chat reçoit un URI de redirection de fin (configCompleteRedirectUri / completeRedirectUri) dans la charge utile de l'événement :

• Message : chat.messagePayload.configCompleteRedirectUri
• Ajouté à l'espace : chat.addedToSpacePayload.configCompleteRedirectUri
• Commande de l'application : chat.appCommandPayload.configCompleteRedirectUri

Vous devez encoder cet URI de redirection dans votre <var>AUTHORIZATION_URL</var> et rediriger le navigateur de l'utilisateur vers celui-ci une fois le flux d'autorisation terminé. La redirection vers cette URL indique à Google Chat que la demande d'autorisation ou de configuration a été traitée.

Lorsqu'un utilisateur est redirigé vers l'URI de redirection de fin fourni dans la charge utile de l'événement d'origine, Google Chat effectue les étapes suivantes :

1. Efface l'invite d'autorisation privée affichée pour l'utilisateur à l'origine de la demande.
2. Convertit le message d'origine en message public, le rendant visible par les autres membres de l'espace.
3. Envoie l'objet d'événement d'origine à votre application Chat une deuxième fois.

Si vous ne redirigez pas l'utilisateur vers l'URI de redirection de fin, il peut toujours terminer le flux d'autorisation, mais Google Chat ne relance pas automatiquement l'exécution précédente. L'utilisateur doit donc invoquer manuellement votre application Chat.

L'accès à un URI de redirection de finalisation n'affecte qu'une seule interaction utilisateur. Si un utilisateur a envoyé plusieurs messages à une application Chat et reçu plusieurs invites, il ne peut réessayer que l'interaction spécifique pour laquelle il a terminé le processus d'authentification et de configuration.

Authentifier l'utilisateur Chat en dehors de Chat

Lorsque vous créez un lien vers une URL en dehors de Chat (par exemple, un rappel Web OAuth), vous devez souvent corréler la session Web externe avec l'identité de l'utilisateur dans Chat. Nous vous recommandons de protéger l'application Web de destination avec Google Sign-In.

Utilisez le jeton d'identité émis lors de la connexion pour obtenir l'ID utilisateur. La revendication sub contient l'ID Google unique de l'utilisateur et peut être mise en corrélation avec le nom de ressource utilisateur (chat.user.name) de Google Chat.

Pour corréler la revendication sub avec un nom de ressource users/{user} Google Chat, ajoutez users/ devant la valeur de la revendication sub. Par exemple, une valeur de revendication sub de 123 correspond à users/123 dans les objets d'événement envoyés à votre application Chat.

Exemples de code

Les exemples de code suivants montrent comment une application Chat peut demander des identifiants OAuth2 hors connexion à l'aide d'une carte d'autorisation de base, les stocker dans une base de données, rediriger vers l'URI d'achèvement et effectuer des appels d'API avec l'authentification de l'utilisateur :

Articles associés

• Recevoir des interactions utilisateur et y répondre
• Authentifier et autoriser les applications Google Chat et les requêtes API Google Chat
• Associer votre module complémentaire Google Workspace à un service tiers

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}