Google setzt sich dafür ein, die Rassengerechtigkeit für schwarze Gemeinschaften zu fördern. Siehe wie.
Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

OpenID Connect

Der OpenID Connect-Endpunkt von Google ist OpenID-zertifiziert.

Die OAuth 2.0-APIs von Google können sowohl zur Authentifizierung als auch zur Autorisierung verwendet werden. Dieses Dokument beschreibt unsere OAuth 2.0-Implementierung für die Authentifizierung, die der OpenID Connect- Spezifikation entspricht und OpenID-zertifiziert ist . Die Dokumentation unter Verwenden von OAuth 2.0 für den Zugriff auf Google-APIs gilt auch für diesen Dienst. Wenn Sie dieses Protokoll interaktiv erkunden möchten, empfehlen wir den Google OAuth 2.0-Spielplatz . Um Hilfe zu erhalten auf Stack - Überlauf , markieren Sie Ihre Fragen mit ‚google-oauth‘.

Einrichten von OAuth 2.0

Bevor Ihre Anwendung das OAuth 2.0-Authentifizierungssystem von Google für die Benutzeranmeldung verwenden kann, müssen Sie im Google API Console ein Projekt einrichten, um OAuth 2.0-Anmeldeinformationen abzurufen, einen Umleitungs-URI festzulegen und (optional) die Branding-Informationen anzupassen, die Ihre Benutzer auf dem Benutzer sehen. Zustimmungsbildschirm. Sie können auch API Console verwenden, um ein Dienstkonto zu erstellen, die Abrechnung zu aktivieren, die Filterung einzurichten und andere Aufgaben auszuführen. Weitere Informationen finden Sie in der Google API Console-Hilfe .

Erhalten Sie OAuth 2.0-Anmeldeinformationen

Sie benötigen OAuth 2.0-Anmeldeinformationen, einschließlich einer Client-ID und eines Client-Geheimnisses, um Benutzer zu authentifizieren und Zugriff auf die APIs von Google zu erhalten.

Klicken Sie auf den folgenden Text, um die Client-ID und das Client-Geheimnis für einen bestimmten OAuth 2.0-Berechtigungsnachweis anzuzeigen: Wählen Sie den Berechtigungsnachweis aus . Wählen Sie im folgenden Fenster Ihr Projekt und die gewünschten Anmeldeinformationen aus und klicken Sie dann auf Anzeigen .

Oder zeigen Sie Ihre Client-ID und Ihr Client-Geheimnis auf der Seite Anmeldeinformationen in API Console :

  1. Go to the Credentials page.
  2. Klicken Sie auf den Namen Ihres Berechtigungsnachweises oder auf das Stiftsymbol ( ). Ihre Kunden-ID und Ihr Geheimnis befinden sich oben auf der Seite.

Legen Sie einen Umleitungs-URI fest

Der Umleitungs-URI, den Sie in API Console festgelegt haben, bestimmt, wohin Google Antworten auf Ihre Authentifizierungsanforderungen sendet.

Gehen Sie wie folgt vor, um die Umleitungs-URIs für einen bestimmten OAuth 2.0-Berechtigungsnachweis zu erstellen, anzuzeigen oder zu bearbeiten:

  1. Go to the Credentials page.
  2. Klicken Sie im Abschnitt OAuth 2.0-Client-IDs der Seite auf einen Berechtigungsnachweis.
  3. Anzeigen oder Bearbeiten der Umleitungs-URIs.

Wenn auf der Seite Anmeldeinformationen kein Abschnitt zu OAuth 2.0-Client-IDs vorhanden ist, verfügt Ihr Projekt über keine OAuth-Anmeldeinformationen. Um einen zu erstellen, klicken Sie auf Anmeldeinformationen erstellen .

Passen Sie den Bildschirm für die Einwilligung des Benutzers an

Für Ihre Benutzer umfasst die OAuth 2.0-Authentifizierungserfahrung einen Zustimmungsbildschirm, in dem die vom Benutzer freigegebenen Informationen und die geltenden Bedingungen beschrieben werden. Wenn sich der Benutzer beispielsweise anmeldet, wird er möglicherweise aufgefordert, Ihrer App Zugriff auf seine E-Mail-Adresse und die grundlegenden Kontoinformationen zu gewähren. Sie fordern den Zugriff auf diese Informationen mithilfe des scope , den Ihre App in ihre Authentifizierungsanforderung einbezieht . Sie können auch Bereiche verwenden, um den Zugriff auf andere Google-APIs anzufordern.

Auf dem Bildschirm mit der Einwilligung des Benutzers werden auch Markeninformationen wie Ihr Produktname, Ihr Logo und eine Homepage-URL angezeigt. Sie steuern die Branding-Informationen im API Console.

So aktivieren Sie den Zustimmungsbildschirm Ihres Projekts:

  1. Öffnen Sie das Consent Screen page im Google API Console .
  2. If prompted, select a project, or create a new one.
  3. Füllen Sie das Formular aus und klicken Sie auf Speichern .

Der folgende Zustimmungsdialog zeigt, was ein Benutzer sehen würde, wenn eine Kombination aus OAuth 2.0- und Google Drive-Bereichen in der Anforderung vorhanden ist. (Dieser generische Dialog wurde mit dem Google OAuth 2.0-Spielplatz erstellt , enthält also keine Markeninformationen, die im API Console festgelegt würden.)

