OpenID Connect

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

Die OAuth 2.0-APIs von Google können sowohl für die Authentifizierung als auch für die Autorisierung verwendet werden. Dieses Dokument beschreibt unsere OAuth 2.0-Implementierung für die Authentifizierung, die der OpenID Connect- Spezifikation entspricht und OpenID Certified 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 Playground . Um Hilfe zu Stack Overflow zu erhalten, markieren Sie Ihre Fragen mit „google-oauth“.

OAuth 2.0 einrichten

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

Rufen Sie OAuth 2.0-Anmeldeinformationen ab

Sie benötigen OAuth 2.0-Anmeldeinformationen, einschließlich einer Client-ID und eines geheimen Clientschlüssels, 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 im API Console festlegen, bestimmt, wohin Google Antworten auf Ihre Authentifizierungsanfragen 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 Benutzerzustimmungsbildschirm an

Für Ihre Benutzer umfasst die OAuth 2.0-Authentifizierung einen Zustimmungsbildschirm, der die Informationen beschreibt, die der Benutzer freigibt, und die geltenden Bedingungen. Wenn sich der Benutzer beispielsweise anmeldet, wird er möglicherweise aufgefordert, Ihrer App Zugriff auf seine E-Mail-Adresse und grundlegende Kontoinformationen zu gewähren. Sie fordern den Zugriff auf diese Informationen mithilfe des scope an, den Ihre App in ihre Authentifizierungsanforderung einschließt . Sie können Bereiche auch verwenden, um Zugriff auf andere Google-APIs anzufordern.

Der Bildschirm zur Benutzereinwilligung enthält auch Markeninformationen wie Ihren Produktnamen, Ihr Logo und eine Homepage-URL. 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 .

Das folgende Zustimmungsdialogfeld zeigt, was ein Benutzer sehen würde, wenn eine Kombination aus OAuth 2.0- und Google Drive-Bereichen in der Anfrage vorhanden ist. (Dieses generische Dialogfeld wurde mithilfe von Google OAuth 2.0 Playground generiert, sodass es keine Branding-Informationen enthält, die im API Consolefestgelegt würden.)

Screenshot der Einwilligungsseite

Zugriff auf den Dienst

Google und Drittanbieter stellen Bibliotheken bereit, die Sie verwenden können, um sich um viele der Implementierungsdetails der Benutzerauthentifizierung und des Zugriffs auf Google-APIs zu kümmern. Beispiele sind Google Sign-In und die Google-Clientbibliotheken , 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-Anforderungsabläufe beschrieben werden, die den verfügbaren Bibliotheken zugrunde liegen.

Authentifizieren des Benutzers

Die Authentifizierung des Benutzers umfasst den Erhalt eines ID-Tokens und dessen Validierung. 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 Erhalten eines ID-Tokens werden als „Server“-Flow und „impliziter“ Flow bezeichnet. Der Serverfluss ermöglicht es dem Back-End-Server einer Anwendung, die Identität der Person zu überprüfen, die einen Browser oder ein mobiles Gerät verwendet. Der implizite Fluss 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.

Dieses Dokument beschreibt, wie der Server-Flow zur Authentifizierung des Benutzers ausgeführt wird. Der implizite Fluss ist aufgrund von Sicherheitsrisiken bei der Handhabung und Verwendung von Token auf der Client-Seite erheblich komplizierter. Wenn Sie einen impliziten Ablauf implementieren müssen, empfehlen wir dringend die Verwendung von Google Log-in .

Serverfluss

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

  1. Erstellen Sie ein fälschungssicheres Zustandstoken
  2. Senden Sie eine Authentifizierungsanfrage an Google
  3. Bestätigen Sie das Token für den Fälschungsschutz
  4. code für Zugriffstoken und ID-Token
  5. Rufen Sie Benutzerinformationen aus dem ID-Token ab
  6. Authentifizieren Sie den Benutzer

1. Erstellen Sie ein fälschungssicheres Zustandstoken

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 hält. Sie gleichen dieses eindeutige Sitzungstoken später mit der vom Google OAuth-Anmeldedienst zurückgegebenen Authentifizierungsantwort ab, um sicherzustellen, dass der Benutzer die Anfrage stellt und kein böswilliger Angreifer ist. Diese Token werden oft als CSRF -Token (Cross-Site Request Forgery) bezeichnet.

