S'authentifier en tant qu'application Google Chat

Ce guide explique comment configurer et utiliser un compte de service pour accéder à l'API Google Chat au nom d'une application Chat. Il vous explique d'abord comment créer un compte de service. Il explique ensuite comment écrire un script qui utilise le compte de service pour s'authentifier avec l'API Chat et publier un message dans un espace Chat.

Lorsqu'elles sont authentifiées avec un compte de service, les applications Chat doivent être membres d'un espace Chat pour obtenir des données ou effectuer des actions dans cet espace. Par exemple, pour répertorier les membres d'un espace ou créer un message dans un espace, l'application Chat doit elle-même être membre de l'espace. La seule exception concerne les applications Chat qui créent un espace avec authentification de l'application. Dans ce cas, l'application crée l'espace, puis devient automatiquement membre.

Les méthodes de l'API Google Chat compatibles avec l'autorisation d'application avec des champs d'application dont le nom commence par https://www.googleapis.com/auth/chat.app.* nécessitent une approbation par l'administrateur unique. Les méthodes d'API Google Chat qui prennent en charge l'autorisation d'application avec le champ d'application d'autorisation https://www.googleapis.com/auth/chat.bot ne nécessitent pas d'approbation supplémentaire. Les champs d'application d'autorisation https://www.googleapis.com/auth/chat.app.* sont disponibles dans la version Preview développeur.

Si votre application Chat doit accéder aux données utilisateur ou effectuer des actions en son nom, authentifiez-vous en tant qu'utilisateur. 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 Chat à accéder aux données de vos utilisateurs sans que chacun d'entre eux ait à donner son consentement. Pour en savoir plus, consultez la section S'authentifier et s'autoriser à l'aide de la délégation au niveau du domaine.

Pour en savoir plus sur les cas où les applications Chat nécessitent une authentification et sur le type d'authentification à utiliser, consultez la section Types d'authentification requise dans la présentation de l'API Chat concernant l'authentification et l'autorisation.

Prérequis

Java

  • JDK 1.7 ou version ultérieure
  • L'outil de gestion de paquets Maven
  • Projet Maven initialisé. Pour initialiser un projet, exécutez la commande suivante dans votre interface de ligne de commande: 
    mvn archetype:generate -DgroupId=com.google.chat.app.authsample -DartifactId=auth-sample-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
  • Une application Google Chat avec des fonctionnalités interactives. Pour créer une application Chat interactive à l'aide d'un service HTTP, suivez ce guide de démarrage rapide.
  • Ajoutez l'application Chat à un espace. Pour ajouter l'application Chat, consultez Tester les fonctionnalités interactives des applications Google Chat.

Python

Node.js

Apps Script

Étape 1: Créez un compte de service dans la console Google Cloud

Créez un compte de service que votre application Chat peut utiliser pour accéder aux API Google.

Créer un compte de service

Pour créer un compte de service, procédez comme suit :

console Google Cloud

  1. Dans la console Google Cloud, accédez à Menu > IAM et administration > Comptes de service.

    Accéder à la page "Comptes de service"

  2. Cliquez sur Créer un compte de service.
  3. Indiquez les détails du compte de service, puis cliquez sur Créer et continuer.
  4. Facultatif : Attribuez des rôles à votre compte de service pour accorder l'accès aux ressources de votre projet Google Cloud. Pour en savoir plus, consultez Accorder, modifier et révoquer les accès à des ressources.
  5. Cliquez sur Continuer.
  6. Facultatif : saisissez les utilisateurs ou les groupes autorisés à gérer et à effectuer des actions avec ce compte de service. Pour en savoir plus, consultez Gérer l'emprunt d'identité d'un compte de service.
  7. Cliquez sur OK. Notez l'adresse e-mail du compte de service.

CLI gcloud

  1. Créez le compte de service : 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. Facultatif : Attribuez des rôles à votre compte de service pour accorder l'accès aux ressources de votre projet Google Cloud. Pour en savoir plus, consultez Accorder, modifier et révoquer les accès à des ressources.

Le compte de service s'affiche sur la page du compte de service. Ensuite, créez une clé privée pour le compte de service.

