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

Authentifizierung und Autorisierung sind Mechanismen 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, die Chat API aktivieren und die Chat-App konfigurieren:Während der Entwicklung erstellen Sie ein Google Cloud-Projekt. Im Google Cloud-Projekt aktivieren Sie die Chat API, konfigurieren Ihre Chat-Anwendung und richten die Authentifizierung ein. Weitere Informationen finden Sie unter In Google Workspace entwickeln und Chat-App erstellen.

  2. Call Chat API:Wenn Ihre Anwendung die Chat API aufruft, sendet sie Anmeldedaten zur Authentifizierung an die Chat API. Bei der Authentifizierung Ihrer Anwendung mit einem Dienstkonto werden die Anmeldedaten als Teil des Anwendungscodes gesendet. Wenn in Ihrer Anwendung die Chat API mit einer noch nicht gewährten Authentifizierung eines Nutzers aufgerufen werden muss, wird der Nutzer aufgefordert, sich anzumelden.

  3. Ressourcen anfordern: Ihre Anwendung fordert Zugriff mit Bereichen an, die Sie beim Einrichten der Authentifizierung angeben.

  4. Nach Einwilligung fragen:Wenn sich Ihre Anwendung als Nutzer authentifiziert, zeigt Google einen OAuth-Zustimmungsbildschirm an, damit der Nutzer entscheiden kann, ob er Ihrer Anwendung 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, bündelt Ihre App die Anmeldedaten und die vom Nutzer genehmigten Bereiche in einer Anfrage. 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 gewährten Bereiche. Ist die zurückgegebene Liste der Bereiche restriktiver als die angeforderten Bereiche, deaktiviert die Anwendung alle durch das Token eingeschränkten Funktionen.

  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 Ihre 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. Weitere Ressourcen anfordern:Wenn Ihre Anwendung mehr Zugriff benötigt, wird der Nutzer aufgefordert, neue Bereiche zu gewähren. Dies führt zu einer neuen Anfrage zum Abrufen eines Zugriffstokens (Schritte 3–6).

Wenn Chat-Apps eine Authentifizierung erfordern

Chat-Apps können Nachrichten als Reaktion auf eine Nutzerinteraktion oder asynchron senden. Außerdem können sie Aufgaben im Namen eines Nutzers ausführen, z. B. einen Chatbereich erstellen oder eine Liste von Personen in einem Chatbereich abrufen.

Chatanwendungen erfordern keine Authentifizierung, um auf eine Nutzerinteraktion zu reagieren, es sei denn, die Chat-App ruft während der Verarbeitung einer Antwort die Chat API oder eine andere Google API auf.

Chatanwendungen stellen RESTful-Anfragen an die Chat API, um asynchrone Nachrichten zu senden oder Aufgaben im Namen eines Nutzers auszuführen. Hierfür ist eine Authentifizierung und Autorisierung erforderlich.

Antworten auf Nutzerinteraktionen erfordern keine Authentifizierung

Google Chat-Anwendungen müssen sich nicht als Nutzer oder Chat-App authentifizieren, um Interaktionsereignisse zu empfangen und synchron darauf zu antworten.

Google Chat-Apps empfangen jedes Mal Interaktionsereignisse, wenn ein Nutzer mit einer Chat-App interagiert oder diese aufruft, darunter:

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

Das folgende Diagramm zeigt eine Anfrage-Antwort-Abfolge zwischen einem Chat-Nutzer und einer Chat-App:

Keine Autorisierung für Interaktionsereignisse in Chat-Apps erforderlich
Abbildung 2: Für Interaktionsereignisse in einer Chat-App 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 wiederholt sich für jedes Interaktionsereignis der Chat-App.

Asynchrone Nachrichten erfordern eine Authentifizierung

Asynchrone Nachrichten treten auf, wenn eine Chat-Anwendung eine Anfrage an die Chat API sendet, für die eine Authentifizierung und Autorisierung erforderlich ist.