Screenshot der Zustimmungsseite

Zugriff auf den Dienst

Google und Dritte stellen Bibliotheken zur Verfügung, mit denen Sie viele Implementierungsdetails für die Authentifizierung von Benutzern und den Zugriff auf Google-APIs verwalten können. Beispiele hierfür sind Google Sign-In und die Google Client-Bibliotheken , die für eine Vielzahl von Plattformen verfügbar sind.

Wenn Sie keine Bibliothek verwenden möchten, befolgen Sie die Anweisungen im Rest dieses Dokuments, in dem die HTTP-Anforderungsflüsse beschrieben werden, die den verfügbaren Bibliotheken zugrunde liegen.

Authentifizierung des Benutzers

Zur Authentifizierung des Benutzers muss ein ID-Token abgerufen und validiert werden. ID-Token sind eine standardisierte Funktion von OpenID Connect, die für die gemeinsame Nutzung von Identitätszusicherungen im Internet entwickelt wurde.

Die am häufigsten verwendeten Ansätze zum Authentifizieren eines Benutzers und zum Abrufen eines ID-Tokens werden als "Server" -Fluss und "impliziter" Fluss bezeichnet. Der Serverfluss ermöglicht es dem Back-End-Server einer Anwendung, die Identität der Person mithilfe eines Browsers oder Mobilgeräts zu überprüfen. Der implizite Ablauf wird verwendet, wenn eine clientseitige Anwendung (normalerweise eine im Browser ausgeführte JavaScript-App) direkt auf APIs zugreifen muss, anstatt über ihren Back-End-Server.

In diesem Dokument wird beschrieben, wie der Serverfluss zur Authentifizierung des Benutzers ausgeführt wird. Der implizite Ablauf ist aufgrund von Sicherheitsrisiken bei der Handhabung und Verwendung von Token auf der Clientseite erheblich komplizierter. Wenn Sie einen impliziten Ablauf implementieren müssen, empfehlen wir dringend die Verwendung von Google Sign-In .

Serverfluss

Stellen Sie sicher, dass Sie Ihre App im API Console eingerichtet haben , damit sie diese Protokolle verwenden und Ihre Benutzer authentifizieren kann. Wenn ein Nutzer versucht, sich bei Google anzumelden, müssen Sie:

  1. Erstellen Sie ein Fälschungsschutz-Status-Token
  2. Senden Sie eine Authentifizierungsanfrage an Google
  3. Bestätigen Sie das Anti-Fälschungs-Status-Token
  4. Exchange - Code für Zugriffstoken und ID - Token
  5. Beziehen Sie Benutzerinformationen vom ID-Token
  6. Authentifizieren Sie den Benutzer

1. Erstellen Sie ein Anti-Fälschungs-Status-Token

Sie müssen die Sicherheit Ihrer Benutzer schützen, indem Sie Anforderungsfälschungsangriffe verhindern. Der erste Schritt besteht darin, ein eindeutiges Sitzungstoken zu erstellen, das den Status zwischen Ihrer App und dem Client des Benutzers enthält. Sie ordnen dieses eindeutige Sitzungstoken später der vom Google OAuth-Anmeldedienst zurückgegebenen Authentifizierungsantwort zu, um zu überprüfen, ob der Benutzer die Anforderung stellt und kein böswilliger Angreifer. Diese Token werden häufig als CSRF- Token (Cross-Site Request Forgery) bezeichnet.

Eine gute Wahl für ein Status-Token ist eine Zeichenfolge mit etwa 30 Zeichen, die mit einem hochwertigen Zufallszahlengenerator erstellt wurde. Ein anderer ist ein Hash, der durch Signieren einiger Sitzungsstatusvariablen mit einem Schlüssel generiert wird, der in Ihrem Back-End geheim gehalten wird.

Der folgende Code demonstriert das Generieren eindeutiger Sitzungstoken.

PHP

Sie müssen die Google APIs-Clientbibliothek für PHP herunterladen, um dieses Beispiel verwenden zu können.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Sie müssen die Google APIs-Clientbibliothek für Java herunterladen, um dieses Beispiel verwenden zu können.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Sie müssen die Google APIs-Clientbibliothek herunterladen, damit Python dieses Beispiel verwenden kann.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Senden Sie eine Authentifizierungsanforderung an Google

Der nächste Schritt besteht darin, eine HTTPS- GET Anforderung mit den entsprechenden URI-Parametern zu erstellen. Beachten Sie die Verwendung von HTTPS anstelle von HTTP in allen Schritten dieses Prozesses. HTTP-Verbindungen werden abgelehnt. Sie sollten den Basis-URI mithilfe des Metadatenwerts authorization_endpoint aus dem Discovery-Dokument abrufen. In der folgenden Diskussion wird davon ausgegangen, dass der Basis-URI https://accounts.google.com/o/oauth2/v2/auth lautet.