Créer une clé privée

Pour créer et télécharger une clé privée pour le compte de service, procédez comme suit:

  1. Dans la console Google Cloud, accédez à Menu  > IAM et administration > Comptes de service.

    Accéder à la page "Comptes de service"

  2. Sélectionnez votre compte de service.
  3. Cliquez sur Clés > Ajouter une clé > Créer une clé.
  4. Sélectionnez JSON, puis cliquez sur Créer.

    Votre nouvelle paire de clés publique/privée est générée et téléchargée sur votre ordinateur en tant que nouveau fichier. Enregistrez le fichier JSON téléchargé sous le nom credentials.json dans votre répertoire de travail. Ce fichier est la seule copie de cette clé. Pour savoir comment stocker votre clé de manière sécurisée, consultez la section Gérer les clés de compte de service.

  5. Cliquez sur Fermer.

Pour en savoir plus sur les comptes de service, consultez la section Comptes de service dans la documentation Google Cloud IAM.

Créez ensuite un client OAuth compatible avec Google Workspace Marketplace pour ce compte de service.

Obtenir l'approbation de l'administrateur

Pour utiliser un champ d'application d'autorisation commençant par https://www.googleapis.com/auth/chat.app.*, qui est disponible dans une version Preview développeur, votre application Chat doit obtenir une approbation unique par l'administrateur.

Pour utiliser le champ d'autorisation https://www.googleapis.com/auth/chat.bot, aucune approbation de l'administrateur n'est requise.

Pour obtenir l'approbation de l'administrateur, vous devez préparer le compte de service de votre application Chat avec les informations suivantes:

  • Un client OAuth compatible avec Google Workspace Marketplace
  • Configuration de l'application dans le SDK Google Workspace Marketplace.

Créer un client OAuth compatible avec Google Workspace Marketplace

Pour créer un client OAuth compatible avec Google Workspace Marketplace, procédez comme suit:

  1. Dans la console Google Cloud, accédez à Menu  > IAM et administration > Comptes de service.

    Accéder à la page "Comptes de service"

  2. Cliquez sur le compte de service que vous avez créé pour votre application Chat.

  3. Cliquez sur Paramètres avancés.

  4. Cliquez sur Créer un client OAuth compatible avec Google Workspace Marketplace.

  5. Cliquez sur Continuer.

Un message de confirmation s'affiche pour indiquer qu'un client OAuth compatible avec Google Workspace Marketplace a été créé.

Configurer l'application Chat dans le SDK Google Workspace Marketplace

Pour configurer l'application Chat dans le SDK Google Workspace Marketplace, procédez comme suit:

  1. Dans la console Google Cloud, activez le SDK Google Workspace Marketplace.

    Activer le SDK Google Workspace Marketplace

  2. Dans la console Google Cloud, accédez à Menu > API et services > API et services activés > SDK Google Workspace Marketplace > Configuration de l'application.

    Accéder à la page "Configuration de l'application"

  3. Complétez la page "Configuration de l'application". La manière dont vous configurez votre application Chat dépend de votre audience cible et d'autres facteurs. Pour obtenir de l'aide pour remplir la page de configuration de l'application, consultez Configurer votre application dans le SDK Google Workspace Marketplace. Pour les besoins de ce guide, saisissez les informations suivantes:

    1. Sous Visibilité de l'application, sélectionnez Privé.
    2. Sous Paramètres d'installation, sélectionnez Installation individuelle et par administrateur.
    3. Sous Intégrations d'applications, sélectionnez Application Chat.

    4. Sous Champs d'application OAuth, saisissez tous les champs d'application d'authentification utilisés par votre application Chat.

    5. Sous Informations sur le développeur, saisissez votre nom de développeur, l'URL du site Web du développeur et l'adresse e-mail du développeur.

    6. Cliquez sur Enregistrer le brouillon.

Obtenir l'approbation de l'administrateur

Maintenant que votre compte de service est configuré pour recevoir l'approbation de l'administrateur, obtenez-la auprès d'un administrateur Google Workspace qui peut l'accorder en suivant la procédure décrite dans la section Configurer l'autorisation pour les applications Chat.

