Konzeptleitfaden für OAuth-Verknüpfungen

Der Typ OAuth-Verknüpfung unterstützt zwei branchenübliche OAuth 2.0-Abläufe: den impliziten und den Autorisierungscode. Im impliziten Codevorgang öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers. Nach erfolgreicher Anmeldung geben Sie ein langlebiges Zugriffstoken an Google zurück. Dieses Zugriffstoken ist dann in jeder Anfrage enthalten, die von Assistant an deine Aktion gesendet wird.

Die OAuth-Verknüpfung ist die empfohlene Kontoverknüpfungslösung, wenn Folgendes zutrifft:

  • Sie haben bereits eine Implementierung eines OAuth 2.0-Servers.Sie können den Endpunkt des Tokenaustauschs nicht erweitern, um Unterstützung für Google-Protokolle für die automatische Verknüpfung und Kontoerstellung aus einem ID-Token hinzuzufügen. Sie können also die Parameter intent=get und intent=create in Anfragen an diesen Endpunkt hinzufügen.

Ob die OAuth-Verknüpfung die richtige Lösung für dich ist, erfährst du auf der Seite Typ der Kontoverknüpfung auswählen.

Wichtige Begriffe

Bevor Sie sich über die Funktionsweise der OAuth-Verknüpfung informieren, machen Sie sich mit den folgenden Begriffen vertraut:

  • user.verificationStatus:Ein vom System festgelegtes Attribut, mit dem angegeben wird, ob in der aktuellen Sitzung ein bestätigter Nutzer vorhanden ist.

  • user.accountLinkingStatus: Ein vom System festgelegtes Attribut, mit dem angegeben wird, ob der Nutzer in der aktuellen Sitzung eine verknüpfte Identität hat.

  • Systemszene für die Kontoverknüpfung:Eine vordefinierte Szene, die den Bestätigungsvorgang für die Kontoverknüpfung implementiert und an bestimmte Anwendungsfälle angepasst werden kann.

  • Vorgang mit Autorisierungscode:Während dieses OAuth 2.0-Vorgangs öffnet Google deinen Autorisierungsendpunkt im Browser des Nutzers. Wenn die Anmeldung erfolgreich ist, erstellt der Dienst einen Autorisierungscode und gibt ihn an Google zurück. Google sendet diesen Autorisierungscode an den Endpunkt des Tokenaustauschs, der die Authentizität des Codes überprüft und ein Zugriffstoken und ein Aktualisierungstoken zurückgibt.

    Dieser Ablauf erfordert zwei Endpunkte:

    • Autorisierungsendpunkt:Der Endpunkt, über den die Einwilligung von Nutzern in den Datenzugriff eingeholt wird. Dieser Endpunkt hat folgende Aufgaben:
      1. Damit wird Nutzern, die noch nicht angemeldet sind, die Anmelde-UI angezeigt.
      2. Zeichnet die Einwilligung für den angeforderten Zugriff in Form eines kurzlebigen Autorisierungscodes auf.
    • Endpunkt zum Tokenaustausch:Mit diesem Endpunkt werden verschlüsselte Strings abgerufen, sogenannte Tokens. Damit autorisieren Sie den Nutzer der Aktion, auf Ihren Dienst zuzugreifen. Dieser Endpunkt ist für zwei Arten von Austauschen zuständig:
      1. Tauscht einen Autorisierungscode gegen ein langlebiges Aktualisierungstoken und ein kurzlebiges Zugriffstoken aus. Dieser Austausch findet statt, wenn der Nutzer den Prozess zur Kontoverknüpfung durchläuft.
      2. Tauscht ein langlebiges Aktualisierungstoken gegen ein kurzlebiges Zugriffstoken aus. Dieser Austausch findet statt, wenn Google ein neues Zugriffstoken benötigt, weil das abgelaufene Token abgelaufen ist.

  • Impliziter Codeablauf:Während dieses OAuth 2.0-Vorgangs öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers. Wenn die Anmeldung erfolgreich ist, geben Sie ein langlebiges Zugriffstoken an Google zurück. Dieses Zugriffstoken ist dann in jeder Anfrage enthalten, die von Assistant an deine Aktion gesendet wird. Für diesen Ablauf ist nur ein Autorisierungsendpunkt erforderlich.

  • Zugriffstoken: Ein Token, das Ihren Dienst für den Zugriff auf Teile der Daten eines Nutzers autorisiert. Zugriffstokens sind mit jedem einzelnen Nutzer verknüpft und sollten nicht erraten werden können.

  • Aktualisierungstoken: Ein Token, das gegen ein neues Zugriffstoken ausgetauscht wird, sobald ein kurzlebiges Zugriffstoken abgelaufen ist.

