Anmeldung auf Fernsehern und eingeschränkten Eingabegeräten

Sie können Nutzern erlauben, sich auf Geräten mit eingeschränkten Eingabefunktionen, z. B. auf Fernsehern mit Internetverbindung, mit ihren Google-Konten in Ihrer App anzumelden.

In der App werden dem Nutzer ein Kurzcode und eine Anmelde-URL angezeigt. Anschließend öffnet der Nutzer die Anmelde-URL in einem Webbrowser, gibt den Code ein und erteilt der App die Berechtigung, auf die Anmeldedaten des Nutzers zuzugreifen. Schließlich erhält die App eine Bestätigung und der Nutzer ist angemeldet.

Damit Sie diesen Anmeldevorgang verwenden können, muss die App auf einem Gerät ausgeführt werden, das die folgenden Kriterien erfüllt:

  • Das Gerät muss eine URL mit bis zu 40 Zeichen, einen 15-stelligen Nutzercode sowie eine Anleitung für den Nutzer anzeigen können.
  • Das Gerät muss mit dem Internet verbunden sein.

Client-ID und Clientschlüssel abrufen

Ihre Anwendung benötigt eine OAuth 2.0-Client-ID und einen Clientschlüssel, um Anfragen an die Anmeldeendpunkte von Google senden zu können.

So finden Sie die Client-ID und den Clientschlüssel Ihres Projekts:

  1. Wähle vorhandene OAuth 2.0-Anmeldedaten aus oder öffne die Seite „Anmeldedaten“.
  2. Falls noch nicht geschehen, erstellen Sie die OAuth 2.0-Anmeldedaten für Ihr Projekt. Klicken Sie dazu auf Anmeldedaten erstellen > OAuth-Client-ID und geben Sie die zum Erstellen der Anmeldedaten erforderlichen Informationen an.
  3. Suchen Sie im Abschnitt OAuth 2.0-Client-IDs nach der Client-ID. Klicken Sie auf die Client-ID, um weitere Informationen zu erhalten.

Wenn Sie eine neue Client-ID erstellen, wählen Sie den Anwendungstyp Fernseher und Geräte mit begrenzter Eingabe aus.

Nutzercode und Bestätigungs-URL abrufen

Wenn ein Nutzer die Anmeldung mit einem Google-Konto anfordert, erhalten Sie einen Nutzercode und eine Bestätigungs-URL. Dazu senden Sie eine HTTP-POST-Anfrage an den OAuth 2.0-Geräteendpunkt https://oauth2.googleapis.com/device/code. Geben Sie Ihre Client-ID und eine Liste der Bereiche an, die Sie für die Anfrage benötigen. Wenn Sie Nutzer nur mit ihren Google-Konten anmelden möchten, fordern Sie nur die Bereiche profile und email an. Wenn Sie die Berechtigung zum Aufrufen einer unterstützten API im Namen der Nutzer anfordern möchten, fordern Sie zusätzlich zu den Bereichen profile und email auch die erforderlichen Bereiche an.

Hier sehen Sie eine Beispielanforderung für einen Nutzercode:

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

client_id=YOUR_GOOGLE_CLIENT_ID&scope=email%20profile

mit curl:

curl -d "client_id=YOUR_GOOGLE_CLIENT_ID&scope=email profile" https://oauth2.googleapis.com/device/code

Die Antwort wird als JSON-Objekt zurückgegeben:

 {
  "device_code" : "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code" : "GQVQ-JKEC",
  "verification_url" : "https://www.google.com/device",
  "expires_in" : 1800,
  "interval" : 5
}

Ihre Anwendung zeigt dem Nutzer die Werte user_code und verification_url an und fragt gleichzeitig den Anmeldeendpunkt am angegebenen interval ab, bis sich der Nutzer entweder anmeldet oder die in expires_in angegebene Zeit verstrichen ist.

Nutzercode und Bestätigungs-URL anzeigen

Nachdem Sie einen Nutzercode und eine Bestätigungs-URL vom Geräteendpunkt erhalten haben, zeigen Sie diese an und weisen Sie den Nutzer an, die URL zu öffnen und den Nutzercode einzugeben.

Die Werte von verification_url und user_code können sich ändern. Entwerfen Sie Ihre UI so, dass die folgenden Limits verarbeitet werden können:

  • user_code muss in einem Feld angezeigt werden, das 15 Zeichen der Größe W verarbeiten kann.
  • verification_url muss in einem Feld angezeigt werden, das so breit ist, dass ein URL-String mit 40 Zeichen verarbeitet werden kann.

Beide Strings können beliebige druckbare Zeichen aus dem US-ASCII-Zeichensatz enthalten.

