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 l'identité et l'accès aux ressources, respectivement. Ce document explique comment fonctionnent l'authentification et l'autorisation pour les applications Chat et les requêtes API Chat.

Présentation du processus

Le schéma suivant illustre les étapes générales d'authentification et d'autorisation pour Google Chat :

Étapes générales 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 : pendant le développement, vous créez un projet Google Cloud. Dans le projet Google Cloud, vous activez l'API Chat, configurez votre application Chat et configurez l'authentification. Pour en savoir plus, consultez Développer sur Google Workspace et Créer une application Chat.

  2. 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 utilisateur qui n'a pas encore été accordée, l'utilisateur est invité à se connecter.

  3. Demander des ressources : votre application demande l'accès avec des scopes 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 pour que l'utilisateur puisse décider d'autoriser ou non votre application à accéder 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 approuvée pour les ressources : si l'utilisateur accepte les niveaux d'autorisation, votre application regroupe les identifiants et les niveaux approuvés par l'utilisateur dans une demande. 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 une liste des autorisations accordées. Si la liste des 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 l'API Chat.

  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 unique, elle peut obtenir un jeton d'actualisation. Pour en savoir plus, consultez Utiliser OAuth 2.0 pour accéder aux API Google.

  9. Demander plus de ressources : si votre application a besoin de plus d'accès, elle demande à l'utilisateur d'accorder de nouveaux niveaux d'accès, ce qui entraîne une nouvelle demande d'obtention d'un jeton d'accès (étapes 3 à 6).

Quand les applications de chat nécessitent une authentification

Les applications Chat peuvent envoyer des messages en réponse à une interaction utilisateur ou de manière asynchrone. Elles peuvent également effectuer des tâches au nom d'un utilisateur, comme créer un espace Chat ou obtenir la liste des personnes présentes dans un espace Chat.

Les applications Chat n'ont pas besoin d'authentification pour répondre à une interaction utilisateur, sauf si l'application Chat appelle 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, qui nécessitent 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 avec une application Chat ou l'appelle, y compris dans les cas suivants :

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

Le schéma suivant illustre une séquence requête/réponse entre un utilisateur Chat et une 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 pour 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

Les messages asynchrones se produisent lorsqu'une application Chat envoie une requête à l'API Chat, qui nécessite une authentification et une autorisation.

En appelant l'API Chat, les applications Chat peuvent publier des messages dans Google Chat, 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'étude et à la résolution de la panne.
  • Ajoutez des personnes à l'espace Chat.
  • Publiez un message dans l'espace Chat pour donner des détails 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 de l'utilisateur dans la requête HTTP.
  2. Google Chat authentifie l'application Chat avec un compte de service ou des 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 des habilitations pour définir les informations affichées aux utilisateurs et aux évaluateurs 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 les niveaux d'autorisation. Un champ d'application d'autorisation est une chaîne d'URI OAuth 2.0 qui contient 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

Permet aux applications Chat d'afficher les discussions et d'envoyer des messages.

Ce champ d'application n'est compatible qu'avec l'authentification des applications avec des comptes de service. Vous ne pouvez pas vous authentifier avec des identifiants utilisateur ni avec la délégation au niveau du domaine à l'aide de ce champ d'application.

Niveaux d'accès sensibles

Code du champ d'application Description
https://www.googleapis.com/auth/chat.spaces Créer des conversations et des espaces, et voir ou modifier les métadonnées (y compris les paramètres d'historique et d'accès) dans Chat.
https://www.googleapis.com/auth/chat.spaces.create créer des conversations dans Chat ;
https://www.googleapis.com/auth/chat.spaces.readonly Afficher les discussions et les espaces dans Chat.
https://www.googleapis.com/auth/chat.memberships Afficher les participants aux conversations dans Chat, en ajouter, les modifier ou en supprimer
https://www.googleapis.com/auth/chat.memberships.app S'ajouter aux conversations dans Google Chat et s'en supprimer
https://www.googleapis.com/auth/chat.memberships.readonly Afficher les membres des conversations Chat
https://www.googleapis.com/auth/chat.messages.create Rédiger et envoyer des messages dans Chat
https://www.googleapis.com/auth/chat.messages.reactions Afficher, ajouter et supprimer des réactions à des 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 Afficher les réactions à un message dans Chat
https://www.googleapis.com/auth/chat.users.readstate Afficher et modifier l'heure de dernière lecture des conversations Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly Afficher l'heure de dernière lecture des conversations Chat
https://www.googleapis.com/auth/chat.admin.spaces.readonly Affichez les discussions et les espaces appartenant au domaine de l'administrateur dans Chat.
https://www.googleapis.com/auth/chat.admin.spaces Afficher ou modifier les discussions et les espaces appartenant au domaine de l'administrateur dans Chat.
https://www.googleapis.com/auth/chat.admin.memberships.readonly Afficher les membres et les gestionnaires dans les conversations appartenant au domaine de l'administrateur dans Chat
https://www.googleapis.com/auth/chat.admin.memberships Voir, ajouter, modifier et supprimer les participants et les gestionnaires dans les conversations appartenant au domaine de l'administrateur dans Chat.
https://www.googleapis.com/auth/chat.app.spaces