Funktionsweise

In diesem Abschnitt werden der allgemeine Ablauf für den OAuth-Autorisierungscode und implizite Abläufe beschrieben. Im folgenden Abschnitt OAuth-Verknüpfungsabläufe werden die verschiedenen Abläufe beschrieben, die mit OAuth ausgeführt werden können.

Der Vorgang mit Autorisierungscode kann so zusammengefasst werden:

  1. Deine Aktion fragt den Nutzer, ob er sein Konto mit deinem Dienst verknüpfen möchte.
  2. Nachdem der Nutzer der Verknüpfung der Konten zustimmt, öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers. Wenn der Ablauf für eine Aktion auf einem sprachgesteuerten Gerät gestartet wurde, würde Google die Ausführung auf ein Smartphone übertragen.
  3. Der Nutzer meldet sich an (sofern er noch nicht angemeldet ist) und erteilt Google die Berechtigung, über Ihre API auf seine Daten zuzugreifen, sofern er dies noch nicht getan hat.
  4. Der Dienst erstellt einen Autorisierungscode und gibt ihn an Google zurück. Dazu wird der Browser des Nutzers mit dem an die Anfrage angehängten Autorisierungscode wieder zu Google weitergeleitet.
  5. Google sendet den Autorisierungscode an den Endpunkt des Tokenaustauschs, der die Authentizität des Codes überprüft und ein Zugriffstoken und ein Aktualisierungstoken zurückgibt. Das Zugriffstoken ist ein kurzlebiges Token, das Ihr Dienst als Anmeldedaten für den Zugriff auf APIs akzeptiert. Das Aktualisierungstoken ist ein langlebiges Token, das Google speichern und verwenden kann, um neue Zugriffstokens zu erhalten, wenn sie ablaufen.
  6. Nachdem der Nutzer den Kontoverknüpfungsvorgang abgeschlossen hat, enthält jede nachfolgende Anfrage, die von Assistant an den Auftragsausführungs-Webhook gesendet wird, ein Zugriffstoken.

Der implizite Codefluss kann so zusammengefasst werden:

  1. Deine Aktion fragt den Nutzer, ob er sein Konto mit deinem Dienst verknüpfen möchte.
  2. Nachdem der Nutzer der Verknüpfung der Konten zustimmt, öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers.
  3. Der Nutzer meldet sich an (sofern er noch nicht angemeldet ist) und erteilt Google die Berechtigung, über Ihre API auf seine Daten zuzugreifen, sofern er dies noch nicht getan hat.
  4. Ihr Dienst erstellt ein Zugriffstoken und gibt es an Google zurück, indem er den Browser des Nutzers wieder zu Google weiterleitet, wobei das Zugriffstoken an die Anfrage angehängt ist.
  5. Nachdem der Nutzer die Kontoverknüpfung abgeschlossen hat, ruft Google die APIs Ihres Dienstes auf und hängt das Zugriffstoken an jede Anfrage an. Der Dienst überprüft, ob das Zugriffstoken Google die Autorisierung für den Zugriff auf die API gewährt, und führt dann den API-Aufruf aus.

