Chat-Apps und Google Chat API-Anfragen authentifizieren und autorisieren

Authentifizierung und Autorisierung sind Verfahren zur Überprüfung der Identität bzw. des Zugriffs auf Ressourcen. In diesem Dokument wird beschrieben, wie die Authentifizierung und Autorisierung für Chat-Apps und Chat API-Anfragen funktioniert.

Prozessübersicht

Das folgende Diagramm zeigt die allgemeinen Schritte zur Authentifizierung und Autorisierung für Google Chat:

Allgemeine Schritte zur Authentifizierung und Autorisierung in Google Chat
Abbildung 1. Allgemeine Schritte zur Authentifizierung und Autorisierung in Google Chat

  1. Google Cloud-Projekt konfigurieren, Chat API aktivieren und Chat-App konfigurieren:Während der Entwicklung erstellen Sie ein Google Cloud-Projekt. Im Google Cloud-Projekt aktivieren Sie die Chat API, konfigurieren die Chat-App und richten die Authentifizierung ein. Weitere Informationen finden Sie unter In Google Workspace entwickeln und Chat-App erstellen.

  2. Call Chat API:Wenn die App die Chat API aufruft, werden die Anmeldedaten zur Authentifizierung an die Chat API gesendet. Wenn sich Ihre Anwendung mit einem Dienstkonto authentifiziert, werden die Anmeldedaten als Teil des Anwendungscodes gesendet. Wenn Ihre Anwendung eine Chat API erfordert, die die Authentifizierung eines Nutzers verwendet, der noch nicht erteilt wurde, wird er aufgefordert, sich anzumelden.

  3. Ressourcen anfordern: Ihre Anwendung bittet um den Zugriff mit Gültigkeitsbereichen, die Sie beim Einrichten der Authentifizierung angeben.

  4. Um Einwilligung bitten:Wenn sich Ihre App als Nutzer authentifiziert, zeigt Google einen OAuth-Zustimmungsbildschirm an, über den der Nutzer entscheiden kann, ob er der App Zugriff auf die angeforderten Daten gewähren möchte. Für die Authentifizierung mit einem Dienstkonto ist keine Nutzereinwilligung erforderlich.

  5. Genehmigte Anfrage für Ressourcen senden: Wenn der Nutzer den Autorisierungsbereichen zustimmt, fasst Ihre Anwendung die Anmeldedaten und die vom Nutzer genehmigten Bereiche in einer Anfrage zusammen. Die Anfrage wird an den Google-Autorisierungsserver gesendet, um ein Zugriffstoken abzurufen.

  6. Google gibt ein Zugriffstoken zurück:Das Zugriffstoken enthält eine Liste der zugewiesenen Bereiche. Wenn die zurückgegebene Liste von Bereichen stärker eingeschränkt ist als die angeforderten Bereiche, deaktiviert Ihre Anwendung alle durch das Token eingeschränkten Features.

  7. Zugriff auf angeforderte Ressourcen:Ihre App verwendet das Zugriffstoken von Google, um die Chat API aufzurufen und auf Chat API-Ressourcen zuzugreifen.

  8. Aktualisierungstoken abrufen (optional): Wenn die Anwendung über die Lebensdauer eines einzelnen Zugriffstokens hinaus auf die Google Chat API zugreifen muss, kann sie ein Aktualisierungstoken abrufen. Weitere Informationen finden Sie unter Mit OAuth 2.0 auf Google APIs zugreifen.

  9. Mehr Ressourcen anfordern: Wenn Ihre Anwendung mehr Zugriff benötigt, wird der Nutzer gebeten, neue Bereiche zu gewähren. Dies führt zu einer neuen Anfrage zum Abrufen eines Zugriffstokens (Schritte 3–6).

Wann Chat-Apps eine Authentifizierung erfordern

Chat-Apps können synchron oder asynchron an Google Chat senden. Er kann auch Aufgaben für einen Nutzer erledigen, z. B. einen Chatbereich erstellen.

Für synchrone Nachrichten ist keine Authentifizierung erforderlich, es sei denn, die Chat-App ruft während der Verarbeitung einer Antwort die Chat API oder eine andere Google API auf.