Étape 2: Installez la bibliothèque cliente Google et les autres dépendances

Installez la bibliothèque cliente Google et les autres dépendances requises pour le projet.

Java

Pour ajouter les bibliothèques clientes Google et d'autres dépendances requises à votre projet Maven, modifiez le fichier pom.xml dans le répertoire de votre projet et ajoutez les dépendances suivantes:

<dependencies>
  <!-- ... existing dependencies ... -->
  <dependency>
    <groupId>com.google.apis</groupId>
    <artifactId>google-api-services-chat</artifactId>
    <version>v1-rev20230905-2.0.0</version>
  </dependency>
  <dependency>
    <groupId>com.google.auth</groupId>
    <artifactId>google-auth-library-oauth2-http</artifactId>
    <version>1.19.0</version>
  </dependency>
  <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.10.1</version>
  </dependency>
</dependencies>

Python

Si vous n'avez pas encore installé les bibliothèques clientes Google pour Python, exécutez la commande suivante dans votre interface de ligne de commande:

pip3 install --upgrade google-api-python-client google-auth

Node.js

Pour ajouter les bibliothèques clientes Google à votre projet Node.js, accédez au répertoire de votre projet et exécutez la commande suivante dans votre interface de ligne de commande:

npm install "@googleapis/chat"

Apps Script

Cet exemple utilise la bibliothèque OAuth2 pour Apps Script afin de générer un jeton JWT pour l'authentification du compte de service. Pour ajouter la bibliothèque à votre projet Apps Script:

  1. Sur la gauche, cliquez sur Montage .
  2. Sur la gauche, à côté de Bibliothèques, cliquez sur Ajouter une bibliothèque .
  3. Saisissez l'ID de script 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
  4. Cliquez sur Rechercher, puis sur Ajouter.

Cet exemple utilise le service Chat avancé pour appeler l'API Google Chat. Pour activer le service pour votre projet Apps Script:

  1. Sur la gauche, cliquez sur Montage .
  2. À gauche, à côté de Services, cliquez sur Ajouter un service .
  3. Sélectionnez API Google Chat.
  4. Dans Version, sélectionnez v1.
  5. Cliquez sur Ajouter.

Vous pouvez utiliser n'importe quel langage compatible avec nos bibliothèques clientes.

Étape 3: Écrivez un script qui utilise le compte de service pour s'authentifier auprès de l'API Chat

Le code suivant s'authentifie auprès de l'API Chat à l'aide d'un compte de service, puis publie un message dans un espace Chat:

Java

  1. Dans le répertoire de votre projet, ouvrez le fichier src/main/java/com/google/chat/app/authsample/App.java.

  2. Remplacez le contenu de App.java par le code suivant:

    package com.google.chat.app.authsample;

import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.chat.v1.HangoutsChat;
import com.google.api.services.chat.v1.model.Message;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

/**
 * Authenticates with Chat API using service account credentials,
 * then creates a Chat message.
 */
public class App {
    // Specify required scopes.
    private static final String CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot";

    // Specify service account details.
    private static final String PRIVATE_KEY_RESOURCE_URI = "/credentials.json";

    public static void main( String[] args ) {
        try {
            // Run app.
            Message response = App.createChatMessage();
            // Print details about the created message.
            System.out.println(response);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static Message createChatMessage() throws Exception {
        // Build the Chat API client and authenticate with the service account.
        GoogleCredentials credentials = GoogleCredentials.fromStream(
            App.class.getResourceAsStream(PRIVATE_KEY_RESOURCE_URI))
            .createScoped(CHAT_SCOPE);
        HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);
        HangoutsChat chatService = new HangoutsChat.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            requestInitializer)
            .setApplicationName("auth-sample-app")
            .build();

        // The space to create the message in.
        //
        // Replace SPACE_NAME with a space name.
        // Obtain the space name from the spaces resource of Chat API,
        // or from a space's URL.
        String spaceName = "spaces/SPACE_NAME";

        // Create a Chat message.
        Message message = new Message().setText("Hello, world!");
        return chatService.spaces().messages().create(spaceName, message).execute();
    }
}

  3. Dans le code, remplacez SPACE_NAME par un nom d'espace, que vous pouvez obtenir à partir de la méthode spaces.list de l'API Chat ou de l'URL d'un espace.

  4. Créez un sous-répertoire nommé resources dans le répertoire de votre projet.

  5. Assurez-vous que le fichier de clé privée de votre compte de service est nommé credentials.json et copiez-le dans le sous-répertoire resources.

  6. Pour configurer Maven afin d'inclure le fichier de clé privée dans le package du projet, modifiez le fichier pom.xml dans le répertoire de votre projet et ajoutez la configuration suivante à la section <build>:

    <build>
  <!-- ... existing configurations ... -->
  <resources>
    <resource>
      <directory>resources</directory>
    </resource>
  </resources>