Geben Sie für eine grundlegende Anforderung die folgenden Parameter an:

  • client_id , die Sie von API Console Credentials page erhalten.
  • response_type , die in einem Basisberechtigungscode Ablaufanforderung sollte code . (Lesen Sie mehr unter response_type .)
  • scope , der in einer grundlegenden Anfrage openid email . (Lesen Sie mehr im scope .)
  • redirect_uri sollte der HTTP-Endpunkt auf Ihrem Server sein, der die Antwort von Google erhält. Der Wert muss genau mit einem der autorisierten Umleitungs-URIs für den OAuth 2.0-Client übereinstimmen, den Sie im API Console Credentials page konfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anforderung mit einem Fehler redirect_uri_mismatch fehl.
  • state sollte den Wert des eindeutigen Anti-Fälschungs-Sitzungstokens sowie alle anderen Informationen enthalten, die zum Wiederherstellen des Kontexts erforderlich sind, wenn der Benutzer zu Ihrer Anwendung zurückkehrt, z. B. die Start-URL. (Lesen Sie mehr unter state .)
  • nonce ist ein zufälliger Wert, der von Ihrer App generiert wird und den Wiederholungsschutz aktiviert, wenn er vorhanden ist.
  • login_hint kann die E-Mail-Adresse des Benutzers oder die sub , die der Google-ID des Benutzers entspricht. Wenn Sie keinen login_hint und der Benutzer derzeit angemeldet ist, enthält der Zustimmungsbildschirm eine Aufforderung zur Genehmigung, die E-Mail-Adresse des Benutzers für Ihre App freizugeben. (Lesen Sie mehr unter login_hint .)
  • Verwenden Sie den Parameter hd , um den OpenID Connect-Ablauf für Benutzer einer bestimmten G Suite-Domäne zu optimieren. (Lesen Sie mehr bei hd .)

Hier ist ein Beispiel für einen vollständigen OpenID Connect-Authentifizierungs-URI mit Zeilenumbrüchen und Leerzeichen zur besseren Lesbarkeit:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

Benutzer müssen ihre Zustimmung geben, wenn Ihre App neue Informationen über sie anfordert oder wenn Ihre App einen Kontozugriff anfordert, den sie zuvor nicht genehmigt haben.

3. Bestätigen Sie den Anti-Fälschungs-Status-Token

Die Antwort wird an die redirect_uri gesendet, die Sie in der Anforderung angegeben haben . Alle Antworten werden in der Abfragezeichenfolge zurückgegeben, wie unten gezeigt:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

Auf dem Server müssen Sie bestätigen, dass der von Google empfangene state mit dem in Schritt 1 erstellten Sitzungstoken übereinstimmt. Diese Roundtrip-Überprüfung stellt sicher, dass der Benutzer, kein bösartiges Skript, die Anforderung stellt.

Der folgende Code zeigt die Bestätigung der Sitzungstoken, die Sie in Schritt 1 erstellt haben:

PHP

Sie müssen die Google APIs-Clientbibliothek für PHP herunterladen, um dieses Beispiel verwenden zu können.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Sie müssen die Google APIs-Clientbibliothek für Java herunterladen, um dieses Beispiel verwenden zu können.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Sie müssen die Google APIs-Clientbibliothek herunterladen, damit Python dieses Beispiel verwenden kann.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Tauschen Sie den code für das Zugriffstoken und das ID-Token aus

Die Antwort enthält einen code - Parameter, einen einmaligen Berechtigungscode , dass der Server für einen Zugriffstoken und ID - Token austauschen kann. Ihr Server führt diesen Austausch durch, indem er eine HTTPS- POST Anforderung sendet. Die POST Anforderung wird an den Token-Endpunkt gesendet, den Sie mithilfe des Metadatenwerts token_endpoint aus dem Discovery-Dokument token_endpoint . In der folgenden Diskussion wird davon ausgegangen, dass der Endpunkt https://oauth2.googleapis.com/token . Die Anforderung muss die folgenden Parameter im POST Text enthalten:

Felder
code Der Autorisierungscode, der von der ersten Anforderung zurückgegeben wird .
client_id Die Client-ID, die Sie von API Console Credentials page erhalten, wie unter Abrufen von OAuth 2.0-Anmeldeinformationen beschrieben .
client_secret Das Client-Geheimnis, das Sie von API Console Credentials page erhalten, wie unter Abrufen von OAuth 2.0-Anmeldeinformationen beschrieben .
redirect_uri Eine autorisierte Umleitungs-URI für die angegebene client_id die in API Console Credentials page angegeben ist, wie unter Festlegen einer Umleitungs-URI beschrieben .
grant_type Dieses Feld muss den Wert authorization_code , wie in der OAuth 2.0-Spezifikation definiert .

Die eigentliche Anfrage könnte wie folgt aussehen:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Eine erfolgreiche Antwort auf diese Anforderung enthält die folgenden Felder in einem JSON-Array:

Felder
access_token Ein Token, das an eine Google-API gesendet werden kann.
expires_in Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.
id_token Ein JWT , das Identitätsinformationen über den von Google digital signierten Nutzer enthält.
scope Die vom access_token gewährten access_token als Liste von durch Leerzeichen getrennten access_token ausgedrückt, bei denen zwischen Groß- und Kleinschreibung unterschieden wird.
token_type Gibt den Typ des zurückgegebenen Tokens an. Zu diesem Zeitpunkt hat dieses Feld immer den Wert Bearer .
refresh_token (Optional)

Dieses Feld ist nur vorhanden, wenn der Parameter access_type in der Authentifizierungsanforderung auf offline wurde. Weitere Informationen finden Sie unter Aktualisieren von Token .

5. Rufen Sie Benutzerinformationen vom ID-Token ab