Créer des conversations et des espaces, et afficher ou modifier les métadonnées (y compris les paramètres d'historique et d'accès) dans Chat. Nécessite l'approbation de l'administrateur.

Ce champ d'application n'est compatible qu'avec l'authentification des applications avec des comptes de service. Vous ne pouvez pas vous authentifier avec des identifiants utilisateur ni avec la délégation au niveau du domaine à l'aide de ce champ d'application.

https://www.googleapis.com/auth/chat.app.spaces.create

Créez des conversations et des espaces dans Chat. Nécessite l'approbation de l'administrateur.

Ce champ d'application n'est compatible qu'avec l'authentification des applications avec des comptes de service. Vous ne pouvez pas vous authentifier avec des identifiants utilisateur ni avec la délégation au niveau du domaine à l'aide de ce champ d'application.

https://www.googleapis.com/auth/chat.app.memberships

Afficher les membres des conversations et des espaces dans Chat, en ajouter, en modifier et en supprimer Nécessite l'approbation de l'administrateur.

Ce champ d'application n'est compatible qu'avec l'authentification des applications avec des comptes de service. Vous ne pouvez pas vous authentifier avec des identifiants utilisateur ni avec la délégation au niveau du domaine à l'aide de ce champ d'application.

https://www.googleapis.com/auth/chat.customemojis Afficher, créer et supprimer des emoji personnalisés dans Chat
https://www.googleapis.com/auth/chat.customemojis.readonly Consulter les emoji personnalisés dans Chat.
https://www.googleapis.com/auth/chat.users.spacesettings Affichez et modifiez les paramètres de l'espace utilisateur Chat.

Niveaux d'accès restreints

Code du champ d'application Description
https://www.googleapis.com/auth/chat.delete Supprimer des conversations et des espaces, et supprimer l'accès aux fichiers associés dans Chat.
https://www.googleapis.com/auth/chat.import Importer 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 Afficher, rédiger, envoyer, modifier et supprimer les messages, et ajouter, afficher et supprimer les réactions aux messages.
https://www.googleapis.com/auth/chat.messages.readonly Afficher les messages et les réactions dans Chat
https://www.googleapis.com/auth/chat.admin.delete Supprimer des conversations et des espaces appartenant au domaine de l'administrateur, et supprimer l'accès aux fichiers associés dans Chat.
https://www.googleapis.com/auth/chat.app.delete

Supprimer des conversations et des espaces, et supprimer l'accès aux fichiers associés dans Chat Nécessite l'approbation de l'administrateur.

Ce champ d'application n'est compatible qu'avec l'authentification des applications avec des comptes de service. Vous ne pouvez pas vous authentifier avec des identifiants utilisateur ni avec la délégation au niveau du domaine à l'aide de ce champ d'application.

Les niveaux d'accès dans les tableaux précédents indiquent leur sensibilité, selon les définitions suivantes :

Si votre application nécessite d'accéder à 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 Utiliser OAuth 2.0 pour accéder aux API Google.

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

Types d'authentification requis

Il existe deux façons pour les applications Chat de s'authentifier et de s'autoriser avec l'API Chat :

Authentification des utilisateurs
L'authentification des utilisateurs permet à une application Chat d'accéder aux données utilisateur et d'effectuer des actions pour le compte d'un utilisateur.
Les habilitations OAuth spécifient les données et les actions autorisées. À moins que l'application Chat n'ait été installée par l'administrateur ou qu'elle n'ait reçu la délégation au niveau du domaine, la première fois qu'elle effectue une action pour le compte d'un utilisateur, celui-ci doit l'autoriser à l'aide de l'écran d'autorisation OAuth.
Authentification des applications

