Google-Kontoverknüpfung mit OAuth

Konten werden über die Branchenstandards impliziter und Autorisierungscode-Abläufe von OAuth 2.0 verknüpft.

OAuth 2.1 und PKCE für Agents

Für zustandslose KI-Agents und multimodale Pipelines wird die Erzwingung von OAuth 2.1 empfohlen.

  • PKCE (Proof Key for Code Exchange): Muss verwendet werden, um den Autorisierungscode-Vorgang zu sichern und Abfangangriffe zu verhindern.
  • Kein impliziter Ablauf: Beim impliziten Ablauf werden Zugriffstokens in der URL offengelegt, was ein Sicherheitsrisiko für Agent-Umgebungen darstellt.

Ihr Dienst muss OAuth 2.0/2.1-konforme Autorisierungs - und Token-Austausch-Endpunkte unterstützen.

Im impliziten Ablauf öffnet Google Ihren Autorisierungsendpunkt im Browser des Nutzers. Nach erfolgreicher Anmeldung geben Sie ein langlebiges Zugriffstoken an Google zurück. Dieses Zugriffstoken ist jetzt in jeder von Google gesendeten Anfrage enthalten.

Beim Autorisierungscode-Ablauf benötigen Sie zwei Endpunkte:

  • Der Autorisierungsendpunkt, über den die Anmeldeoberfläche für Nutzer angezeigt wird, die noch nicht angemeldet sind. Am Autorisierungsendpunkt wird auch ein kurzlebiger Autorisierungscode erstellt, um die Einwilligung der Nutzer für den angeforderten Zugriff aufzuzeichnen.

  • Der Tokenaustausch-Endpunkt, der für zwei Arten von Austauschvorgängen zuständig ist:

    1. Tauscht einen Autorisierungscode gegen ein langlebiges Aktualisierungstoken und ein kurzlebiges Zugriffstoken ein. Dieser Austausch findet statt, wenn der Nutzer den Ablauf zur Kontoverknüpfung durchläuft.
    2. Tauscht ein langlebiges Aktualisierungstoken gegen ein kurzlebiges Zugriffstoken ein. Dieser Austausch erfolgt, wenn Google ein neues Zugriffstoken benötigt, weil das vorhandene abgelaufen ist.

OAuth 2.0-Vorgang auswählen

Der implizite Ablauf ist zwar einfacher zu implementieren, Google empfiehlt jedoch, dass Zugriffstokens, die über den impliziten Ablauf ausgestellt werden, niemals ablaufen. Das liegt daran, dass der Nutzer sein Konto nach Ablauf eines Tokens mit dem impliziten Ablauf noch einmal verknüpfen muss. Wenn Sie aus Sicherheitsgründen ein Ablaufdatum für Tokens benötigen, empfehlen wir dringend, stattdessen den Autorisierungscode-Ablauf zu verwenden.

Gestaltungsrichtlinien

In diesem Abschnitt werden die Designanforderungen und ‑empfehlungen für den Nutzerbildschirm beschrieben, den Sie für OAuth-Verknüpfungsabläufe hosten. Nachdem die Funktion von der Google-App aufgerufen wurde, zeigt Ihre Plattform dem Nutzer eine Anmeldeseite für Google und einen Bildschirm zur Einwilligung in die Kontoverknüpfung an. Nachdem der Nutzer der Kontoverknüpfung zugestimmt hat, wird er zur Google-App zurückgeleitet.

In dieser Abbildung sehen Sie die Schritte, die ein Nutzer ausführen muss, um sein Google-Konto mit Ihrem Authentifizierungssystem zu verknüpfen. Der erste Screenshot zeigt die vom Nutzer initiierte Verknüpfung über Ihre Plattform. Das zweite Bild zeigt die Nutzeranmeldung bei Google, das dritte die Einwilligung und Bestätigung des Nutzers für die Verknüpfung seines Google-Kontos mit Ihrer App. Der letzte Screenshot zeigt ein erfolgreich verknüpftes Nutzerkonto in der Google App.
Abbildung 1. Anmeldung des Nutzers bei Google und Einwilligungsbildschirme für die Kontoverknüpfung

Voraussetzungen

  1. Sie müssen dem Nutzer mitteilen, dass sein Konto mit Google verknüpft wird, nicht mit einem bestimmten Google-Produkt wie Google Home oder Google Assistant.