Ein ID-Token ist ein JWT (JSON Web Token), dh ein kryptografisch signiertes Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, dass Sie ein ID-Token validieren, bevor Sie es verwenden. Da Sie jedoch über einen vermittelnden HTTPS-Kanal direkt mit Google kommunizieren und Ihr Kundengeheimnis verwenden, um sich bei Google zu authentifizieren, können Sie sicher sein, dass Sie das Token verwenden erhalten kommt wirklich von Google und ist gültig. Wenn Ihr Server das ID-Token an andere Komponenten Ihrer App weitergibt, ist es äußerst wichtig, dass die anderen Komponenten das Token validieren, bevor Sie es verwenden.

Da die meisten API-Bibliotheken die Validierung mit der Dekodierung der base64url-codierten Werte und der Analyse des darin enthaltenen JSON kombinieren, werden Sie das Token wahrscheinlich trotzdem validieren, wenn Sie auf die Ansprüche im ID-Token zugreifen.

Die Nutzlast eines ID-Tokens

Ein ID-Token ist ein JSON-Objekt, das eine Reihe von Name / Wert-Paaren enthält. Hier ist ein Beispiel, das aus Gründen der Lesbarkeit formatiert wurde:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Google ID-Token können die folgenden Felder enthalten (sogenannte Ansprüche ):

Anspruch Unter der Voraussetzung Beschreibung
aud immer Die Zielgruppe, für die dieses ID-Token bestimmt ist. Es muss eine der OAuth 2.0-Client-IDs Ihrer Anwendung sein.
exp immer Ablaufzeit, ab der das ID-Token nicht mehr akzeptiert werden darf. Dargestellt in Unix-Zeit (ganzzahlige Sekunden).
iat immer Die Zeit, zu der das ID-Token ausgestellt wurde. Dargestellt in Unix-Zeit (ganzzahlige Sekunden).
iss immer Die Emittenten-ID für den Emittenten der Antwort. Immer https://accounts.google.com oder accounts.google.com für Google ID-Token.
sub immer Eine Kennung für den Nutzer, die unter allen Google-Konten eindeutig ist und nie wiederverwendet wird. Ein Google-Konto kann zu unterschiedlichen Zeitpunkten mehrere E-Mail-Adressen haben, der sub wird jedoch nie geändert. Verwenden Sie sub in Ihrer Anwendung als eindeutigen Identifizierungsschlüssel für den Benutzer. Maximale Länge von 255 ASCII-Zeichen, bei denen zwischen Groß- und Kleinschreibung unterschieden wird.
at_hash Zugriffstoken-Hash. Bietet eine Überprüfung, ob das Zugriffstoken an das Identitätstoken gebunden ist. Wenn das ID-Token im access_token mit einem Wert für access_token ausgegeben wird, ist dieser Anspruch immer enthalten. Diese Behauptung kann als alternativer Mechanismus zum Schutz vor standortübergreifenden Fälschungsangriffen verwendet werden. Wenn Sie jedoch Schritt 1 und Schritt 3 ausführen, ist es nicht erforderlich, das Zugriffstoken zu überprüfen.
azp Die client_id des autorisierten Präsentators. Dieser Anspruch wird nur benötigt, wenn die Partei, die das ID-Token anfordert, nicht mit der Zielgruppe des ID-Tokens identisch ist. Dies kann bei Google für Hybrid-Apps der Fall sein, bei denen eine Webanwendung und eine Android-App eine andere OAuth 2.0- client_id jedoch dasselbe Google APIs-Projekt verwenden.
email Die E-Mail-Adresse des Benutzers. Dieser Wert ist für diesen Benutzer möglicherweise nicht eindeutig und nicht für die Verwendung als Primärschlüssel geeignet. Wird nur bereitgestellt, wenn Ihr Bereich den Wert für den email Bereich enthält.
email_verified True, wenn die E-Mail-Adresse des Benutzers überprüft wurde. sonst falsch.
family_name Nachname oder Nachname des Benutzers. Kann angegeben werden, wenn ein name vorliegt.
given_name Die Vornamen oder Vornamen des Benutzers. Kann angegeben werden, wenn ein name vorliegt.
hd Die gehostete G Suite-Domäne des Benutzers. Wird nur bereitgestellt, wenn der Benutzer einer gehosteten Domain angehört.
locale Das Gebietsschema des Benutzers, dargestellt durch ein BCP 47- Sprach-Tag. Kann angegeben werden, wenn ein name vorliegt.
name Der vollständige Name des Benutzers in anzeigbarer Form. Könnte bereitgestellt werden, wenn:
  • Der Anforderungsbereich enthielt die Zeichenfolge "Profil"
  • Das ID-Token wird von einer Token-Aktualisierung zurückgegeben

Wenn name vorhanden sind, können Sie diese verwenden, um die Benutzerdatensätze Ihrer App zu aktualisieren. Beachten Sie, dass diese Behauptung niemals garantiert vorhanden ist.

nonce Der Wert der von Ihrer App in der Authentifizierungsanforderung angegebenen nonce . Sie sollten den Schutz vor Wiederholungsangriffen erzwingen, indem Sie sicherstellen, dass er nur einmal angezeigt wird.
picture Die URL des Profilbilds des Benutzers. Könnte bereitgestellt werden, wenn:
  • Der Anforderungsbereich enthielt die Zeichenfolge "Profil"
  • Das ID-Token wird von einer Token-Aktualisierung zurückgegeben