L'authentification des applications permet à une application Chat d'utiliser les identifiants d'un compte de service, d'accéder aux données et d'effectuer des actions en son nom propre. Étant donné que l'application Chat utilise ses propres identifiants pour accéder aux ressources et les utiliser, les utilisateurs finaux n'ont pas besoin d'approuver les appels d'API de l'application Chat. De plus, vous ne pouvez pas ajouter de niveaux d'autorisation OAuth compatibles avec l'autorisation d'application à l'écran d'autorisation OAuth.

Deux types de niveaux d'autorisation OAuth sont compatibles avec l'authentification des applications :

  • https://www.googleapis.com/auth/chat.bot : Votre application Chat peut appeler des méthodes de l'API Google Chat compatibles avec ce champ d'application d'autorisation pour créer, mettre à jour, obtenir, lister ou supprimer les ressources auxquelles elle a accès, comme les messages dans les espaces auxquels les utilisateurs finaux ajoutent votre application Chat. Votre application Chat peut s'accorder elle-même ce champ d'application d'autorisation. Aucune autorisation d'administrateur ni d'utilisateur final n'est requise.
  • https://www.googleapis.com/auth/chat.app.* (Preview développeur) : l'utilisation de ces niveaux d'accès nécessite une approbation unique de l'administrateur. Pour obtenir l'approbation de l'administrateur, préparez le compte de service de l'application Chat à recevoir l'approbation de l'administrateur en créant un client OAuth compatible avec Google Workspace Marketplace et en configurant l'application dans le SDK Google Workspace Marketplace. Ces habilitations permettent à votre application Chat d'appeler des méthodes spécifiques de l'API Google Chat. Par exemple, chat.app.spaces.create permet aux applications de créer des espaces Chat.

Si une méthode est compatible avec l'authentification des utilisateurs ou des applications, l'API Chat renvoie des résultats différents en fonction du type d'authentification que vous utilisez :

  • Avec l'authentification des applications, les méthodes ne renvoient que les ressources auxquelles l'application Chat peut accéder.
  • Avec l'authentification des utilisateurs, les méthodes ne renvoient que les ressources auxquelles l'utilisateur peut accéder.

Par exemple, l'appel de la méthode spaces.list() avec l'autorisation de l'application renvoie la liste des espaces dont l'application Chat est membre. L'appel de spaces.list() avec l'autorisation de l'utilisateur renvoie la liste des espaces dont l'utilisateur est membre. En pratique, vous pouvez utiliser les deux types d'authentification lorsque vous appelez l'API Chat, en fonction de la conception et des fonctionnalités de votre application Chat.

Pour les appels asynchrones de l'API Chat

Le tableau suivant liste les méthodes de l'API Chat et leurs niveaux d'autorisation compatibles :

Méthode Authentification des utilisateurs prise en charge L'authentification par l'application est prise en charge. Champs d'application des autorisations acceptés
Espaces  
Créer un espace Avec l'authentification des utilisateurs :
  • chat.spaces.create
  • chat.spaces
  • chat.import
Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) :
  • chat.app.spaces.create
  • chat.app.spaces
Configurer un espace Avec l'authentification des utilisateurs :
  • chat.spaces.create
  • chat.spaces
Récupérer un espace Avec l'authentification des utilisateurs :
  • chat.spaces.readonly
  • chat.spaces
Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.spaces.readonly
Avec l'authentification de l'application :
  • chat.bot
Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) :
  • chat.app.spaces
Lister les espaces Avec l'authentification des utilisateurs :
  • chat.spaces.readonly
  • chat.spaces
Avec l'authentification de l'application :
  • chat.bot
Espaces de recherche Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.spaces.readonly
Mettre à jour un espace Avec l'authentification des utilisateurs :
  • chat.spaces
  • chat.import
Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.spaces
Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) :
  • chat.app.spaces
Supprimer un espace Avec l'authentification des utilisateurs :
  • chat.delete
  • chat.import
Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.delete
Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) :
  • chat.app.delete
Finaliser l'importation d'un espace Avec l'authentification des utilisateurs :
  • chat.import
Rechercher un message privé Avec l'authentification des utilisateurs :
  • chat.spaces.readonly
  • chat.spaces
Avec l'authentification de l'application :
  • chat.bot
Membres  
Créer un membre Avec l'authentification des utilisateurs :
  • chat.memberships
  • chat.memberships.app
  • chat.import
Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.memberships
Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) :
  • chat.app.memberships