Eine gute Wahl für ein Zustandstoken ist eine Zeichenfolge von etwa 30 Zeichen, die mit einem hochwertigen Zufallszahlengenerator erstellt wird. Ein anderer ist ein Hash, der generiert wird, indem einige Ihrer Sitzungsstatusvariablen mit einem Schlüssel signiert werden, der auf Ihrem Back-End geheim gehalten wird.

Der folgende Code veranschaulicht 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 für Python herunterladen, um dieses Beispiel zu verwenden.

# 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 Authentifizierungsanfrage 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 aus dem Discovery-Dokument abrufen, indem Sie den Metadatenwert „ authorization_endpoint “ verwenden. Die folgende Diskussion geht davon aus, dass der Basis-URI https://accounts.google.com/o/oauth2/v2/auth lautet.

Geben Sie für eine einfache Anfrage die folgenden Parameter an:

  • client_id , die Sie aus dem API ConsoleCredentials pageerhalten.
  • response_type , was in einer einfachen Autorisierungscodeflussanforderung code sein sollte. (Lesen Sie mehr unter response_type .)
  • scope , der in einer einfachen Anfrage openid email sein sollte. (Lesen Sie mehr unter 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 in API ConsoleCredentials pagekonfiguriert haben. Wenn dieser Wert nicht mit einem autorisierten URI übereinstimmt, schlägt die Anforderung mit dem 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 Wiedergabeschutz aktiviert, sofern vorhanden.
  • login_hint kann die E-Mail-Adresse des Benutzers oder die sub sein, die der Google-ID des Benutzers entspricht. Wenn Sie keinen login_hint und der Benutzer derzeit angemeldet ist, enthält der Zustimmungsbildschirm eine Genehmigungsanfrage, um die E-Mail-Adresse des Benutzers für Ihre App freizugeben. (Lesen Sie mehr unter login_hint .)
  • Verwenden Sie den hd -Parameter, um den OpenID Connect-Fluss für Benutzer einer bestimmten G Suite-Domäne zu optimieren. (Lesen Sie mehr unter 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 erteilen, wenn Ihre App neue Informationen über sie anfordert oder wenn Ihre App Kontozugriff anfordert, den sie zuvor nicht genehmigt haben.

3. Bestätigen Sie das fälschungssichere Zustandstoken

Die Antwort wird an die von Ihnen in der Anfrage angegebene redirect_uri -URI gesendet. 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 erhaltene state mit dem Sitzungstoken übereinstimmt, das Sie in Schritt 1 erstellt haben. Diese Roundtrip-Überprüfung hilft sicherzustellen, dass der Benutzer und nicht ein bösartiges Skript die Anfrage 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 für Python herunterladen, um dieses Beispiel zu verwenden.

# 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. code für Zugangstoken und ID-Token

Die Antwort enthält einen code , einen einmaligen Autorisierungscode, den Ihr Server gegen ein Zugriffstoken und ein 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 abrufen sollten. Die folgende Diskussion geht davon aus, dass der Endpunkt https://oauth2.googleapis.com/token ist. Die Anforderung muss die folgenden Parameter im POST Body enthalten:

Felder
code Der Autorisierungscode, der von der ursprünglichen Anfrage zurückgegeben wird.
client_id Die Client-ID, die Sie von API ConsoleCredentials pageplaceholder140 abrufen, wie unter OAuth 2.0-Anmeldeinformationen abrufen beschrieben.
client_secret Der geheime Clientschlüssel, den Sie von API ConsoleCredentials pageplaceholder142 abrufen, wie unter OAuth 2.0-Anmeldeinformationen abrufen beschrieben.
redirect_uri Ein autorisierter Umleitungs-URI für die angegebene client_id , die in API ConsoleCredentials pageangegeben ist, wie unter Festlegen eines Umleitungs-URI beschrieben.
grant_type Dieses Feld muss einen Wert von authorization_code enthalten , wie in der OAuth 2.0 - Spezifikation definiert .

Die tatsächliche Anfrage könnte wie im folgenden Beispiel 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 Anfrage 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 Benutzer enthält, die von Google digital signiert sind.
scope Die vom access_token gewährten Zugriffsbereiche, ausgedrückt als Liste von durch Leerzeichen getrennten Zeichenfolgen mit Berücksichtigung der Groß- und Kleinschreibung.
token_type Identifiziert den Typ des zurückgegebenen Tokens. Dieses Feld hat zu diesem Zeitpunkt immer den Wert Bearer .
refresh_token (Optional)

Dieses Feld ist nur vorhanden, wenn der Parameter access_type in der Authentifizierungsanforderung auf offline gesetzt wurde. Einzelheiten finden Sie unter Aktualisierungstoken .

5. Rufen Sie Benutzerinformationen aus dem ID-Token ab

Ein ID-Token ist ein JWT (JSON Web Token), also ein kryptografisch signiertes Base64-codiertes JSON-Objekt. Normalerweise ist es wichtig, dass Sie ein ID-Token validieren , bevor Sie es verwenden, aber da Sie direkt mit Google über einen zwischengeschalteten HTTPS-Kanal kommunizieren und Ihr Client-Geheimnis verwenden, um sich bei Google zu authentifizieren, können Sie sicher sein, dass das Token Sie empfangen 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 Decodierung der base64url-codierten Werte und dem Parsen des darin enthaltenen JSON kombinieren, werden Sie das Token wahrscheinlich sowieso 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, formatiert für die Lesbarkeit:

{
  "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 (bekannt als Ansprüche ):

Beanspruchen Bereitgestellt Beschreibung
aud stets Die Zielgruppe, für die dieses ID-Token bestimmt ist. Es muss eine der OAuth 2.0-Client-IDs Ihrer Anwendung sein.
exp stets Ablaufzeit, an oder nach der der ID-Token nicht akzeptiert werden darf. Dargestellt in Unix-Zeit (ganzzahlige Sekunden).
iat stets Die Zeit, zu der das ID-Token ausgestellt wurde. Dargestellt in Unix-Zeit (ganzzahlige Sekunden).
iss stets Die Ausstellerkennung für den Aussteller der Antwort. Immer https://accounts.google.com oder accounts.google.com für Google-ID-Token.
sub stets Eine Kennung für den Nutzer, die unter allen Google-Konten eindeutig ist und nie wiederverwendet wird. Ein Google-Konto kann mehrere E-Mail-Adressen zu unterschiedlichen Zeitpunkten haben, aber der sub wird nie geändert. Verwenden Sie sub in Ihrer Anwendung als eindeutigen Identifikationsschlüssel für den Benutzer. Maximale Länge von 255 ASCII-Zeichen mit Berücksichtigung der Groß-/Kleinschreibung.
at_hash Zugriffstoken-Hash. Stellt eine Validierung bereit, dass das Zugriffstoken an das Identitätstoken gebunden ist. Wenn das ID-Token mit einem access_token -Wert im Serverfluss ausgegeben wird, ist dieser Anspruch immer enthalten. Dieser Anspruch kann als alternativer Mechanismus zum Schutz vor Cross-Site-Anforderungsfälschungsangriffen verwendet werden, aber wenn Sie Schritt 1 und Schritt 3 befolgen, 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 unterschiedliche OAuth 2.0 client_id haben, aber dasselbe Google-APIs-Projekt verwenden.
email Die E-Mail-Adresse des Benutzers. Dieser Wert ist möglicherweise nicht eindeutig für diesen Benutzer und eignet sich nicht zur Verwendung als Primärschlüssel. Wird nur bereitgestellt, wenn Ihr Bereich den email Bereichswert enthält.
email_verified True, wenn die E-Mail-Adresse des Benutzers verifiziert wurde; ansonsten falsch.
family_name Nachname(n) oder Nachname(n) des Benutzers. Kann bereitgestellt werden, wenn ein name vorliegt.
given_name Vorname(n) oder Vorname(n) des Benutzers. Kann bereitgestellt werden, wenn ein name vorliegt.
hd Die gehostete G Suite-Domäne des Benutzers. Wird nur bereitgestellt, wenn der Benutzer zu einer gehosteten Domäne gehört.
locale Das Gebietsschema des Benutzers, dargestellt durch ein BCP 47 -Sprachtag. Kann bereitgestellt werden, wenn ein name vorliegt.
name Der vollständige Name des Benutzers in anzeigbarer Form. Kann 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 sie verwenden, um die Benutzerdatensätze Ihrer App zu aktualisieren. Beachten Sie, dass das Vorhandensein dieses Anspruchs nie garantiert wird.

nonce Der Wert der von Ihrer App in der Authentifizierungsanforderung bereitgestellten nonce . Sie sollten den Schutz vor Replay-Angriffen erzwingen, indem Sie sicherstellen, dass er nur einmal präsentiert wird.
picture Die URL des Profilbilds des Benutzers. Kann bereitgestellt werden, wenn:
  • Der Anforderungsbereich enthielt die Zeichenfolge "Profil".
  • Das ID-Token wird von einer Token-Aktualisierung zurückgegeben

Wenn picture vorhanden sind, können Sie sie verwenden, um die Benutzerdatensätze Ihrer App zu aktualisieren. Beachten Sie, dass das Vorhandensein dieses Anspruchs nie garantiert wird.

profile Die URL der Profilseite des Benutzers. Kann 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 sie verwenden, um die Benutzerdatensätze Ihrer App zu aktualisieren. Beachten Sie, dass das Vorhandensein dieses Anspruchs nie garantiert wird.

6. Authentifizieren Sie den Benutzer

Nachdem Sie Benutzerinformationen aus dem ID-Token abgerufen 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 Registrierungsablauf für neue Benutzer umleiten. Möglicherweise können Sie den Benutzer basierend auf den Informationen, die Sie von Google erhalten, automatisch registrieren, oder Sie können 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 Benutzerprofil-Endpunkten 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 in Bezug auf Authentifizierung und Autorisierung.

Zugriff auf andere Google-APIs

Einer der Vorteile der Verwendung von OAuth 2.0 für die Authentifizierung besteht darin, dass Ihre Anwendung die Erlaubnis erhalten kann, andere Google-APIs im Namen des Benutzers zu verwenden (z. B. YouTube, Google Drive, Kalender oder Kontakte), während Sie den Benutzer authentifizieren. Schließen Sie dazu die anderen Bereiche, die Sie benötigen, in die Authentifizierungsanfrage 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 Zustimmungsbildschirm entsprechend aufgefordert. Das Zugriffstoken, das Sie von Google zurückerhalten, ermöglicht Ihnen den Zugriff auf alle APIs, die sich auf die von Ihnen angeforderten und gewährten Zugriffsbereiche beziehen.

Token aktualisieren

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

Überlegungen:

  • Achten Sie darauf, das Aktualisierungstoken sicher und dauerhaft zu speichern, da Sie ein Aktualisierungstoken nur erhalten können, wenn Sie den Codeaustauschfluss 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, stößt sie möglicherweise an diese Grenzwerte. In diesem Fall funktionieren ältere Aktualisierungstoken nicht mehr.

Weitere Informationen finden Sie unter Aktualisieren eines Zugriffstokens (Offlinezugriff) .

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

Weitere Informationen zum prompt finden Sie unter prompt in der Authentifizierungs-URI-Parametertabelle .

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 ConsoleCredentials pageplaceholder146 abrufen, wie unter OAuth 2.0-Anmeldeinformationen abrufen beschrieben.
nonce (Erforderlich) Ein von Ihrer App generierter Zufallswert, der den Wiedergabeschutz aktiviert.
response_type (Erforderlich) Wenn der Wert code ist, wird ein einfacher Autorisierungscodefluss gestartet , der einen POST an den Token-Endpunkt erfordert, um die Token zu erhalten. Wenn der Wert token id_token oder id_token token ist, wird ein impliziter Fluss gestartet, der die Verwendung von JavaScript am Umleitungs-URI erfordert, um Token aus dem URI #fragment identifier abzurufen .
redirect_uri (Erforderlich) Bestimmt, wohin die Antwort gesendet wird. Der Wert dieses Parameters muss genau mit einem der autorisierten Umleitungswerte übereinstimmen, die Sie in API ConsoleCredentials page festlegen (einschließlich HTTP- oder HTTPS-Schema, Groß-/Kleinschreibung und nachgestelltem „/“, falls vorhanden).
scope (Erforderlich)

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

Wenn der profile vorhanden ist, kann das ID-Token (aber nicht garantiert) die Standardprofilansprüche des profile enthalten.

Wenn der email Bereichswert vorhanden ist, enthält das ID-Token die Ansprüche „ email “ und email_verified .

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

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

state (Optional, aber dringend empfohlen)

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

Der state kann nützlich sein, um Anfragen und Antworten zu korrelieren. Da Ihre redirect_uri -URI erraten werden kann, kann die Verwendung eines state Ihre Gewissheit erhöhen, dass eine eingehende Verbindung das Ergebnis einer von Ihrer App initiierten Authentifizierungsanforderung ist. Wenn Sie eine zufällige Zeichenfolge generieren oder den Hash eines Clientstatus (z. B. eines Cookies) in diese Statusvariable codieren state können Sie die Antwort validieren, um zusätzlich sicherzustellen, dass Anfrage und Antwort vom selben Browser stammen. Dies bietet Schutz vor Angriffen wie Cross-Site-Request-Fälschung.

access_type (Optional) Die zulässigen Werte sind offline und online . Der Effekt ist in Offline Access 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 Angeben, wie der Autorisierungsserver die Benutzeroberflächenseiten für Authentifizierung und Zustimmung anzeigt. Die folgenden Werte werden von den Google-Servern angegeben und akzeptiert, haben jedoch keine Auswirkung auf ihr Verhalten: page , popup , touch und wap .
hd (Optional)

Der Parameter hd (hosted domain) optimiert den Anmeldeprozess für von G Suite gehostete Konten. Indem Sie die Domäne des G Suite-Benutzers (z. B. mycollege.edu ) einbeziehen, können Sie angeben, dass die Benutzeroberfläche zur Kontoauswahl für Konten in dieser Domäne optimiert werden soll. Um generell für G Suite-Konten statt nur für eine Domäne zu optimieren, legen Sie den Wert eines Sternchens ( * ) fest: 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. Vergewissern Sie sich, dass das zurückgegebene ID-Token einen hd -Anspruchswert hat, der hd Erwartungen entspricht (z. B. mycolledge.edu ). Im Gegensatz zum Anforderungsparameter ist der hd Anspruch des ID-Tokens in einem Sicherheitstoken von Google enthalten, sodass dem Wert vertraut werden kann.

include_granted_scopes (Optional) Wenn dieser Parameter mit dem Wert true bereitgestellt wird und die Autorisierungsanforderung gewährt wird, umfasst die Autorisierung alle früheren Autorisierungen, die dieser Benutzer-/Anwendungskombination für andere Geltungsbereiche erteilt wurden; siehe Inkrementelle Autorisierung .

Beachten Sie, dass Sie mit dem Flow „Installierte 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. Das Übergeben dieses Hinweises unterdrückt die Kontoauswahl und füllt entweder das E-Mail-Feld auf dem Anmeldeformular vorab aus oder wählt die richtige Sitzung aus (wenn der Benutzer die Mehrfachanmeldung 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 die sub Zeichenfolge sein, die der Google-ID des Benutzers entspricht.
prompt (Optional) Eine durch Leerzeichen getrennte Liste von Zeichenfolgewerten, 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 nicht bereits authentifiziert ist und keine vorkonfigurierte Zustimmung für die angeforderten Bereiche hat. Sie können none verwenden, 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ücksendet.

  • select_account

    Der Autorisierungsserver fordert den Benutzer auf, ein Benutzerkonto auszuwählen. Dies ermöglicht einem Benutzer, der mehrere Konten auf dem Autorisierungsserver hat, unter den mehreren Konten auszuwählen, für die er möglicherweise aktuelle Sitzungen hat.

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

Validierung eines ID-Tokens

Sie müssen alle ID-Token auf Ihrem Server validieren, 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 verifizieren.

Im Folgenden finden Sie häufige Situationen, in denen Sie möglicherweise ID-Token an Ihren Server senden:

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

ID-Token sind sensibel und können missbraucht werden, wenn sie abgefangen werden. Sie müssen sicherstellen, dass diese Token sicher gehandhabt 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. Aber bevor Sie die Informationen im ID-Token verwenden oder sich darauf verlassen können, dass sich der Benutzer 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 unter dem URI gefunden werden, der im jwks_uri Metadatenwert des Discovery-Dokuments angegeben ist.
  2. Stellen Sie sicher, dass der Wert des Anspruchs iss im ID-Token gleich https://accounts.google.com oder accounts.google.com ist.
  3. Stellen Sie sicher, dass der Wert des aud -Anspruchs im ID-Token gleich der Client-ID Ihrer App ist.
  4. Stellen Sie sicher, dass die Ablaufzeit ( exp Anspruch) des ID-Tokens nicht abgelaufen ist.
  5. Wenn Sie in der Anfrage einen hd-Parameterwert angegeben haben, überprüfen Sie, ob das ID-Token einen hd -Anspruch hat, der mit einer akzeptierten, von G Suite gehosteten Domäne übereinstimmt.

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

Der erste Schritt ist komplexer und beinhaltet die Prüfung kryptografischer Signaturen. Zu Debugging -Zwecken können Sie den tokeninfo -Endpunkt von Google verwenden, um ihn mit der lokalen Verarbeitung zu vergleichen, die auf Ihrem Server oder Gerät implementiert ist. 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 Token-Signatur gültig ist, wäre die Antwort die JWT-Nutzlast in ihrer decodierten JSON-Objektform.

Der tokeninfo Endpunkt ist nützlich für das Debugging, aber für Produktionszwecke sollten Sie die öffentlichen Schlüssel von Google vom Schlüsselendpunkt abrufen und die Validierung lokal durchführen. Sie sollten den Schlüssel-URI aus dem Discovery-Dokument abrufen, indem Sie den Metadatenwert jwks_uri verwenden. Anforderungen an den Debugging-Endpunkt können gedrosselt werden oder anderweitig zeitweiligen Fehlern unterliegen.

Da Google seine öffentlichen Schlüssel nur selten ändert, können Sie sie mit den Cache-Anweisungen der HTTP-Antwort zwischenspeichern und in den allermeisten Fällen eine lokale Validierung viel effizienter durchführen als mit dem tokeninfo Endpunkt. Diese Validierung erfordert das Abrufen und Analysieren von Zertifikaten und das Durchführen der entsprechenden kryptografischen Aufrufe zum Überprüfen der Signatur. Glücklicherweise gibt es gut debuggte Bibliotheken in einer Vielzahl von Sprachen, um dies zu erreichen (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 Authentifizierungsablaufs erhält) und den OpenID Connect -Standard verwenden:

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

    Wenn Sie möchten, dass die E-Mail-Adresse des Benutzers eingeschlossen wird, können Sie einen zusätzlichen Bereichswert von email angeben. Um sowohl profile als auch email 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 stellen Sie eine HTTPS- GET -Anforderung an den userinfo-Endpunkt, den Sie mithilfe des Metadatenwerts userinfo_endpoint aus dem Discovery-Dokument abrufen sollten. Die userinfo-Antwort enthält Informationen über den 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 zum Authentifizieren von Benutzern und zum Anfordern von Ressourcen, einschließlich Token, Benutzerinformationen und öffentlichen Schlüsseln.

Um Implementierungen zu vereinfachen und die Flexibilität zu erhöhen, ermöglicht OpenID Connect die Verwendung eines „Erkennungsdokuments“, eines JSON-Dokuments, das an einem bekannten Ort gefunden wird und 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-Key-Endpunkte. Das Discovery-Dokument für den OpenID Connect-Dienst von Google kann abgerufen werden unter:

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

Um die OpenID Connect-Dienste von Google zu verwenden, sollten Sie den Discovery-Dokument-URI ( 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 dann bei Bedarf Endpunkt-URIs daraus ab. Um beispielsweise einen Benutzer zu authentifizieren, würde Ihr Code den Metadatenwert „ authorization_endpoint “ ( https://accounts.google.com/o/oauth2/v2/auth im Beispiel unten) als Basis-URI für Authentifizierungsanforderungen abrufen, an die gesendet wird Google.

Hier ist ein Beispiel für ein solches Dokument; die Feldnamen sind diejenigen, die in OpenID Connect Discovery 1.0 angegeben sind (ihre Bedeutung finden Sie in diesem Dokument). Die Werte dienen lediglich der Veranschaulichung und können sich ändern, obwohl sie aus einer neueren Version des eigentlichen 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 respektiert 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 Request Object ).