Ändern Sie den String user_code nicht, z. B. ändern Sie die Groß-/Kleinschreibung und fügen Sie keine anderen Formatierungszeichen ein, da Ihre Anwendung beschädigt werden kann, wenn sich das Format des Codes in Zukunft ändert.

Sie können den String verification_url ändern, indem Sie das Schema aus der URL für die Anzeige entfernen. Achten Sie in diesem Fall darauf, dass Ihre Anwendung sowohl die „http“- als auch die „https“-Varianten verarbeiten kann. Ansonsten ändern Sie den String verification_url nicht.

Wenn der Nutzer die Bestätigungs-URL aufruft, sieht er eine Seite ähnlich der folgenden:

Gerät durch Eingabe eines Codes verbinden

Nachdem der Nutzer den Nutzercode eingegeben hat, wird auf der Google Log-in-Website ein Zustimmungsbildschirm ähnlich dem folgenden angezeigt:

Beispiel für einen Zustimmungsbildschirm für einen Geräteclient

Wenn der Nutzer auf Zulassen klickt, kann die Anwendung ein ID-Token zur Identifizierung des Nutzers, ein Zugriffstoken zum Aufrufen von Google APIs und ein Aktualisierungstoken zum Abrufen neuer Token abrufen.

ID-Token und Aktualisierungstoken abrufen

Nachdem Ihre App den Nutzercode und die Bestätigungs-URL angezeigt hat, beginnen Sie mit dem Abfragen des Tokenendpunkts (https://oauth2.googleapis.com/token) mit dem Gerätecode, den Sie vom Geräteendpunkt erhalten haben. Fragen Sie den Tokenendpunkt in dem Intervall in Sekunden ab, das durch den Wert interval angegeben wird.

Hier ist eine Beispielanfrage:

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

client_id=YOUR_GOOGLE_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

mit curl:

curl -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0" https://oauth2.googleapis.com/token

Wenn der Nutzer die Anfrage noch nicht genehmigt hat, lautet die Antwort so:

{
  "error" : "authorization_pending"
}

Die Anwendung sollte diese Anfragen mit einer Rate wiederholen, die den Wert von interval nicht überschreitet. Wenn Ihre App zu schnell eine Abfrage durchführt, lautet die Antwort:

{
  "error" : "slow_down"
}

Sobald sich der Nutzer anmeldet und Ihrer Anwendung Zugriff auf die angeforderten Bereiche gewährt, enthält die Antwort auf die nächste Anfrage Ihrer Anwendung ein ID-Token, ein Zugriffstoken und ein Aktualisierungstoken:

{
  "access_token": "ya29.AHES6ZSuY8f6WFLswSv0HZLP2J4cCvFSj-8GiZM0Pr6cgXU",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1/551G1yXUqgkDGnkfFk6ZbjMMMDIMxo3JFc8lY8CAR-Q",
  "id_token": "eyJhbGciOiJSUzI..."
}

Nach Erhalt dieser Antwort kann Ihre Anwendung das ID-Token decodieren, um grundlegende Profilinformationen über den angemeldeten Nutzer abzurufen, oder das ID-Token an den Back-End-Server Ihrer App senden, um sich sicher beim Server zu authentifizieren. Außerdem kann die Anwendung das Zugriffstoken verwenden, um die Google APIs aufzurufen, die der Nutzer autorisiert hat.

ID- und Zugriffstokens haben eine begrenzte Lebensdauer. Damit der Nutzer über die Lebensdauer des Tokens hinaus angemeldet bleibt, speichern Sie das Aktualisierungstoken und verwenden Sie es, um neue Tokens anzufordern.

Nutzerprofilinformationen aus dem ID-Token abrufen

Du kannst Profilinformationen über den angemeldeten Nutzer abrufen, indem du das ID-Token mit einer beliebigen JWT-Decodierungsbibliothek decodieren. Verwenden Sie beispielsweise die Auth0-JavaScript-Bibliothek jwt-decode:

var user_profile = jwt_decode(<var>id_token</var>);

// The "sub" field is available on all ID tokens. This value is unique for each
// Google account and can be used to identify the user. (But do not send this
// value to your server; instead, send the whole ID token so its authenticity
// can be verified.)
var user_id = user_profile["sub"];

// These values are available when you request the "profile" and "email" scopes.
var user_email = user_profile["email"];
var email_verified = user_profile["email_verified"];
var user_name = user_profile["name"];
var user_photo_url = user_profile["picture"];
var user_given_name = user_profile["given_name"];
var user_family_name = user_profile["family_name"];
var user_locale = user_profile["locale"];

Weitere Informationen