Empfehlungen

Wir empfehlen Folgendes:

  1. Datenschutzerklärung von Google anzeigen Fügen Sie auf dem Zustimmungsbildschirm einen Link zur Datenschutzerklärung von Google ein.

  2. Zu teilende Daten: Verwenden Sie eine klare und prägnante Sprache, um dem Nutzer mitzuteilen, welche seiner Daten Google benötigt und warum.

  3. Klarer Call-to-Action: Geben Sie auf dem Einwilligungsbildschirm einen klaren Call-to-Action an, z. B. „Zustimmen und verknüpfen“. Nutzer müssen wissen, welche Daten sie mit Google teilen müssen, um ihre Konten zu verknüpfen.

  4. Möglichkeit zur Kündigung Bieten Sie Nutzern die Möglichkeit, zurückzugehen oder abzubrechen, wenn sie die Verknüpfung nicht herstellen möchten.

  5. Übersichtlicher Anmeldevorgang: Sorgen Sie dafür, dass Nutzer sich auf einfache Weise in ihrem Google-Konto anmelden können, z. B. über Felder für ihren Nutzernamen und ihr Passwort oder über Über Google anmelden.

  6. Möglichkeit, die Verknüpfung aufzuheben: Bieten Sie Nutzern eine Möglichkeit, die Verknüpfung aufzuheben, z. B. über eine URL zu ihren Kontoeinstellungen auf Ihrer Plattform. Alternativ können Sie einen Link zu Google-Konto einfügen, über den Nutzer ihr verknüpftes Konto verwalten können.

  7. Nutzerkonto ändern: Schlagen Sie Nutzern eine Methode vor, mit der sie ihr(e) Konto(s) wechseln können. Das ist besonders dann von Vorteil, wenn Nutzer mehrere Konten haben.

    • Wenn ein Nutzer den Zustimmungsbildschirm schließen muss, um das Konto zu wechseln, senden Sie einen behebbaren Fehler an Google, damit sich der Nutzer mit OAuth-Verknüpfung und dem impliziten Ablauf im ausgewählten Konto anmelden kann.

  8. Fügen Sie Ihr Logo ein. Ihr Unternehmenslogo auf dem Zustimmungsbildschirm anzeigen Platzieren Sie Ihr Logo gemäß Ihren Style-Richtlinien. Wenn Sie das Google-Logo auch einblenden möchten oder müssen, lesen Sie den Abschnitt Logos und Marken.

Projekt erstellen

So erstellen Sie Ihr Projekt für die Kontoverknüpfung:

  1. Gehen Sie zur Google API Console.
  2. Klicken Sie auf Projekt erstellen.
  3. Geben Sie einen Namen ein oder übernehmen Sie den generierten Vorschlag.
  4. Bestätigen oder bearbeiten Sie die verbleibenden Felder.
  5. Klicken Sie auf Erstellen.

So rufen Sie Ihre Projekt-ID auf:

  1. Gehen Sie zur Google API Console.
  2. Suchen Sie in der Tabelle auf der Landingpage nach Ihrem Projekt. Die Projekt-ID wird in der Spalte ID angezeigt.