Durch Aufrufen der Chat API können Chat-Apps Nachrichten in Google Chat posten oder im Namen eines Nutzers Aufgaben erledigen und auf Daten zugreifen. Nachdem ein Serverausfall erkannt wurde, kann eine Chat-App beispielsweise die Chat API für Folgendes aufrufen:

  • Erstellen Sie einen Chatbereich, der für die Untersuchung und Behebung des Ausfalls vorgesehen ist.
  • Fügen Sie dem Chatbereich Personen hinzu.
  • Posten Sie eine Nachricht im Chatbereich mit Details zum Ausfall.

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 der Methode spaces.messages.create aufruft, und fügt Nutzeranmeldedaten in die HTTP-Anfrage ein.
  2. Google Chat authentifiziert die Chat-App mit Dienstkonto- oder Nutzeranmeldedaten.
  3. Google Chat rendert die Nachricht der App in einen angegebenen Chatbereich.

Chat API-Bereiche

Konfigurieren Sie den OAuth-Zustimmungsbildschirm und wählen Sie Bereiche aus, um festzulegen, welche Informationen Nutzern und Anwendungsprüfern angezeigt werden. Registrieren Sie Ihre Anwendung, damit Sie sie später veröffentlichen können.

Zum Definieren der Zugriffsebene für Ihre Anwendung müssen Sie Autorisierungsbereiche identifizieren 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.

Nicht vertrauliche Bereiche

Bereichscode Beschreibung
https://www.googleapis.com/auth/chat.bot

Der Bereich chat.bot unterstützt nur Dienstkonten. Mit diesem Bereich ist keine Authentifizierung mit Nutzeranmeldedaten oder bei der domainweiten Delegierung möglich.

Hiermit können Chat-Apps Chats ansehen und Nachrichten senden. Gewährt Zugriff auf alle Funktionen, die für Chat-Apps verfügbar sind.

Sensible Bereiche

Bereichscode Beschreibung
https://www.googleapis.com/auth/chat.spaces In Chat Unterhaltungen und Gruppenbereiche erstellen sowie Metadaten (einschließlich Einstellungen für den Verlauf) ansehen oder aktualisieren.
https://www.googleapis.com/auth/chat.spaces.create Sie können neue Unterhaltungen in Google Chat erstellen.
https://www.googleapis.com/auth/chat.spaces.readonly Chats und Gruppenbereiche in Google Chat ansehen.
https://www.googleapis.com/auth/chat.memberships Mitglieder in Google Chat-Unterhaltungen ansehen, hinzufügen und entfernen.
https://www.googleapis.com/auth/chat.memberships.app Sich selbst zu Unterhaltungen in Google Chat hinzufügen oder daraus entfernen.
https://www.googleapis.com/auth/chat.memberships.readonly Mitglieder in Chat-Unterhaltungen ansehen.
https://www.googleapis.com/auth/chat.messages.create Schreiben und senden Sie Nachrichten in Google Chat.
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 eine Nachricht in Google Chat ansehen.
https://www.googleapis.com/auth/chat.users.readstate „Zuletzt gelesen“-Zeit für Chat-Unterhaltungen ansehen und ändern.
https://www.googleapis.com/auth/chat.users.readstate.readonly Zeit der zuletzt gelesenen Nachrichten für Chat-Unterhaltungen ansehen.

Eingeschränkte Bereiche

Bereichscode Beschreibung
https://www.googleapis.com/auth/chat.delete Sie können Unterhaltungen und Gruppenbereiche löschen sowie den Zugriff auf verknüpfte Dateien in Chat entfernen.
https://www.googleapis.com/auth/chat.import Gruppenbereiche, Nachrichten und Mitgliedschaften in Google Chat importieren Weitere Informationen finden Sie unter Chat-Apps zum Importieren von Daten autorisieren.
https://www.googleapis.com/auth/chat.messages Sie können Nachrichten ansehen, verfassen, senden, aktualisieren und löschen sowie Reaktionen auf Nachrichten hinzufügen, ansehen und löschen.
https://www.googleapis.com/auth/chat.messages.readonly Nachrichten und Reaktionen in Google Chat ansehen.