Wenn picture Ansprüche vorhanden sind, können Sie sie benutzen , um Ihre App Benutzerdatensätze zu aktualisieren. Beachten Sie, dass diese Behauptung niemals garantiert vorhanden ist.

profile Die URL der Profilseite des Benutzers. Könnte bereitgestellt werden, wenn:
  • Der Anforderungsbereich enthielt die Zeichenfolge "Profil"
  • Das ID-Token wird von einer Token-Aktualisierung zurückgegeben

Wenn profile vorhanden sind, können Sie diese verwenden, um die Benutzerdatensätze Ihrer App zu aktualisieren. Beachten Sie, dass diese Behauptung niemals garantiert vorhanden ist.

6. Authentifizieren Sie den Benutzer

Nachdem Sie Benutzerinformationen vom ID-Token erhalten haben, sollten Sie die Benutzerdatenbank Ihrer App abfragen. Wenn der Benutzer bereits in Ihrer Datenbank vorhanden ist, sollten Sie eine Anwendungssitzung für diesen Benutzer starten, wenn alle Anmeldeanforderungen von der Google API-Antwort erfüllt werden.

Wenn der Benutzer nicht in Ihrer Benutzerdatenbank vorhanden ist, sollten Sie den Benutzer zu Ihrem Anmeldefluss für neue Benutzer umleiten. Möglicherweise können Sie den Nutzer anhand der von Google erhaltenen Informationen automatisch registrieren oder zumindest viele der Felder, die Sie in Ihrem Registrierungsformular benötigen, vorab ausfüllen. Zusätzlich zu den Informationen im ID-Token können Sie zusätzliche Benutzerprofilinformationen an unseren Benutzerprofilendpunkten abrufen.

Fortgeschrittene Themen

In den folgenden Abschnitten wird die Google OAuth 2.0-API ausführlicher beschrieben. Diese Informationen richten sich an Entwickler mit erweiterten Anforderungen an die Authentifizierung und Autorisierung.

Zugriff auf andere Google-APIs

Einer der Vorteile der Verwendung von OAuth 2.0 zur Authentifizierung besteht darin, dass Ihre Anwendung gleichzeitig mit der Authentifizierung des Benutzers die Berechtigung erhalten kann, andere Google-APIs im Namen des Nutzers (z. B. YouTube, Google Drive, Kalender oder Kontakte) zu verwenden. Fügen Sie dazu die anderen Bereiche, die Sie benötigen, in die Authentifizierungsanforderung ein , die Sie an Google senden. Um beispielsweise die Altersgruppe des Benutzers zu Ihrer Authentifizierungsanforderung hinzuzufügen, übergeben Sie einen Bereichsparameter von openid email https://www.googleapis.com/auth/profile.agerange.read . Der Benutzer wird auf dem Einwilligungsbildschirm entsprechend aufgefordert. Mit dem Zugriffstoken, das Sie von Google zurückerhalten, können Sie auf alle APIs zugreifen, die sich auf die von Ihnen angeforderten und gewährten Zugriffsbereiche beziehen.

Token aktualisieren

In Ihrer Anfrage nach API-Zugriff können Sie ein Aktualisierungstoken anfordern, das während des code Austauschs zurückgegeben wird . Ein Aktualisierungstoken ermöglicht Ihrer App den kontinuierlichen Zugriff auf Google APIs, während der Benutzer nicht in Ihrer Anwendung vorhanden ist. Um ein Aktualisierungstoken anzufordern, setzen Sie den Parameter access_type in Ihrer Authentifizierungsanforderung auf offline .

Überlegungen:

  • Stellen Sie sicher, dass das Aktualisierungstoken sicher und dauerhaft gespeichert ist, da Sie ein Aktualisierungstoken nur erhalten können, wenn Sie den Codeaustausch zum ersten Mal ausführen.
  • Die Anzahl der ausgegebenen Aktualisierungstoken ist begrenzt: ein Limit pro Client / Benutzer-Kombination und ein weiteres pro Benutzer für alle Clients. Wenn Ihre Anwendung zu viele Aktualisierungstoken anfordert, kann dies zu Einschränkungen führen. In diesem Fall funktionieren ältere Aktualisierungstoken nicht mehr.

Weitere Informationen finden Sie unter Aktualisieren eines Zugriffstokens (Offline-Zugriff) .

Sie können den Benutzer auffordern , auf Ihre App erneut autorisieren , indem Sie die Einstellung prompt Parameter auf consent in der Authentifizierungsanforderung . Wenn prompt=consent enthalten ist, wird der Zustimmungsbildschirm jedes Mal angezeigt, wenn Ihre App die Autorisierung von Zugriffsbereichen anfordert, auch wenn alle Bereiche zuvor Ihrem Google APIs-Projekt gewährt wurden. Geben Sie aus diesem Grund nur bei Bedarf prompt=consent an.

Weitere Informationen zum prompt finden Sie unter prompt in der Tabelle mit den Authentifizierungs-URI-Parametern .

Authentifizierungs-URI-Parameter

Die folgende Tabelle enthält ausführlichere Beschreibungen der Parameter, die von der OAuth 2.0-Authentifizierungs-API von Google akzeptiert werden.