Um asynchrone Nachrichten zu senden oder im Namen eines Nutzers zu arbeiten, stellen Chat-Apps RESTful-Anfragen an die Chat API, die eine Authentifizierung und Autorisierung erfordern.

Für synchrone Nachrichten ist keine Authentifizierung erforderlich.

Synchrone Nachrichten sind Antworten auf Chatereignisse. Google Chat-Apps können nach der Konfiguration und der Veröffentlichung der Ereignisse auf der Konfigurationsseite der Chat-App Ereignisse empfangen und darauf reagieren. Eine Authentifizierung oder Autorisierung ist nicht erforderlich.

Beispiele für synchrone Chatereignisse:

  • Ein Nutzer sendet eine Nachricht an eine Chat-App in Google Chat.
  • Ein Nutzer erwähnt eine Chat-App.
  • Ein Nutzer ruft einen der Slash-Befehle der Chat-App auf.

Das folgende Diagramm zeigt eine synchrone Anfrage/Antwort-Sequenz zwischen einem Chatnutzer und der Chat-App:

Für synchrone Nachrichten ist keine Autorisierung erforderlich.
Abbildung 2. Für synchrone Nachrichten ist keine Authentifizierung erforderlich.

  1. Der Nutzer sendet eine Nachricht an die Chat-App in Google Chat.
  2. Google Chat leitet die Nachricht an die App weiter.
  3. Die App empfängt die Nachricht, verarbeitet sie und gibt eine Antwort an Google Chat zurück.
  4. Google Chat rendert die Antwort für den Nutzer oder in einem Gruppenbereich.

Diese Sequenz wird für jedes Chatereignis wiederholt.

Asynchrone Nachrichten erfordern eine Authentifizierung

Asynchrone Nachrichten treten auf, wenn eine Chat-App eine Anfrage an die Chat API sendet, die eine Authentifizierung und Autorisierung erfordert.

Wenn Sie die Chat API aufrufen, können Chat-Apps Nachrichten in Google Chat posten oder Aufgaben ausführen und im Namen eines Nutzers auf Daten zugreifen. Nach dem Erkennen eines Serverausfalls kann eine Chat-App die Chat API beispielsweise aufrufen, um...

  • Erstellen Sie einen Chatbereich, um den Ausfall zu untersuchen und zu beheben.
  • Personen zum Chatbereich hinzufügen.
  • Veröffentlichen Sie eine Nachricht im Chatbereich, um Details zum Ausfall zu teilen.

Das folgende Diagramm zeigt eine asynchrone Nachrichtensequenz zwischen einer Chat-App und einem Chatbereich:

Authentifizierung für asynchrone Nachrichten erforderlich
Abbildung 3. Asynchrone Nachrichten erfordern eine Authentifizierung.

  1. Eine Chat-App erstellt eine Nachricht, indem sie die Chat API mit spaces.messages.create method aufruft und die Nutzeranmeldedaten in die HTTP-Anfrage einschließt.
  2. Google Chat authentifiziert die Chat-App mit Dienstkonto- oder Nutzeranmeldedaten.
  3. Google Chat rendert die Nachricht der Anwendung in einen bestimmten Chatbereich.

Chat API-Bereiche

Um die Zugriffsebene zu definieren, die Ihrer App gewährt wird, müssen Sie Autorisierungsbereiche angeben und deklarieren. Ein Autorisierungsbereich ist ein OAuth 2.0-URI-String, der den Namen der Google Workspace-Anwendung, die Art der Daten, auf die sie zugreift, und die Zugriffsebene enthält.

Google Chat unterstützt die folgenden Umfänge:

Google Chat API-Bereich Beschreibung
https://www.googleapis.com/auth/chat.bot Ermöglicht Chat-Apps, Chats anzusehen und Nachrichten zu senden. Gewährt Zugriff auf alle Funktionen, die für Chat-Apps verfügbar sind.
https://www.googleapis.com/auth/chat.delete Unterhaltungen und Gruppenbereiche löschen sowie den Zugriff auf verknüpfte Dateien in Google Chat entfernen.
Kanalmitgliedschaft  
https://www.googleapis.com/auth/chat.memberships Mitglieder in Google Chat-Unterhaltungen aufrufen, hinzufügen oder entfernen.
https://www.googleapis.com/auth/chat.memberships.app Ermöglicht es der Google Chat App, sich selbst (und nicht anderen Apps) zu Unterhaltungen in Google Chat hinzuzufügen oder daraus zu entfernen.
https://www.googleapis.com/auth/chat.memberships.readonly Details zu einer Mitgliedschaft und Liste von Mitgliedschaften in einem Gruppenbereich ansehen
Nachrichten  
https://www.googleapis.com/auth/chat.messages Nachrichten in Google Chat erstellen, abrufen, aktualisieren, löschen und auflisten
https://www.googleapis.com/auth/chat.messages.create Nachrichten erstellen und Anhänge in Google Chat hochladen
https://www.googleapis.com/auth/chat.messages.reactions Reaktionen auf Nachrichten in Google Chat ansehen, hinzufügen und löschen.
https://www.googleapis.com/auth/chat.messages.reactions.create Reaktionen auf Nachrichten in Google Chat hinzufügen.
https://www.googleapis.com/auth/chat.messages.reactions.readonly Reaktionen auf Nachrichten in Google Chat ansehen.
https://www.googleapis.com/auth/chat.messages.readonly Nachrichten in Google Chat abrufen und auflisten
Gruppenbereiche  
https://www.googleapis.com/auth/chat.spaces Unterhaltungen und Gruppenbereiche erstellen sowie Metadaten (einschließlich Einstellungen für den Verlauf) in Google Chat aufrufen oder aktualisieren.
https://www.googleapis.com/auth/chat.spaces.create Unterhaltungen in Google Chat erstellen
https://www.googleapis.com/auth/chat.spaces.readonly Chats und Gruppenbereiche in Google Chat aufrufen

Weitere Informationen zu Bereichen für Google Workspace APIs finden Sie unter Bereiche für Ihre Anwendung auswählen.

Eine Liste der verfügbaren Bereiche finden Sie unter OAuth 2.0-Bereiche für Google APIs.

Arten der erforderlichen Authentifizierung

Es gibt zwei Möglichkeiten, wie Chat-Apps mit der Chat API authentifiziert und autorisiert werden können: Nutzeranmeldedaten oder Dienstkonten.

Mit der Autorisierung für Anmeldedaten des Nutzers kann eine Chat-App auf Nutzerdaten zugreifen und Aktionen im Namen des Nutzers ausführen. OAuth-Umfänge geben die autorisierten Daten und Aktionen an. Diese Chat-Apps können jedoch nicht veröffentlicht werden. Weitere Informationen finden Sie unter Google Chat-Apps veröffentlichen.

Mit der App-Autorisierung greift eine Chat-App über Anmeldedaten für das Dienstkonto als App zu. Für die App-Autorisierung wird immer der Autorisierungsbereich chat.bot verwendet.

Als Domainadministrator können Sie die domainweite Delegierung von Befugnissen autorisieren, um dem Dienstkonto einer Anwendung Zugriff auf die Daten Ihrer Nutzer zu gewähren, ohne dass jeder Nutzer seine Einwilligung geben muss. Nachdem Sie die domainweite Delegierung konfiguriert haben, können Sie API-Aufrufe über Ihr Dienstkonto ausführen, um die Identität eines Nutzerkontos zu übernehmen. Obwohl ein Dienstkonto für die Authentifizierung verwendet wird, fungiert die domainweite Delegierung als Nutzer. Daher wird dies als Nutzerauthentifizierung betrachtet. Alle Funktionen, für die eine Nutzerauthentifizierung erforderlich ist, können die domainweite Delegierung verwenden.

Bei der Entscheidung, welche Art von Anmeldedaten für eine bestimmte API-Anfrage zu verwenden ist, solltest du bedenken, dass einige API-Methoden nur eine bestimmte Art von Anmeldedaten unterstützen. Wenn eine API-Methode beide Anmeldedaten unterstützt, wirkt sich der im Aufruf verwendete Anmeldedatentyp auf das zurückgegebene Ergebnis aus:

  • Bei der App-Autorisierung werden von den Methoden nur Ressourcen zurückgegeben, auf die die App zugreifen kann.
  • Bei der Nutzerautorisierung werden mit den Methoden nur Ressourcen zurückgegeben, auf die der Nutzer in der Chat-UI zugreifen kann.