Die Bereiche in den vorherigen Tabellen geben ihre Vertraulichkeit gemäß den folgenden Definitionen an:

Wenn Ihre Anwendung Zugriff auf andere Google APIs benötigt, können Sie diese Bereiche ebenfalls hinzufügen. Weitere Informationen zu Google API-Bereichen finden Sie unter Mit OAuth 2.0 auf Google APIs zugreifen.

Weitere Informationen zu Bereichen für Google Workspace APIs finden Sie unter OAuth-Zustimmungsbildschirm konfigurieren und Bereiche auswählen.

Arten erforderlicher Authentifizierungen

Es gibt zwei Möglichkeiten, wie sich Chat-Apps bei der Chat API authentifizieren und autorisieren können: Nutzeranmeldedaten oder Dienstkonten.

Mit der Autorisierung der Nutzeranmeldedaten kann eine Chat-Anwendung auf Nutzerdaten zugreifen und im Namen eines Nutzers Aktionen ausführen. OAuth-Bereiche geben die autorisierten Daten und Aktionen an. Diese Chat-Apps können jedoch nicht öffentlich veröffentlicht werden. Weitere Informationen finden Sie unter Google Chat-Apps veröffentlichen.

Mit der App-Autorisierung greift eine Chat-App mit Dienstkonto-Anmeldedaten auf die API als Anwendung zu. Für die App-Autorisierung wird immer der Autorisierungsbereich chat.bot verwendet.

Als Domainadministrator können Sie eine domainweite Delegierung von Befugnissen gewähren, um das Dienstkonto einer Anwendung für den Zugriff auf die Daten Ihrer Nutzer zu autorisieren, ohne dass jeder Nutzer seine Zustimmung 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 zur Authentifizierung verwendet wird, wird die domainweite Delegierung der Identität eines Nutzers nachgeahmt und gilt daher als Nutzerauthentifizierung. Alle Funktionen, für die eine Nutzerauthentifizierung erforderlich ist, kann die domainweite Delegierung verwenden.

Bei der Entscheidung, welche Art von Anmeldedaten für eine bestimmte API-Anfrage verwendet werden, ist zu beachten, dass einige API-Methoden nur einen bestimmten Berechtigungstyp unterstützen. Wenn eine API-Methode beide Anmeldedaten unterstützt, wirkt sich der im Aufruf verwendete Typ der Anmeldedaten auf das zurückgegebene Ergebnis aus:

  • Bei der Anwendungsautorisierung geben die Methoden nur Ressourcen zurück, auf die die App zugreifen kann.
  • Mit der Nutzerautorisierung geben die Methoden nur Ressourcen zurück, auf die der Nutzer über die Chat-UI zugreifen kann.

Wenn Sie beispielsweise die Methode ListSpaces mit der Anwendungsautorisierung aufrufen, wird eine Liste der Gruppenbereiche zurückgegeben, in denen die Anwendung Mitglied ist. Beim Aufrufen von ListSpaces mit Nutzerautorisierung wird die Liste der Gruppenbereiche zurückgegeben, in denen der Nutzer Mitglied ist. In der Praxis verwendet Ihre Anwendung beim Aufrufen der Chat API möglicherweise beide Autorisierungsarten, je nach der gewünschten Funktionalität.

Für asynchrone Chat API-Aufrufe

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

Methode Nutzerauthentifizierung wird unterstützt. App-Authentifizierung wird unterstützt. Unterstützte Autorisierungsbereiche
Gruppenbereiche  
Gruppenbereich erstellen Mit der Nutzerauthentifizierung:
  • chat.spaces.create
  • chat.spaces
  • chat.import
Gruppenbereich einrichten Mit der Nutzerauthentifizierung:
  • chat.spaces.create
  • chat.spaces
Gruppenbereich erstellen Mit der Nutzerauthentifizierung:
  • chat.spaces.readonly
  • chat.spaces
Mit der App-Authentifizierung:
  • chat.bot
Gruppenbereiche auflisten Mit der Nutzerauthentifizierung:
  • chat.spaces.readonly
  • chat.spaces