Parameter Erforderlich Beschreibung
client_id (Erforderlich) Die Client-ID-Zeichenfolge, die Sie von API Console Credentials page erhalten, wie unter Abrufen von OAuth 2.0-Anmeldeinformationen beschrieben .
nonce (Erforderlich) Ein zufälliger Wert, der von Ihrer App generiert wird und den Wiederholungsschutz aktiviert.
response_type (Erforderlich) Wenn der Wert code , wird ein Code für den Basisautorisierungscode gestartet, für den ein POST zum Token-Endpunkt erforderlich ist, um die Token abzurufen. Wenn der Wert token id_token oder id_token token , wird ein impliziter Fluss id_token token , für den JavaScript am Umleitungs-URI verwendet werden muss, um Token aus der URI- #fragment .
redirect_uri (Erforderlich) Legt fest, wohin die Antwort gesendet wird. Der Wert dieses Parameters muss genau mit einem der autorisierten Umleitungswerte übereinstimmen, die Sie in API Console Credentials page festgelegt haben (einschließlich des HTTP- oder HTTPS-Schemas, der Groß- und Kleinschreibung und gegebenenfalls des nachfolgenden '/').
scope (Erforderlich)

Der Bereichsparameter muss mit dem Wert openid beginnen und dann den profile , den email Wert oder beides enthalten.

Wenn das profile Umfang Wert vorhanden ist, die ID - Token könnte (aber nicht garantiert) sind die profile Ansprüche.

Wenn der Wert für den email Bereich vorhanden ist, enthält das ID-Token email und email_verified Ansprüche.

Zusätzlich zu diesen OpenID-spezifischen Bereichen kann Ihr Bereichsargument auch andere Bereichswerte enthalten. Alle Bereichswerte müssen durch Leerzeichen getrennt sein. Wenn Sie beispielsweise per Datei auf das Google Drive eines Benutzers zugreifen openid profile email https://www.googleapis.com/auth/drive.file , openid profile email https://www.googleapis.com/auth/drive.file Ihr Bereichsparameter möglicherweise die openid profile email https://www.googleapis.com/auth/drive.file .

Informationen zu verfügbaren Bereichen finden Sie unter OAuth 2.0- Bereiche für Google-APIs oder in der Dokumentation zu der Google-API, die Sie verwenden möchten.

state (Optional, aber dringend empfohlen)

Eine undurchsichtige Zeichenfolge, die im Protokoll umgeleitet wird. Das heißt, es wird als URI-Parameter im #fragment und in der URI #fragment im impliziten Fluss zurückgegeben.

Der state kann nützlich sein, um Anforderungen und Antworten zu korrelieren. Weil Ihr redirect_uri erraten werden kann, einen mit state kann Wert erhöhen Ihre Sicherheit , dass eine eingehende Verbindung das Ergebnis einer Authentifizierungsanfrage von Ihrer App gestartet ist. Wenn Sie eine zufällige Zeichenfolge erzeugen oder codieren die Hash einiger Client - Zustand (zB ein Cookie) in diesem state Variable, können Sie die Antwort validieren , um zusätzlich sicherzustellen , dass die Anfrage und Antwort im gleichen Browser stammt. Dies bietet Schutz vor Angriffen wie z. B. Fälschung von standortübergreifenden Anforderungen.

access_type (Optional) Die zulässigen Werte sind offline und online . Der Effekt ist im Offline-Zugriff dokumentiert. Wenn ein Zugriffstoken angefordert wird, erhält der Client kein Aktualisierungstoken, es sei denn, der Wert offline ist angegeben.
display (Optional) Ein ASCII-Zeichenfolgenwert zum Festlegen, wie der Autorisierungsserver die Seiten der Authentifizierungs- und Zustimmungsbenutzeroberfläche anzeigt. Die folgenden Werte werden von den Google-Servern angegeben und akzeptiert, haben jedoch keine Auswirkungen auf das Verhalten: page , popup , touch und wap .
hd (Optional)

Der Parameter hd (gehostete Domäne) optimiert den Anmeldevorgang für gehostete G Suite-Konten. Durch Einbeziehen der Domäne des G Suite-Benutzers (z. B. mycollege.edu ) können Sie angeben, dass die Benutzeroberfläche für die Kontoauswahl für Konten in dieser Domäne optimiert werden soll. hd=* Wert eines Sterns ( * ) fest, um für G Suite-Konten im Allgemeinen anstelle nur einer Domäne zu optimieren: hd=* .

Verlassen Sie sich nicht auf diese UI-Optimierung, um zu steuern, wer auf Ihre App zugreifen kann, da clientseitige Anforderungen geändert werden können. Achten Sie darauf, Validieren , dass die zurück ID - hd mycolledge.edu Token einen hat hd Anspruch Wert, Streichhölzer , was Sie erwarten (zB mycolledge.edu ). Im Gegensatz zum Anforderungsparameter ist der ID-Token- hd Anspruch in einem Sicherheitstoken von Google enthalten, sodass dem Wert vertraut werden kann.

include_granted_scopes (Optional) Wenn dieser Parameter mit dem Wert true ist und die Autorisierungsanforderung erteilt wurde, enthält die Autorisierung alle vorherigen Autorisierungen, die dieser Benutzer- / Anwendungskombination für andere Bereiche erteilt wurden. Siehe Inkrementelle Autorisierung .

Beachten Sie, dass Sie mit dem Flow der installierten App keine inkrementelle Autorisierung durchführen können.