Der Prozess zur Verknüpfung von Google-Konten umfasst einen Zustimmungsbildschirm, auf dem Nutzer darüber informiert werden, welche Anwendung Zugriff auf ihre Daten anfordert, welche Art von Daten angefordert werden und welche Nutzungsbedingungen gelten. Sie müssen den OAuth-Zustimmungsbildschirm konfigurieren, bevor Sie eine Google API-Client-ID generieren.

  1. Öffnen Sie in der Google APIs Console die Seite OAuth-Zustimmungsbildschirm.
  2. Wählen Sie bei Aufforderung das Projekt aus, das Sie gerade erstellt haben.

  3. Füllen Sie auf der Seite „OAuth-Zustimmungsbildschirm“ das Formular aus und klicken Sie auf die Schaltfläche „Speichern“.

    Anwendungsname:Der Name der Anwendung, die um Einwilligung bittet. Der Name sollte Ihre Anwendung korrekt widerspiegeln und mit dem Anwendungsnamen übereinstimmen, den Nutzer an anderer Stelle sehen. Der Anwendungsname wird auf dem Zustimmungsbildschirm für die Kontoverknüpfung angezeigt.

    App-Logo:Ein Bild auf dem Zustimmungsbildschirm, das Nutzern hilft, Ihre App zu erkennen. Das Logo wird auf dem Zustimmungsbildschirm für die Kontoverknüpfung und in den Kontoeinstellungen angezeigt.

    Support-E-Mail-Adresse:Für Nutzer, die Sie wegen Fragen zu ihrer Einwilligung kontaktieren möchten.

    Bereiche für Google-APIs:Mit Bereichen kann Ihre Anwendung auf die privaten Google-Daten Ihrer Nutzer zugreifen. Für die Verknüpfung von Google-Konten reicht der Standardbereich („email“, „profile“, „openid“) aus. Sie müssen keine sensiblen Bereiche hinzufügen. Es empfiehlt sich, Bereiche inkrementell anzufordern, wenn der Zugriff erforderlich ist, und nicht im Voraus. Weitere Informationen

    Autorisierte Domains:Um Sie und Ihre Nutzer zu schützen, erlaubt Google die Nutzung autorisierter Domains nur Anwendungen, die sich mit OAuth authentifizieren. Die Links Ihrer Anwendungen müssen auf autorisierten Domains gehostet werden. Weitere Informationen

    Link zur Startseite der Anwendung:Startseite Ihrer Anwendung. Muss auf einer autorisierten Domain gehostet werden.

    Link zur Datenschutzerklärung der Anwendung:Wird auf dem Zustimmungsbildschirm für die Verknüpfung von Google-Konten angezeigt. Muss auf einer autorisierten Domain gehostet werden.

    Link zu den Nutzungsbedingungen der Anwendung (optional): Muss auf einer autorisierten Domain gehostet werden.

    Abbildung 1. Zustimmungsbildschirm für die Google-Kontoverknüpfung für die fiktive App „Tunery“

  4. Prüfen Sie den „Überprüfungsstatus“. Wenn Ihre Anwendung überprüft werden muss, klicken Sie auf die Schaltfläche „Zur Überprüfung einreichen“, um sie zur Überprüfung einzureichen. Weitere Informationen finden Sie unter Voraussetzungen für die OAuth-Überprüfung.

OAuth-Server implementieren

Implementierung validieren

Sie können Ihre Implementierung mit dem OAuth 2.0 Playground Tool validieren.

Führen Sie im Tool die folgenden Schritte aus:

  1. Klicken Sie auf die Konfigurationseinstellungen , um das Fenster „OAuth 2.0-Konfiguration“ zu öffnen.
  2. Wählen Sie im Feld OAuth-Ablauf die Option Clientseitig aus.
  3. Wählen Sie im Feld OAuth-Endpunkte die Option Benutzerdefiniert aus.
  4. Geben Sie in den entsprechenden Feldern Ihren OAuth 2.0-Endpunkt und die Client-ID an, die Sie Google zugewiesen haben.
  5. Wählen Sie im Abschnitt Schritt 1 keine Google-Bereiche aus. Lassen Sie dieses Feld stattdessen leer oder geben Sie einen für Ihren Server gültigen Bereich ein (oder eine beliebige Zeichenfolge, wenn Sie keine OAuth-Bereiche verwenden). Klicken Sie anschließend auf APIs autorisieren.
  6. Führen Sie in den Abschnitten Schritt 2 und Schritt 3 den OAuth 2.0-Ablauf durch und prüfen Sie, ob jeder Schritt wie vorgesehen funktioniert.

Sie können Ihre Implementierung mit dem Tool „Google-Kontoverknüpfung – Demo“ validieren.

Führen Sie im Tool die folgenden Schritte aus:

  1. Klicken Sie auf die Schaltfläche Mit Google anmelden.
  2. Wählen Sie das Konto aus, das Sie verknüpfen möchten.
  3. Geben Sie die Dienst-ID ein.
  4. Optional können Sie einen oder mehrere Bereiche eingeben, für die Sie Zugriff anfordern möchten.
  5. Klicken Sie auf Demo starten.
  6. Bestätigen Sie bei Aufforderung, dass Sie der Verknüpfungsanfrage zustimmen und sie ablehnen können.
  7. Bestätigen Sie, dass Sie zu Ihrer Plattform weitergeleitet werden.