Mit der App-Authentifizierung:
  • chat.bot
Gruppenbereiche aktualisieren Mit der Nutzerauthentifizierung:
  • chat.spaces
  • chat.import
Gruppenbereiche löschen Mit der Nutzerauthentifizierung:
  • chat.delete
  • chat.import
Importvorgang für einen Gruppenbereich abschließen Mit der Nutzerauthentifizierung:
  • chat.import
Direktnachrichten suchen Mit der Nutzerauthentifizierung:
  • chat.spaces.readonly
  • chat.spaces
Mit der App-Authentifizierung:
  • chat.bot
Mitglieder  
Mitglied erstellen Mit der Nutzerauthentifizierung:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Mitglied werden Mit der Nutzerauthentifizierung:
  • chat.memberships.readonly
  • chat.memberships
Mit der App-Authentifizierung:
  • chat.bot
Listenmitglieder Mit der Nutzerauthentifizierung:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
Mit der App-Authentifizierung:
  • chat.bot
Mitglied löschen Mit der Nutzerauthentifizierung:
  • chat.memberships
  • chat.memberships.app
  • chat.import
Nachrichten  
Mitteilung erstellen Mit der Nutzerauthentifizierung:
  • chat.messages.create
  • chat.messages
  • chat.import
Mit der App-Authentifizierung:
  • chat.bot
Nachricht erhalten Mit der Nutzerauthentifizierung:
  • chat.messages.readonly
  • chat.messages
Mit der App-Authentifizierung:
  • chat.bot
Nachrichten auflisten Mit der Nutzerauthentifizierung:
  • chat.messages.readonly
  • chat.messages
  • chat.import
Nachrichten aktualisieren Mit der Nutzerauthentifizierung:
  • chat.messages
  • chat.import
Mit der App-Authentifizierung:
  • chat.bot
Nachrichten löschen Mit der Nutzerauthentifizierung:
  • chat.messages
  • chat.import
Mit der App-Authentifizierung:
  • chat.bot
Reaktionen  
Reaktionen erstellen Mit der Nutzerauthentifizierung:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
Reaktionen auflisten Mit der Nutzerauthentifizierung:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
Reaktionen löschen Mit der Nutzerauthentifizierung:
  • chat.messages.reactions
  • chat.messages
  • chat.import
Medien und Anhänge  
Medien als Dateianhang hochladen Mit der Nutzerauthentifizierung:
  • chat.messages.create
  • chat.messages
  • chat.import
Medien herunterladen Mit der Nutzerauthentifizierung:
  • chat.messages.readonly
  • chat.messages
Mit der App-Authentifizierung:
  • chat.bot
Nachrichtenanhang abrufen Mit der App-Authentifizierung:
  • chat.bot
Lesestatus für Nutzer
Lesestatus eines Nutzers zum Gruppenbereich abrufen Mit der Nutzerauthentifizierung:
  • chat.users.readstate
  • chat.users.readstate.readonly
Lesestatus für den Gruppenbereich eines Nutzers aktualisieren Mit der Nutzerauthentifizierung:
  • chat.users.readstate
Lesestatus des Threads eines Nutzers abrufen Mit der Nutzerauthentifizierung:
  • chat.users.readstate
  • chat.users.readstate.readonly

Für Chat-App-Interaktionsereignisse

In der folgenden Tabelle sehen Sie, wie Nutzer häufig mit Chat-Apps interagieren und ob eine Authentifizierung erforderlich ist oder unterstützt wird:

Szenario Keine Authentifizierung erforderlich Nutzerauthentifizierung wird unterstützt. App-Authentifizierung wird unterstützt.
Nachrichten erhalten von:
Interaktionsereignisse in Chat-Apps
Apps Script-Callbacks
Cloud Pub/Sub
So antworten Sie auf Nachrichten:
Synchronisiert über ein Interaktionsereignis in der Chat-App
Synchrone Verwendung eines Apps Script-Callback-Rückgabewerts
Neue Nachrichten senden:
Mit eingehenden Webhooks