login_hint (Optional) Wenn Ihre App weiß, welchen Benutzer sie zu authentifizieren versucht, kann sie diesen Parameter als Hinweis für den Authentifizierungsserver bereitstellen. Durch das Übergeben dieses Hinweises wird die Kontoauswahl unterdrückt und entweder das E-Mail-Feld im Anmeldeformular vorab ausgefüllt oder die richtige Sitzung ausgewählt (wenn der Benutzer mehrere Anmeldungen verwendet ), wodurch Sie Probleme vermeiden können, die bei Ihrer App auftreten meldet sich im falschen Benutzerkonto an. Der Wert kann entweder eine E-Mail-Adresse oder eine sub , die der Google-ID des Benutzers entspricht.
prompt (Optional) Eine durch Leerzeichen getrennte Liste von Zeichenfolgenwerten, die angibt, ob der Autorisierungsserver den Benutzer zur erneuten Authentifizierung und Zustimmung auffordert. Die möglichen Werte sind:
  • none

    Der Autorisierungsserver zeigt keine Authentifizierungs- oder Benutzerzustimmungsbildschirme an. Es wird ein Fehler zurückgegeben, wenn der Benutzer noch nicht authentifiziert ist und keine vorkonfigurierte Einwilligung für die angeforderten Bereiche hat. Sie können none , um nach vorhandener Authentifizierung und / oder Zustimmung zu suchen.

  • consent

    Der Autorisierungsserver fordert den Benutzer zur Zustimmung auf, bevor er Informationen an den Client zurückgibt.

  • select_account

    Der Autorisierungsserver fordert den Benutzer auf, ein Benutzerkonto auszuwählen. Auf diese Weise kann ein Benutzer mit mehreren Konten auf dem Autorisierungsserver unter den mehreren Konten auswählen, für die er möglicherweise aktuelle Sitzungen hat.

Wenn kein Wert angegeben ist und der Benutzer zuvor keinen autorisierten Zugriff hat, wird dem Benutzer ein Zustimmungsbildschirm angezeigt.

Überprüfen eines ID-Tokens

Sie müssen alle ID-Token auf Ihrem Server überprüfen, es sei denn, Sie wissen, dass sie direkt von Google stammen. Beispielsweise muss Ihr Server alle ID-Token, die er von Ihren Client-Apps erhält, als authentisch überprüfen.

In den folgenden Situationen können Sie möglicherweise ID-Token an Ihren Server senden:

  • Senden von ID-Token mit Anforderungen, die authentifiziert werden müssen. Die ID-Token geben an, welcher Benutzer die Anforderung gestellt hat und für welchen Client dieses ID-Token gewährt wurde.

ID-Token sind empfindlich und können beim Abfangen missbraucht werden. Sie müssen sicherstellen, dass diese Token sicher behandelt werden, indem Sie sie nur über HTTPS und nur über POST-Daten oder innerhalb von Anforderungsheadern übertragen. Wenn Sie ID-Token auf Ihrem Server speichern, müssen Sie diese auch sicher speichern.

Eine Sache, die ID-Token nützlich macht, ist die Tatsache, dass Sie sie an verschiedene Komponenten Ihrer App weitergeben können. Diese Komponenten können ein ID-Token als einfachen Authentifizierungsmechanismus verwenden, der die App und den Benutzer authentifiziert. Bevor Sie jedoch die Informationen im ID-Token verwenden oder sich darauf verlassen können, dass der Benutzer sich authentifiziert hat, müssen Sie sie validieren.

Die Validierung eines ID-Tokens erfordert mehrere Schritte:

  1. Stellen Sie sicher, dass das ID-Token vom Aussteller ordnungsgemäß signiert ist. Von Google ausgestellte Token werden mit einem der Zertifikate signiert, die an der URI gefunden wurden, die im Metadatenwert jwks_uri des Discovery-Dokuments angegeben ist .
  2. Stellen Sie sicher, dass der Wert des iss Anspruchs im ID-Token gleich https://accounts.google.com oder accounts.google.com .
  3. Stellen Sie sicher, dass der Wert des aud Anspruchs im ID-Token der Client-ID Ihrer App entspricht.
  4. Stellen Sie sicher, dass die Ablaufzeit ( exp Claim) des ID-Tokens nicht abgelaufen ist.
  5. Wenn Sie in der Anforderung einen HD-Parameterwert angegeben haben, überprüfen Sie, ob das ID-Token einen hd Anspruch hat, der mit einer akzeptierten gehosteten G Suite-Domäne übereinstimmt.

Die Schritte 2 bis 5 beinhalten nur Zeichenfolgen- und Datumsvergleiche, die recht einfach sind, daher werden wir sie hier nicht detailliert beschreiben.

Der erste Schritt ist komplexer und umfasst die Überprüfung der kryptografischen Signatur. Für Debugging- Zwecke können Sie den tokeninfo Endpunkt von Google verwenden, um ihn mit der auf Ihrem Server oder Gerät implementierten lokalen Verarbeitung zu vergleichen. Angenommen, der Wert Ihres ID-Tokens ist XYZ123 . Dann würden Sie den URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 dereferenzieren. Wenn die Tokensignatur gültig ist, ist die Antwort die JWT-Nutzlast in ihrer dekodierten JSON-Objektform.