</build>

  7. Pour configurer Maven afin d'inclure les dépendances dans le package du projet et d'exécuter la classe principale de votre application, modifiez le fichier pom.xml dans le répertoire de votre projet et ajoutez la configuration suivante à la section <plugins>:

    <plugins>
  <!-- ... existing configurations ... -->
  <plugin>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
      <archive>
        <manifest>
          <mainClass>com.google.chat.app.authsample.App</mainClass>
        </manifest>
      </archive>
      <descriptorRefs>
        <descriptorRef>jar-with-dependencies</descriptorRef>
      </descriptorRefs>
    </configuration>
  </plugin>
</plugins>

Python

  1. Dans votre répertoire de travail, créez un fichier nommé chat_app_auth.py.

  2. Ajoutez le code suivant dans chat_app_auth.py:

    from apiclient.discovery import build
from google.oauth2 import service_account

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
creds = service_account.Credentials.from_service_account_file(
    'credentials.json', scopes=SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', credentials=creds)

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE_NAME with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE_NAME',

    # The message to create.
    body={'text': 'Hello, world!'}

).execute()

# Prints details about the created message.
print(result)

  3. Dans le code, remplacez SPACE_NAME par un nom d'espace, que vous pouvez obtenir à partir de la méthode spaces.list de l'API Chat ou de l'URL d'un espace. Assurez-vous que le fichier de clé privée de votre compte de service est nommé credentials.json.

Node.js

  1. Dans le répertoire de votre projet, créez un fichier nommé chat_app_auth.js.

  2. Incluez le code suivant dans chat_app_auth.js:

    const chat = require('@googleapis/chat');

async function createMessage() {
  const auth = new chat.auth.GoogleAuth({

    // Specify service account details.
    keyFilename: 'credentials.json',

    // Specify required scopes.
    scopes: ['https://www.googleapis.com/auth/chat.bot']

  });
  const authClient = await auth.getClient();

  // Create the Chat API client and authenticate with the service account.
  const chatClient = await chat.chat({
    version: 'v1',
    auth: authClient
  });

  // Create a Chat message.
  const result = await chatClient.spaces.messages.create({

    // The space to create the message in.
    //
    // Replace SPACE_NAME with a space name.
    // Obtain the space name from the spaces resource of Chat API,
    // or from a space's URL.
    parent: 'spaces/SPACE_NAME',

    // The message to create.
    requestBody: { 'text': 'Hello, world!' }

  });
  return result;
}

// Execute function then print details about the created message.
createMessage().then(console.log);

  3. Dans le code, remplacez SPACE_NAME par un nom d'espace, que vous pouvez obtenir à partir de la méthode spaces.list de l'API Chat ou de l'URL d'un espace. Assurez-vous que le fichier de clé privée de votre compte de service est nommé credentials.json.

Apps Script

  1. Dans l'éditeur Apps Script, modifiez le fichier appsscript.json et ajoutez le champ d'application OAuth nécessaire pour effectuer des requêtes externes afin d'obtenir le jeton OAuth du compte de service:

      "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]

  2. Enregistrez le code suivant dans un fichier nommé ChatAppAuth.gs dans votre projet Apps Script:

    // Specify the contents of the file credentials.json.
const CREDENTIALS = CREDENTIALS;

const SCOPE = 'https://www.googleapis.com/auth/chat.bot';

