Authentifier et autoriser les applications Chat et les requêtes API Google Chat

L'authentification et l'autorisation sont des mécanismes utilisés pour vérifier respectivement l'identité et l'accès aux ressources. Ce document décrit le fonctionnement de l'authentification et de l'autorisation pour les applications et requêtes Chat.

Présentation du processus

Le schéma suivant présente les principales étapes d'authentification et d'autorisation pour Google Chat:

Principales étapes pour l'authentification et l'autorisation Google Chat
Figure 1. Étapes générales pour l'authentification et l'autorisation Google Chat

  1. Configurez un projet Google Cloud, activez l'API Chat et configurez votre application Chat:au cours du développement, vous créez un projet Google Cloud. Dans le projet Google Cloud, vous activez l'API Chat, puis configurez votre application Chat et l'authentification. Pour en savoir plus, consultez Développer sur Google Workspace et Créer une application Chat.

  2. Call Chat API (Appeler l'API Chat) : lorsque votre application appelle l'API Chat, elle envoie des identifiants d'authentification à l'API Chat. Si votre application s'authentifie avec un compte de service, les identifiants sont envoyés dans le code de votre application. Si votre application nécessite d'appeler l'API Chat à l'aide d'une authentification qui n'a pas encore été accordée, elle l'invite à se connecter.

  3. Demander des ressources: votre application demande l'accès avec les champs d'application que vous spécifiez lors de la configuration de l'authentification.

  4. Demander le consentement:si votre application s'authentifie en tant qu'utilisateur, Google affiche un écran de consentement OAuth afin que l'utilisateur puisse décider d'accorder à votre application l'accès aux données demandées. L'authentification avec un compte de service ne nécessite pas le consentement de l'utilisateur.

  5. Envoyez une demande de ressources approuvée:si l'utilisateur accepte les champs d'application d'autorisation, votre application regroupe les identifiants et les champs d'application approuvés par l'utilisateur dans une requête. La requête est envoyée au serveur d'autorisation Google pour obtenir un jeton d'accès.

  6. Google renvoie un jeton d'accès. Le jeton d'accès contient la liste des champs d'application autorisés. Si la liste de champs d'application renvoyée est plus restrictive que les champs d'application demandés, votre application désactive toutes les fonctionnalités limitées par le jeton.

  7. Accès aux ressources demandées:votre application utilise le jeton d'accès de Google pour appeler l'API Chat et accéder aux ressources de cette API.

  8. Obtenir un jeton d'actualisation (facultatif) : si votre application doit accéder à l'API Google Chat au-delà de la durée de vie d'un jeton d'accès, elle peut obtenir un jeton d'actualisation. Pour en savoir plus, consultez Utiliser OAuth 2.0 pour accéder aux API Google.

  9. Demande de ressources supplémentaires:si votre application a besoin d'un accès plus étendu, elle demande à l'utilisateur d'accorder de nouveaux champs d'application, ce qui génère une nouvelle demande de jeton d'accès (étapes 3 à 6).

Lorsque les applications Chat nécessitent une authentification

Les applications de chat peuvent envoyer des messages en réponse à une interaction utilisateur ou de manière asynchrone. Ils peuvent également effectuer des tâches pour le compte d'un utilisateur, comme créer un espace Chat ou obtenir la liste des membres d'un espace Chat.

Les applications de chat ne nécessitent pas d'authentification pour répondre à une interaction utilisateur, sauf si elles appellent l'API Chat ou une autre API Google lors du traitement d'une réponse.

Pour envoyer des messages asynchrones ou effectuer des tâches au nom d'un utilisateur, les applications Chat envoient des requêtes RESTful à l'API Chat, ce qui nécessite une authentification et une autorisation.

Les réponses aux interactions des utilisateurs ne nécessitent pas d'authentification

Les applications Google Chat n'ont pas besoin de s'authentifier en tant qu'utilisateur ou application Chat pour recevoir des événements d'interaction et y répondre de manière synchrone.

Les applications Google Chat reçoivent des événements d'interaction chaque fois qu'un utilisateur interagit ou appelle une application Chat. Par exemple:

  • Un utilisateur envoie un message à une application Chat.
  • Un utilisateur @mentionne une application Chat.
  • Un utilisateur appelle l'une des commandes à barre oblique de l'application Chat.

Le schéma suivant illustre une séquence de requête-réponse entre un utilisateur de Chat et l'application Chat:

Aucune autorisation requise pour les événements d'interaction avec l'application Chat
Figure 2 : Les événements d'interaction avec l'application Chat ne nécessitent pas d'authentification.

  1. L'utilisateur envoie un message à l'application Chat dans Google Chat.
  2. Google Chat transfère le message à l'application.
  3. L'application reçoit le message, le traite et renvoie une réponse à Google Chat.
  4. Google Chat affiche la réponse à l'utilisateur ou dans un espace.

Cette séquence se répète pour chaque événement d'interaction avec l'application Chat.

Les messages asynchrones nécessitent une authentification

Des messages asynchrones surviennent lorsqu'une application Chat envoie une requête à l'API Chat, ce qui nécessite une authentification et une autorisation.

En appelant l'API Chat, les applications Chat peuvent publier des messages sur Google Chat ou effectuer des tâches et accéder aux données au nom d'un utilisateur. Par exemple, après avoir détecté une panne de serveur, une application Chat peut appeler l'API Chat pour:

  • Créez un espace Chat dédié à l'investigation et à la résolution de la panne.
  • Ajoutez des participants à l'espace Chat.
  • Publier un message dans l'espace Chat pour fournir des informations sur l'indisponibilité

Le schéma suivant illustre une séquence de messages asynchrones entre une application Chat et un espace Chat:

Authentification requise pour les messages asynchrones
Figure 3. Les messages asynchrones nécessitent une authentification.

  1. Une application Chat crée un message en appelant l'API Chat à l'aide de la méthode spaces.messages.create et inclut les identifiants utilisateur dans la requête HTTP.
  2. Google Chat authentifie l'application Chat avec le compte de service ou les identifiants utilisateur.
  3. Google Chat affiche le message de l'application dans un espace Chat spécifié.

Champs d'application de l'API Chat

Configurez l'écran de consentement OAuth et choisissez les champs d'application pour définir les informations à présenter aux utilisateurs et aux examinateurs d'applications, et enregistrez votre application pour pouvoir la publier ultérieurement.

Pour définir le niveau d'accès accordé à votre application, vous devez identifier et déclarer des champs d'application d'autorisation. Un champ d'application d'autorisation est une chaîne d'URI OAuth 2.0 contenant le nom de l'application Google Workspace, le type de données auxquelles elle accède et le niveau d'accès.

Champs d'application non sensibles

Code du champ d'application Description
https://www.googleapis.com/auth/chat.bot

Le niveau d'accès chat.bot n'est compatible qu'avec les comptes de service. Vous ne pouvez pas vous authentifier avec des identifiants utilisateur ni via la délégation au niveau du domaine avec ce champ d'application.

Autorise les applications Chat à afficher les discussions et à envoyer des messages. Donne l'accès à toutes les fonctionnalités disponibles pour les applications Chat.

Champs d'application sensibles

Code du champ d'application Description
https://www.googleapis.com/auth/chat.spaces Créez des conversations et des espaces, et affichez ou mettez à jour les métadonnées (y compris les paramètres d'historique) dans Chat.
https://www.googleapis.com/auth/chat.spaces.create Créez des conversations dans Chat.
https://www.googleapis.com/auth/chat.spaces.readonly Affichez le chat et les espaces dans Chat.
https://www.googleapis.com/auth/chat.memberships Affichez des participants aux conversations dans Chat, ajoutez-en et supprimez-en.
https://www.googleapis.com/auth/chat.memberships.app S'ajouter aux conversations dans Google Chat et s'en retirer
https://www.googleapis.com/auth/chat.memberships.readonly Affichez les participants aux conversations Chat.
https://www.googleapis.com/auth/chat.messages.create Rédigez et envoyez des messages dans Chat.
https://www.googleapis.com/auth/chat.messages.reactions Affichez, ajoutez et supprimez des réactions aux messages dans Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create Ajoutez des réactions à un message dans Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Affichez les réactions à un message dans Chat.
https://www.googleapis.com/auth/chat.users.readstate Affichez et modifiez l'heure de dernière lecture des conversations Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly Affichez l'heure de dernière lecture des conversations Chat.

Champs d'application restreints

Code du champ d'application Description
https://www.googleapis.com/auth/chat.delete Supprimez des conversations et des espaces, ainsi que l'accès aux fichiers associés dans Chat.
https://www.googleapis.com/auth/chat.import Importez des espaces, des messages et des membres dans Chat. Pour en savoir plus, consultez Autoriser les applications Chat à importer des données.
https://www.googleapis.com/auth/chat.messages Affichez, rédigez, envoyez, mettez à jour et supprimez des messages, et ajoutez, affichez et supprimez les réactions aux messages.
https://www.googleapis.com/auth/chat.messages.readonly Affichez les messages et les réactions dans Chat.

Les champs d'application des tableaux précédents indiquent leur sensibilité, selon les définitions suivantes:

Si votre application nécessite l'accès à d'autres API Google, vous pouvez également ajouter ces niveaux d'accès. Pour en savoir plus sur les champs d'application des API Google, consultez la page Utiliser OAuth 2.0 pour accéder aux API Google.

Pour en savoir plus sur les champs d'application des API Google Workspace, consultez Configurer l'écran de consentement OAuth et choisir les champs d'application.

Types d'authentifications requises

Il existe deux façons de s'authentifier et d'autoriser les applications Chat avec l'API Chat: les identifiants utilisateur ou les comptes de service.

Avec l'autorisation via les identifiants utilisateur, une application Chat peut accéder aux données utilisateur et effectuer des actions au nom d'un utilisateur. Les champs d'application OAuth spécifient les données et actions autorisées. Toutefois, ces applications Chat ne peuvent pas être publiées publiquement. Pour en savoir plus, consultez Publier des applications Google Chat.

Avec l'autorisation d'application, une application Chat accède à l'API en tant qu'application à l'aide des identifiants du compte de service. L'autorisation des applications utilise toujours le champ d'application d'autorisation chat.bot.

Si vous êtes administrateur de domaine, vous pouvez accorder une délégation d'autorité au niveau du domaine pour autoriser le compte de service d'une application à accéder aux données de vos utilisateurs sans que chacun d'eux ait à donner son consentement. Après avoir configuré la délégation au niveau du domaine, vous pouvez effectuer des appels d'API à l'aide de votre compte de service pour emprunter l'identité d'un compte utilisateur. Bien qu'un compte de service soit utilisé pour l'authentification, la délégation au niveau du domaine emprunte l'identité d'un utilisateur et est donc considérée comme une authentification de l'utilisateur. Toute fonctionnalité nécessitant l'authentification des utilisateurs peut utiliser la délégation au niveau du domaine.

Lorsque vous décidez du type d'identifiant à utiliser pour une requête API particulière, gardez à l'esprit que certaines méthodes d'API ne sont compatibles qu'avec un type d'identifiant particulier. Si une méthode API est compatible avec les deux identifiants, le type d'identifiant utilisé dans l'appel affecte le résultat renvoyé:

  • Avec l'autorisation d'application, les méthodes ne renvoient que les ressources auxquelles l'application peut accéder.
  • Avec l'autorisation de l'utilisateur, les méthodes ne renvoient que les ressources auxquelles l'utilisateur peut accéder dans l'interface Chat.

Par exemple, l'appel de la méthode ListSpaces avec l'autorisation de l'application renvoie la liste des espaces dont l'application est membre. L'appel de ListSpaces avec l'autorisation de l'utilisateur renvoie la liste des espaces dont l'utilisateur est membre. En pratique, votre application peut utiliser les deux types d'autorisation lors de l'appel de l'API Chat, en fonction de la fonctionnalité souhaitée.

Pour les appels d'API Chat asynchrones

Le tableau suivant répertorie les méthodes de l'API Chat et leurs champs d'application d'autorisation compatibles:

Méthode Authentification des utilisateurs prise en charge Authentification des applications acceptée Champs d'application des autorisations compatibles
Espaces  
Créer un espace Avec l'authentification des utilisateurs :
  • chat.spaces.create
  • chat.spaces
  • chat.import
Configurer un espace Avec l'authentification des utilisateurs :
  • chat.spaces.create
  • chat.spaces
Obtenir un espace Avec l'authentification des utilisateurs :
  • chat.spaces.readonly
  • chat.spaces
Avec Authentification de l'application :
  • chat.bot
Lister les espaces Avec l'authentification des utilisateurs :
  • chat.spaces.readonly
  • chat.spaces
Avec Authentification de l'application :
  • chat.bot
Modifier un espace Avec l'authentification des utilisateurs :
  • chat.spaces
  • chat.import
Supprimer un espace Avec l'authentification des utilisateurs :
  • chat.delete
  • chat.import
Terminer le processus d'importation d'un espace Avec l'authentification des utilisateurs :
  • chat.import
Trouver un message privé Avec l'authentification des utilisateurs :
  • chat.spaces.readonly
  • chat.spaces
Avec Authentification de l'application :
  • chat.bot
Membres  
Créer un membre Avec l'authentification des utilisateurs :
  • chat.memberships
  • chat.memberships.app
  • chat.import
Devenez membre Avec l'authentification des utilisateurs :
  • chat.memberships.readonly
  • chat.memberships
Avec Authentification de l'application :
  • chat.bot
Membres de la liste Avec l'authentification des utilisateurs :
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Avec Authentification de l'application :
  • chat.bot
Supprimer un membre Avec l'authentification des utilisateurs :
  • chat.memberships
  • chat.memberships.app
  • chat.import
Messages  
Créer un message Avec l'authentification des utilisateurs :
  • chat.messages.create
  • chat.messages
  • chat.import
Avec Authentification de l'application :
  • chat.bot
Recevoir un message Avec l'authentification des utilisateurs :
  • chat.messages.readonly
  • chat.messages
Avec Authentification de l'application :
  • chat.bot
Lister les messages Avec l'authentification des utilisateurs :
  • chat.messages.readonly
  • chat.messages
  • chat.import
Modifier un message Avec l'authentification des utilisateurs :
  • chat.messages
  • chat.import
Avec Authentification de l'application :
  • chat.bot
Supprimer un message Avec l'authentification des utilisateurs :
  • chat.messages
  • chat.import
Avec Authentification de l'application :
  • chat.bot
Réactions  
Créer une réaction Avec l'authentification des utilisateurs :
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Lister les réactions Avec l'authentification des utilisateurs :
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Supprimer une réaction Avec l'authentification des utilisateurs :
  • chat.messages.reactions
  • chat.messages
  • chat.import
Contenus multimédias et pièces jointes  
Importer des contenus multimédias en tant que pièce jointe Avec l'authentification des utilisateurs :
  • chat.messages.create
  • chat.messages
  • chat.import
Télécharger des contenus multimédias Avec l'authentification des utilisateurs :
  • chat.messages.readonly
  • chat.messages
Avec Authentification de l'application :
  • chat.bot
Recevoir une pièce jointe Avec l'authentification de l'application :
  • chat.bot
États de lecture des utilisateurs
Obtenir l'état de lecture d'un espace utilisateur Avec l'authentification des utilisateurs :
  • chat.users.readstate
  • chat.users.readstate.readonly
Mettre à jour l'état de lecture d'un espace utilisateur Avec l'authentification des utilisateurs :
  • chat.users.readstate
Obtenir l'état de lecture du thread d'un utilisateur Avec l'authentification des utilisateurs :
  • chat.users.readstate
  • chat.users.readstate.readonly

Pour les événements d'interaction avec l'application Chat

Le tableau suivant répertorie les interactions courantes des utilisateurs avec les applications Chat, et indique si l'authentification est requise ou prise en charge:

Scénario Aucune authentification requise Authentification des utilisateurs prise en charge Authentification des applications acceptée
Recevoir des messages de:
Événements d'interaction avec les applications Chat
Rappels Apps Script
Google Cloud Pub/Sub
Pour répondre aux messages:
De manière synchrone, via un événement d'interaction avec l'application Chat
De manière synchrone, à l'aide d'une valeur de retour de rappel Apps Script
Pour envoyer de nouveaux messages:
Avec les webhooks entrants