Der tokeninfo Endpunkt ist nützlich für das Debuggen, aber für Produktionszwecke tokeninfo die öffentlichen Schlüssel von Google vom Schlüsselendpunkt ab und führen Sie die Validierung lokal durch. Sie sollten den Schlüssel-URI mithilfe des Metadatenwerts jwks_uri aus dem Discovery-Dokument jwks_uri . Anforderungen an den Debugging-Endpunkt können gedrosselt werden oder auf andere Weise zeitweise fehlerhaft sein.

Da Google seine öffentlichen Schlüssel nur selten ändert, können Sie sie mithilfe der Cache-Anweisungen der HTTP-Antwort zwischenspeichern und in den allermeisten Fällen die lokale Validierung wesentlich effizienter durchführen als mithilfe des tokeninfo Endpunkts. Diese Validierung erfordert das Abrufen und Parsen von Zertifikaten sowie das Ausführen der entsprechenden kryptografischen Aufrufe zum Überprüfen der Signatur. Glücklicherweise gibt es dafür gut debuggte Bibliotheken in einer Vielzahl von Sprachen (siehe jwt.io ).

Abrufen von Benutzerprofilinformationen

Um zusätzliche Profilinformationen über den Benutzer zu erhalten, können Sie das Zugriffstoken (das Ihre Anwendung während des Authentifizierungsflusses erhält) und den OpenID Connect- Standard verwenden:

  1. Um OpenID-kompatibel zu sein, müssen Sie die Werte des openid profile in Ihre Authentifizierungsanforderung aufnehmen .

    Wenn Sie möchten, dass die E-Mail-Adresse des Benutzers angegeben wird, können Sie einen zusätzlichen Bereichswert für email angeben. Um sowohl das profile als auch die email Adresse anzugeben, können Sie den folgenden Parameter in Ihren Authentifizierungsanforderungs-URI aufnehmen:

    scope=openid%20profile%20email
  2. Fügen Sie Ihr Zugriffstoken zum Autorisierungsheader hinzu und senden Sie eine HTTPS- GET Anforderung an den Endpunkt userinfo, den Sie mithilfe des Metadatenwerts userinfo_endpoint aus dem Discovery-Dokument userinfo_endpoint . Die Benutzerinfo-Antwort enthält Informationen zum Benutzer, wie in OpenID Connect Standard Claims und dem Metadatenwert claims_supported des Discovery-Dokuments beschrieben. Benutzer oder ihre Organisationen können bestimmte Felder angeben oder zurückhalten, sodass Sie möglicherweise nicht für jedes Feld Informationen für Ihre autorisierten Zugriffsbereiche erhalten.

Das Discovery-Dokument

Das OpenID Connect-Protokoll erfordert die Verwendung mehrerer Endpunkte zur Authentifizierung von Benutzern und zum Anfordern von Ressourcen wie Token, Benutzerinformationen und öffentlichen Schlüsseln.

Um die Implementierung zu vereinfachen und die Flexibilität zu erhöhen, ermöglicht OpenID Connect die Verwendung eines "Discovery-Dokuments", eines JSON-Dokuments an einem bekannten Ort, das Schlüssel-Wert-Paare enthält, die Details zur Konfiguration des OpenID Connect-Anbieters enthalten, einschließlich der URIs der Autorisierung , Token-, Widerrufs-, Benutzerinfo- und Public-Keys-Endpunkte. Das Discovery-Dokument für den OpenID Connect-Dienst von Google kann abgerufen werden von:

https://accounts.google.com/.well-known/openid-configuration

Um die OpenID Connect-Dienste von Google nutzen zu können, müssen Sie den URI des Discovery-Dokuments ( https://accounts.google.com/.well-known/openid-configuration ) in Ihrer Anwendung fest codieren. Ihre Anwendung ruft das Dokument ab, wendet Caching-Regeln in der Antwort an und ruft bei Bedarf Endpunkt-URIs ab. Um beispielsweise einen Benutzer zu authentifizieren, ruft Ihr Code den Metadatenwert authorization_endpoint (im folgenden Beispiel https://accounts.google.com/o/oauth2/v2/auth ) als Basis-URI für Authentifizierungsanforderungen ab, an die gesendet wird Google.

Hier ist ein Beispiel für ein solches Dokument. Die Feldnamen sind die in OpenID Connect Discovery 1.0 angegebenen (ihre Bedeutung finden Sie in diesem Dokument). Die Werte dienen lediglich der Veranschaulichung und können sich ändern, obwohl sie aus einer aktuellen Version des aktuellen Google Discovery-Dokuments kopiert wurden:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Möglicherweise können Sie einen HTTP-Roundtrip vermeiden, indem Sie die Werte aus dem Discovery-Dokument zwischenspeichern. Standard-HTTP-Caching-Header werden verwendet und sollten beachtet werden.

Client-Bibliotheken

Die folgenden Client-Bibliotheken vereinfachen die Implementierung von OAuth 2.0 durch die Integration in gängige Frameworks:

OpenID Connect-Konformität

Das OAuth 2.0-Authentifizierungssystem von Google unterstützt die erforderlichen Funktionen der OpenID Connect Core- Spezifikation. Jeder Client, der für die Arbeit mit OpenID Connect ausgelegt ist, sollte mit diesem Dienst zusammenarbeiten (mit Ausnahme des OpenID-Anforderungsobjekts ).