// The space to create the message in.
//
// Replace SPACE_NAME with a space name.
// Obtain the space name from the spaces resource of Chat API,
// or from a space's URL.
const PARENT = 'spaces/SPACE_NAME'

/**
 * Authenticates with Chat API using app credentials, then posts a message.
 */
function createMessageWithAppCredentials() {
  try {
    const service = getService_();
    if (!service.hasAccess()) {
      console.error(service.getLastError());
      return;
    }

    // Specify the message to create.
    const message = {'text': 'Hello world!'};

    // Call Chat API with a service account to create a message.
    const result = Chat.Spaces.Messages.create(
        message,
        PARENT,
        {},
        // Authenticate with the service account token.
        {'Authorization': 'Bearer ' + service.getAccessToken()});

    // Log details about the created message.
    console.log(result);

  } catch (err) {
    // TODO (developer) - Handle exception.
    console.log('Failed to create message with error %s', err.message);
  }
}

/**
 * Configures the OAuth library to authenticate with the service account.
 */
function getService_() {
  return OAuth2.createService(CREDENTIALS.client_email)
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(CREDENTIALS.private_key)
      .setIssuer(CREDENTIALS.client_email)
      .setSubject(CREDENTIALS.client_email)
      .setScope(SCOPE)
      .setPropertyStore(PropertiesService.getScriptProperties());
}

  3. Dans le code, remplacez CREDENTIALS par le contenu du fichier credentials.json.

  4. Dans le code, remplacez SPACE_NAME par un nom d'espace, que vous pouvez obtenir à partir de la méthode spaces.list de l'API Chat ou de l'URL d'un espace.

Étape 4: Exécutez l'exemple complet

Dans votre répertoire de travail, créez et exécutez l'exemple:

Java

mvn compile assembly:single
java -jar target/auth-sample-app-1.0-SNAPSHOT-jar-with-dependencies.jar

Python

python3 chat_app_auth.py

Node.js

node chat_app_auth.js

Apps Script

Ouvrez le fichier ChatAppAuth.gs dans l'éditeur Apps Script, puis cliquez sur Run (Exécuter).

Votre script envoie une requête authentifiée à l'API Chat, qui répond en publiant un message dans un espace Chat en tant qu'application Chat.

Résoudre l'exemple

Cette section décrit les problèmes courants que vous pouvez rencontrer lorsque vous essayez d'exécuter cet exemple.

Vous n'êtes pas autorisé à utiliser cette application

Lors de l'exécution du script, vous pouvez recevoir l'erreur suivante:

<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}/messages?alt=json returned "You are not permitted to use this app". Details: "You are not permitted to use this app">

Ce message d'erreur signifie que l'application Chat n'est pas autorisée à créer des messages Chat dans l'espace Chat spécifié.

Pour résoudre l'erreur, ajoutez l'application Chat à l'espace Chat spécifié dans le script.

L'administrateur doit accorder à l'application le champ d'application d'autorisation OAuth requis pour cette action.

Lorsque vous exécutez le script, vous pouvez recevoir le message d'erreur suivant:

<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}?alt=json returned "The administrator must grant the app the required OAuth authorization scope for this action.". Details: "The administrator must grant the app the required OAuth authorization scope for this action.">

Ce message d'erreur signifie qu'un administrateur Google Workspace n'a pas encore accordé une approbation unique à l'application Chat pour utiliser des champs d'autorisation commençant par le nom https://www.googleapis.com/auth/chat.app.*.

Pour résoudre l'erreur:

  • Demandez à l'administrateur Google Workspace d'approuver votre application Chat. Lorsque vous gérez cette erreur dans la logique de votre application Chat, envisagez d'envoyer un message annonçant que l'application Chat a besoin de l'approbation de l'administrateur pour effectuer l'action demandée, par exemple: To perform this action, I need approval. <https://support.google.com/a?p=chat-app-auth|Learn more>.
  • Si la méthode de l'API Google Chat est compatible avec le niveau d'autorisation https://www.googleapis.com/auth/chat.bot, qui ne nécessite pas l'approbation de l'administrateur, envisagez de l'utiliser à la place. Pour vérifier les portées d'autorisation compatibles avec une méthode, consultez la documentation de référence de l'API Google Chat.