Wenn Sie beispielsweise die Methode ListSpaces mit App-Autorisierung aufrufen, wird die Liste der Gruppenbereiche zurückgegeben, in denen die App Mitglied ist. Wenn Sie ListSpaces mit Nutzerautorisierung aufrufen, wird die Liste der Gruppenbereiche zurückgegeben, in denen der Nutzer Mitglied ist. In der Praxis kann Ihre App je nach den gewünschten Funktionen beide Autorisierungsarten verwenden, wenn sie die Chat API aufrufen.

Für asynchrone Chat API-Aufrufe

In der folgenden Tabelle sind die Chat API-Methoden und die unterstützten Autorisierungsbereiche aufgeführt:

Methode Nutzerauthentifizierung wird unterstützt. App-Authentifizierung unterstützt Unterstützte Autorisierungsbereiche
Gruppenbereiche  
Gruppenbereich erstellen
  • chat.spaces.create
  • chat.spaces
Gruppenbereiche einrichten
  • chat.spaces.create
  • chat.spaces
Gruppenbereich anfordern Mit der Nutzerauthentifizierung:
  • chat.spaces.readonly
  • chat.spaces
Mit App-Authentifizierung:
  • chat.bot
Gruppenbereiche auflisten Mit der Nutzerauthentifizierung:
  • chat.spaces.readonly
  • chat.spaces
Mit App-Authentifizierung:
  • chat.bot
Gruppenbereiche aktualisieren
  • chat.spaces
Gruppenbereiche löschen
  • chat.delete
Direktnachrichten suchen Mit der Nutzerauthentifizierung:
  • chat.spaces.readonly
  • chat.spaces
Mit App-Authentifizierung:
  • chat.bot
Mitglieder  
Mitglied erstellen
  • chat.memberships
  • chat.memberships.app
Mitglied werden Mit der Nutzerauthentifizierung:
  • chat.memberships.readonly
  • chat.memberships
Mit App-Authentifizierung:
  • chat.bot
Listenmitglieder Mit der Nutzerauthentifizierung:
  • chat.memberships.readonly
  • chat.memberships
Mit App-Authentifizierung:
  • chat.bot
Mitglieder löschen
  • chat.memberships
  • chat.memberships.app
Nachrichten  
Nachricht erstellen Mit der Nutzerauthentifizierung:
  • chat.messages.create
  • chat.messages
Mit App-Authentifizierung:
  • chat.bot
Nachricht erhalten Mit der Nutzerauthentifizierung:
  • chat.messages.readonly
  • chat.messages
Mit App-Authentifizierung:
  • chat.bot
Nachrichten auflisten
  • chat.messages.readonly
  • chat.messages
Nachricht aktualisieren Mit der Nutzerauthentifizierung:
  • chat.messages
Mit App-Authentifizierung:
  • chat.bot
Nachrichten löschen Mit der Nutzerauthentifizierung:
  • chat.messages
Mit App-Authentifizierung:
  • chat.bot
Reaktionen  
Reaktionen erstellen
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
Reaktionen auflisten
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Reaktionen löschen
  • chat.messages.reactions
  • chat.messages
Medien und Anhänge  
Medien als Dateianhang hochladen
  • chat.messages.create
  • chat.messages
Medien herunterladen Mit der Nutzerauthentifizierung:
  • chat.messages.readonly
  • chat.messages
Mit App-Authentifizierung:
  • chat.bot
Nachrichtenanhang abrufen
  • chat.bot

Für synchrones Empfangen und Beantworten von Nutzerinteraktionen

In der folgenden Tabelle sind die verschiedenen Möglichkeiten aufgeführt, wie Nutzer mit Chat-Apps interagieren und ob eine Authentifizierung erforderlich oder unterstützt wird:

Szenario Keine Authentifizierung erforderlich Nutzerauthentifizierung wird unterstützt. App-Authentifizierung unterstützt
Nachrichten empfangen von:
Chatereignisse
Apps Script-Callbacks
Cloud Pub/Sub
Nachrichten beantworten:
Synchron über ein Chatereignis
Synchron, über einen Apps Script-Callback-Wert
Neue Nachrichten senden:
Mit eingehenden Webhooks