Der grundlegende Ablauf mit Autorisierungscode sieht so aus:

  1. Deine Aktion fragt den Nutzer, ob er sein Konto mit deinem Dienst verknüpfen möchte.
  2. Nachdem der Nutzer der Verknüpfung der Konten zustimmt, öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers. Wenn der Ablauf für eine Aktion auf einem sprachgesteuerten Gerät gestartet wurde, würde Google die Ausführung auf ein Smartphone übertragen.
  3. Der Nutzer meldet sich an (sofern er noch nicht angemeldet ist) und erteilt Google die Berechtigung, über Ihre API auf seine Daten zuzugreifen, sofern er dies noch nicht getan hat.
  4. Der Dienst erstellt einen Autorisierungscode und gibt ihn an Google zurück. Dazu wird der Browser des Nutzers wieder an Google weitergeleitet und der kurzlebige Autorisierungscode an die Anfrage angehängt.
  5. Google sendet den Autorisierungscode an den Endpunkt des Tokenaustauschs, der die Authentizität des Codes überprüft und ein Zugriffstoken und ein Aktualisierungstoken zurückgibt. Das Zugriffstoken ist ein kurzlebiges Token, das Ihr Dienst als Anmeldedaten für den Zugriff auf APIs akzeptiert. Das Aktualisierungstoken ist ein langlebiges Token, das Google speichern und verwenden kann, um neue Zugriffstokens zu erhalten, wenn sie ablaufen.
  6. Nachdem der Nutzer den Kontoverknüpfungsvorgang abgeschlossen hat, enthält jede nachfolgende Anfrage, die von Assistant an den Auftragsausführungs-Webhook gesendet wird, ein Zugriffstoken.

OAuth-Verknüpfungsabläufe

In diesem Abschnitt werden die verschiedenen Abläufe bei der OAuth-Verknüpfung beschrieben.

Jeder Ablauf enthält diese allgemeinen Schritte, nachdem der Nutzer deine Aktion aufgerufen hat:

Im obigen Ablauf wechseln Sie zur Szene des Kontoverknüpfungssystems und geben eine individuelle Begründung an. Assistant fragt den Nutzer, ob er sein Konto mit Ihrem Dienst verknüpfen möchte, und zeigt ihm einen Bildschirm mit den angeforderten Berechtigungen. Wenn der Nutzer einwilligt, leitet Google ihn dann zum Autorisierungsendpunkt Ihres Dienstes im Browser weiter. Der Nutzer meldet sich an (oder erstellt je nach Konfiguration ein neues Konto) und erteilt Ihrer Aktion die Berechtigung, auf seine Daten zuzugreifen.

Die Abläufe danach unterscheiden sich je nachdem, ob Sie den impliziten Vorgang oder den Vorgang mit Autorisierungscode implementiert haben. Diese Abläufe werden in den folgenden Abschnitten beschrieben.

Ablauf 1: Nutzer meldet sich mit implizitem Vorgang an

Nachdem sich der Nutzer angemeldet und seine Anmeldedaten verifiziert haben, erstellt Ihr Dienst ein langlebiges Zugriffstoken und gibt es an Google zurück. An dieser Stelle ist die Identität des Nutzers in deiner Aktion mit dem Konto verknüpft, mit dem er sich angemeldet hat, und das Zugriffstoken wird an jeden API-Aufruf von Google an die APIs deines Dienstes angehängt.

Ablauf 2: Nutzer meldet sich mit Autorisierungscode an

Nachdem sich der Nutzer angemeldet und seine Anmeldedaten bestätigt haben, erstellt Ihr Dienst einen Autorisierungscode und gibt ihn an Google zurück.

Dieser Autorisierungscode wird an den Endpunkt des Tokenaustauschs gesendet, der sowohl ein Zugriffstoken als auch ein Aktualisierungstoken zurückgibt. An dieser Stelle ist die Identität des Nutzers in deiner Aktion mit dem Konto verknüpft, mit dem er sich angemeldet hat. Jede nachfolgende Anfrage, die von Assistant an deine Auftragsausführung gesendet wird, enthält ein Zugriffstoken.