Récupérer un membre Avec l'authentification des utilisateurs :
  • chat.memberships.readonly
  • chat.memberships
Avec l'authentification de l'application :
  • chat.bot
Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.memberships.readonly
Lister les membres Avec l'authentification des utilisateurs :
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Avec l'authentification de l'application :
  • chat.bot
Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.memberships.readonly
Supprimer un membre Avec l'authentification des utilisateurs :
  • chat.memberships
  • chat.memberships.app
  • chat.import
Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.memberships
Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) :
  • chat.app.memberships
Modifier un membre Avec l'authentification des utilisateurs :
  • chat.memberships
  • chat.import
Avec l'authentification des utilisateurs à l'aide des droits d'administrateur :
  • chat.admin.memberships
Avec l'authentification des applications et l'approbation de l'administrateur (disponibles en Preview développeur) :
  • chat.app.memberships
Messages  
Créer un message Avec l'authentification des utilisateurs :
  • chat.messages.create
  • chat.messages
  • chat.import
Avec l'authentification de l'application :
  • chat.bot
Récupérer un message Avec l'authentification des utilisateurs :
  • chat.messages.readonly
  • chat.messages
Avec l'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 l'authentification de l'application :
  • chat.bot
Supprimer un message Avec l'authentification des utilisateurs :
  • chat.messages
  • chat.import
Avec l'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
Emoji personnalisés  
Créer un emoji personnalisé Avec l'authentification des utilisateurs :
  • chat.customemojis
Supprimer un emoji personnalisé Avec l'authentification des utilisateurs :
  • chat.customemojis
Obtenir un emoji personnalisé Avec l'authentification des utilisateurs :
  • chat.customemojis
  • chat.customemojis.readonly
Lister les emoji personnalisés Avec l'authentification des utilisateurs :
  • chat.customemojis
  • chat.customemojis.readonly
Contenu multimédia et pièces jointes  
Importer des éléments multimédias en tant que pièces jointes 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 l'authentification de l'application :
  • chat.bot
Obtenir une pièce jointe d'un message Avec l'authentification de l'application :
  • chat.bot
États de lecture des utilisateurs
Obtenir l'état de lecture d'un espace pour un utilisateur Avec l'authentification des utilisateurs :
  • chat.users.readstate
  • chat.users.readstate.readonly
Mettre à jour l'état de lecture d'un espace pour un utilisateur Avec l'authentification des utilisateurs :
  • chat.users.readstate
Obtenir l'état de lecture d'un fil de discussion pour un utilisateur Avec l'authentification des utilisateurs :
  • chat.users.readstate
  • chat.users.readstate.readonly
Paramètres de l'espace utilisateur
Obtenir le paramètre de notification d'un utilisateur pour un espace Avec l'authentification des utilisateurs :
  • chat.users.spacesettings
Modifier le paramètre de notification d'un utilisateur pour un espace Avec l'authentification des utilisateurs :
  • chat.users.spacesettings
Événements dans l'espace
Obtenir les événements d'un espace Avec l'authentification de l'utilisateur, vous devez utiliser un champ d'application basé sur le type d'événement :
  • Pour les événements concernant les messages :
    • chat.messages
    • chat.messages.readonly
  • Pour les événements concernant les réactions :
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • Pour les événements concernant les abonnements :
    • chat.memberships
    • chat.memberships.readonly
  • Pour les événements concernant l'espace :
    • chat.spaces
    • chat.spaces.readonly
Lister les événements d'un espace Avec l'authentification des utilisateurs, vous devez utiliser un champ d'application pour chaque type d'événement inclus dans la requête :
  • Pour les événements concernant les messages :
    • chat.messages
    • chat.messages.readonly
  • Pour les événements concernant les réactions :
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • Pour les événements concernant les abonnements :
    • chat.memberships
    • chat.memberships.readonly
  • Pour les événements concernant l'espace :
    • chat.spaces
    • chat.spaces.readonly

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

Le tableau suivant répertorie les façons courantes dont les utilisateurs interagissent 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 L'authentification par l'application est prise en charge.
Recevoir des messages de :
Événements d'interaction avec les applications Chat
Rappels Apps Script
Google Cloud Pub/Sub
Répondre aux messages :
De manière synchrone, à l'aide d'un événement d'interaction avec une application Chat
De manière synchrone, à l'aide d'une valeur de retour de rappel Apps Script
Envoyer de nouveaux messages :
Avec les webhooks entrants