OAuth 2.0 dla aplikacji na telewizory i urządzenia wejściowe z ograniczeniami

Ten dokument wyjaśnia, jak wdrożyć autoryzację OAuth 2.0, aby uzyskać dostęp do interfejsów API Google przez aplikacje działające na urządzeniach takich jak telewizory, konsole do gier i drukarki. Ta procedura dotyczy urządzeń, które nie mają dostępu do przeglądarki lub mają ograniczone możliwości wprowadzania danych.

Protokół OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy zachowaniu ich nazw użytkowników, haseł i innych informacji. Aplikacja telewizyjna może na przykład użyć protokołu OAuth 2.0, aby uzyskać pozwolenie na wybór pliku zapisanego na Dysku Google.

Ponieważ aplikacje korzystające z tego przepływu są rozprowadzane na poszczególne urządzenia, zakłada się, że nie mogą one być tajne. Może korzystać z interfejsów API Google, gdy użytkownik jest zalogowany w aplikacji lub gdy działa w tle.

Alternatywy

Jeśli piszesz aplikację dla platformy, takiej jak Android, iOS, macOS, Linux czy Windows (w tym uniwersalnej platformy Windows), która ma dostęp do przeglądarki i wszystkich możliwości wprowadzania danych, użyj przepływu OAuth 2.0 w aplikacjach mobilnych i komputerowych. Należy z niego korzystać, nawet jeśli aplikacja jest narzędziem wiersza poleceń bez graficznego interfejsu).

Jeśli chcesz logować tylko użytkowników za pomocą kont Google i używać tokena identyfikatora JWT do uzyskiwania podstawowych informacji o profilu użytkownika, przeczytaj artykuł Logowanie się na telewizorach i urządzeniach z ograniczonym dostępem.

Wymagania wstępne

Włącz interfejsy API w projekcie

Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć je w API Console.

Aby włączyć interfejs API w projekcie:

  1. Open the API Library w: Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Na liście API Library znajdują się wszystkie dostępne interfejsy API pogrupowane według rodziny usług i popularności. Jeśli interfejs API, który chcesz włączyć, nie jest widoczny na liście, użyj funkcji wyszukiwania, aby go znaleźć, lub kliknij Wyświetl wszystko w rodzinie usług, do której należy.
  4. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Tworzenie danych uwierzytelniających

Każda aplikacja, która uzyskuje dostęp do interfejsów API Google przy użyciu OAuth 2.0, musi mieć dane uwierzytelniające, które identyfikują aplikację z serwerem OAuth 2.0 Google. Poniżej wyjaśniamy, jak utworzyć dane logowania do projektu. Dzięki temu aplikacje będą mogły korzystać z danych logowania, aby uzyskać dostęp do interfejsów API włączonych w tym projekcie.

  1. Go to the Credentials page.
  2. Kliknij Utwórz dane logowania > identyfikator klienta OAuth.
  3. Wybierz typ aplikacji Telewizory i urządzenia wejściowe z ograniczonym dostępem.
  4. Nazwij klienta OAuth 2.0 i kliknij Utwórz.

Określ zakresy dostępu

Zakresy umożliwiają aplikacji żądanie tylko tych zasobów, których potrzebują, a także umożliwienie użytkownikom kontrolowania poziomu dostępu przyznawanego aplikacji. Dlatego może występować zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Zanim zaczniesz wdrażać autoryzację OAuth 2.0, zalecamy wskazanie zakresów, do których aplikacja będzie potrzebować dostępu.

Zobacz listę Dozwolone zakresy dla zainstalowanych aplikacji lub urządzeń.

Uzyskiwanie tokenów dostępu do protokołu OAuth 2.0

Mimo że Twoja aplikacja działa na urządzeniu z ograniczonymi możliwościami wpisywania danych, użytkownicy muszą mieć oddzielny dostęp do urządzeń z lepszymi funkcjami wprowadzania danych, aby dokończyć ten proces autoryzacji. Proces jest następujący:

  1. Aplikacja wysyła żądanie do serwera autoryzacji Google i wskazuje zakresy, do których aplikacja będzie prosić o dostęp.
  2. W odpowiedzi serwer przesyła kilka informacji wykorzystywanych w kolejnych krokach, np. kod urządzenia i kod użytkownika.
  3. Możesz wyświetlać informacje, które użytkownik może wpisać na innym urządzeniu, aby autoryzować swoją aplikację.
  4. Twoja aplikacja rozpoczyna odpytywanie serwera autoryzacji Google i określa, czy użytkownik autoryzował Twoją aplikację.
  5. Użytkownik przechodzi na urządzenie z bardziej rozbudowanymi możliwościami wprowadzania tekstu, uruchamia przeglądarkę internetową, otwiera URL wyświetlany w kroku 3 i wpisuje kod, który wyświetla się w kroku 3. Użytkownik może następnie przyznać (lub odrzucić) dostęp do aplikacji.
  6. Następna odpowiedź na żądanie ankiety zawiera tokeny, które aplikacja musi autoryzować w imieniu użytkownika. (Jeśli użytkownik odmówił dostępu do aplikacji, odpowiedź nie zawiera tokenów).

Poniższa ilustracja przedstawia ten proces:

użytkownik loguje się na innym urządzeniu z przeglądarką,

Poniżej znajdziesz szczegółowe omówienie tych czynności. W tym dokumencie używamy narzędzia wiersza poleceń curl z uwzględnieniem różnych możliwości i środowisk środowiska wykonawczego używanych przez urządzenia. Te przykłady powinny być łatwe do przeniesienia do różnych języków i środowisk wykonawczych.

Krok 1. Poproś o kody urządzeń i użytkowników

W tym kroku urządzenie wyśle żądanie HTTP POST do serwera autoryzacji Google na adres https://oauth2.googleapis.com/device/code, które identyfikuje Twoją aplikację oraz zakresy dostępu, do których aplikacja chce uzyskiwać dostęp w imieniu użytkownika. Ten adres URL powinien zostać pobrany z dokumentu opisującego za pomocą wartości metadanych device_authorization_endpoint. Uwzględnij te parametry żądania HTTP:

Parametry
client_id Wymagany

Identyfikator klienta aplikacji. Tę wartość znajdziesz w API ConsoleCredentials page.

scope Wymagany

Lista rozdzielonych spacjami, które identyfikują zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi. Listę zainstalowanych aplikacji lub urządzeń znajdziesz na liście Dozwolone zakresy.

Zakresy umożliwiają aplikacji żądanie tylko tych zasobów, których potrzebują, a także umożliwienie użytkownikom kontrolowania poziomu dostępu przyznawanego aplikacji. Dlatego występuje odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Przykłady

Ten fragment kodu zawiera przykładowe żądanie:

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

client_id=client_id&scope=email%20profile

Oto przykład polecenia curl, które pozwala wysłać to samo żądanie:

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

Krok 2. Przetwórz odpowiedź z serwera autoryzacji

Serwer autoryzacji zwróci jedną z następujących odpowiedzi:

Odpowiedź z potwierdzeniem

Jeśli żądanie jest prawidłowe, odpowiedź będzie obiektem JSON zawierającym te właściwości:

Właściwości
device_code Wartość przypisywana przez Google do identyfikowania urządzenia, na którym działa aplikacja żądająca autoryzacji. Użytkownik autoryzuje to urządzenie na innym urządzeniu z lepszymi możliwościami wpisywania danych. Użytkownik może na przykład autoryzować aplikację na telewizorze, używając laptopa lub telefonu komórkowego. W tym przypadku device_code wskazuje telewizor.

Pozwala on bezpiecznie sprawdzić, czy użytkownik przyznał aplikacji dostęp.

expires_in Czas (w sekundach), przez jaki device_code i user_code są prawidłowe. Jeśli w tym czasie użytkownik nie ukończy procesu autoryzacji, a Twoje urządzenie nie będzie mogło pobrać informacji na temat jego decyzji, konieczne może być ponowne rozpoczęcie tego procesu od kroku 1.
interval Czas oczekiwania urządzenia (w sekundach) między żądaniami odpytywania. Jeśli na przykład wartość to 5, urządzenie powinno wysłać żądanie odpytywania do serwera autoryzacji Google co 5 sekund. Więcej informacji znajdziesz w kroku 3.
user_code Wielkość liter określa Google zakresy, do których aplikacja prosi o dostęp. Interfejs użytkownika poinstruuje użytkownika, aby wpisał tę wartość na osobnym urządzeniu z bardziej zaawansowanymi możliwościami wprowadzania danych. Następnie Google wyświetla tę wartość, aby wyświetlić użytkownikowi odpowiedni zestaw zakresów, gdy wyświetla użytkownikowi prośbę o przyznanie dostępu do aplikacji.
verification_url Adres URL, do którego użytkownik musi przejść na osobnym urządzeniu, aby wpisać adres user_code oraz przyznać lub zablokować dostęp do aplikacji. Ta wartość jest wyświetlana w interfejsie użytkownika.

Poniższy fragment kodu zawiera przykładową odpowiedź:

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

Przekroczono limit miejsca

Jeśli żądania kodu urządzenia przekroczyły limit powiązany z identyfikatorem klienta, otrzymasz odpowiedź 403 z tym błędem:

{
  "error_code": "rate_limit_exceeded"
}

W takim przypadku stosuj strategię sprzężenia zwrotnego, aby zmniejszyć częstotliwość żądań.

Krok 3. Wyświetl kod użytkownika

Wyświetl verification_url i user_code uzyskane w kroku 2. Obie wartości mogą zawierać dowolny znak do wydrukowania z zestawu znaków US-ASCII. Wyświetlane użytkownikowi treści powinny zawierać instrukcje, by na osobnym urządzeniu przejść do verification_url i wpisać user_code.

Projektując interfejs, pamiętaj o tych regułach:

  • user_code
    • Element user_code musi być wyświetlany w polu, który obsługuje 15 znaków rozmiaru. Innymi słowy, jeśli możesz prawidłowo wyświetlać kod WWWWWWWWWWWWWWW, Twój interfejs użytkownika jest prawidłowy i zalecamy użycie tej wartości ciągu podczas testowania sposobu wyświetlania user_code w interfejsie.
    • W elemencie user_code rozróżniana jest wielkość liter. Nie należy jej w żaden sposób zmieniać, na przykład zmieniać wielkości liter czy wstawiać inne znaki formatowania.
  • verification_url
    • Przestrzeń, w której wyświetla się verification_url, musi być na tyle szeroka, aby obsłużyć ciąg znaków URL o długości 40 znaków.
    • Nie należy w żaden sposób modyfikować elementu verification_url z wyjątkiem możliwości usunięcia schematu wyświetlania. Jeśli planujesz usunąć schemat (np. https://) z adresu URL ze względu na sposób wyświetlania, upewnij się, że aplikacja może obsługiwać zarówno warianty http, jak i https.

Krok 4. Serwer autoryzacji Google do przeprowadzenia ankiet

Ponieważ użytkownik będzie korzystał z oddzielnego urządzenia, by przejść do verification_url i przyznać (lub odmówić) dostępu, urządzenie, z którego pochodzi żądanie, nie otrzyma automatycznie powiadomienia o odpowiedzi na prośbę o dostęp. Z tego powodu urządzenie, z którego pochodzi żądanie, musi przeprowadzić ankietę na serwerze autoryzacji Google, aby określić, kiedy użytkownik odpowiedział na żądanie.

Urządzenie wysyłające żądanie powinno nadal wysyłać żądania dotyczące odpytywania, dopóki nie otrzyma odpowiedzi informującej o tym, że użytkownik odpowiedział na prośbę o dostęp lub dopóki device_code i user_code uzyskane w kroku 2 nie wygasną. Parametr interval zwracany w kroku 2 określa czas oczekiwania między żądaniami (w sekundach).

URL punktu końcowego do przeprowadzenia ankiety to https://oauth2.googleapis.com/token. Żądanie odpytywania zawiera następujące parametry:

Parametry
client_id Identyfikator klienta aplikacji. Tę wartość znajdziesz w API ConsoleCredentials page.
client_secret Klucz klienta dla podanego client_id. Tę wartość znajdziesz w API ConsoleCredentials page.
device_code device_code zwrócony przez serwer autoryzacji w kroku 2.
grant_type Ustaw ją na urn:ietf:params:oauth:grant-type:device_code.

Przykłady

Ten fragment kodu zawiera przykładowe żądanie:

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

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Oto przykład polecenia curl, które pozwala wysłać to samo żądanie:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         /token

Krok 5. Użytkownik odpowiada na prośbę o dostęp

Na obrazie poniżej widać stronę podobną do tej, którą użytkownicy widzą po przejściu do verification_url w kroku 3:

Podłącz urządzenie, wpisując kod

Po wpisaniu user_code i zalogowaniu się w Google użytkownik zobaczy ekran zgody podobny do tego poniżej:

Przykładowy ekran zgody dla klienta urządzenia

Krok 6. Przetwórz odpowiedzi na żądania dotyczące ankiet

Serwer autoryzacji Google dla każdego żądania odpytywania odpowiada jedną z tych odpowiedzi:

Dostęp przyznany

Jeśli użytkownik przyznał dostęp do urządzenia (klikając Allow na ekranie zgody), odpowiedź zawiera token dostępu oraz token odświeżania. Tokeny umożliwiają dostęp do interfejsów API Google w imieniu użytkownika. Właściwość scope w odpowiedzi określa, do których interfejsów API ma dostęp urządzenie.

W takim przypadku odpowiedź API zawiera te pola:

Pola
access_token Token wysyłany przez aplikację, aby autoryzować żądanie do interfejsu API Google.
expires_in Pozostały czas życia tokena dostępu (w sekundach).
refresh_token Token, za pomocą którego możesz uzyskać nowy token dostępu. Tokeny odświeżania są ważne, dopóki użytkownik ich nie unieważni. Pamiętaj, że tokeny odświeżania zawsze zwracają urządzenia.
scope Zakresy dostępu przyznane przez zasadę access_token wyrażoną jako lista ciągów rozdzielanych spacjami, z uwzględnieniem wielkości liter.
token_type Typ zwracanego tokena. Obecnie wartość tego pola jest zawsze ustawiona na Bearer.

Poniższy fragment kodu zawiera przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Tokeny dostępu mają ograniczony czas trwania. Jeśli Twoja aplikacja potrzebuje dostępu do interfejsu API przez dłuższy okres, może użyć tokena odświeżania, aby uzyskać nowy token dostępu. Jeśli Twoja aplikacja potrzebuje tego typu dostępu, powinna przechowywać token odświeżania do użycia w przyszłości.

Odmowa dostępu

Jeśli użytkownik odmówi przyznania dostępu do urządzenia, odpowiedź serwera będzie zawierać kod stanu odpowiedzi HTTP 403 (Forbidden). Odpowiedź zawiera ten błąd:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Oczekiwanie na autoryzację

Jeśli użytkownik nie zakończył jeszcze procesu autoryzacji, serwer zwraca kod stanu odpowiedzi HTTP 428 (Precondition Required). Odpowiedź zawiera ten błąd:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Ankiety są zbyt częste

Jeśli urządzenie zbyt często wysyła żądania odpytywania, serwer zwraca kod stanu odpowiedzi HTTP 403 (Forbidden). Odpowiedź zawiera ten błąd:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Inne błędy

Serwer autoryzacji zwraca też błędy, jeśli w żądaniu odpytywania brakuje wymaganych parametrów lub wartość parametru jest nieprawidłowa. Żądania te mają zwykle kod stanu odpowiedzi HTTP 400 (Bad Request) lub 401 (Unauthorized). Błędy te obejmują:

Błąd Kod stanu HTTP Opis
invalid_client 401 Nie znaleziono klienta OAuth. Ten błąd występuje np. wtedy, gdy wartość parametru client_id jest nieprawidłowa.
invalid_grant 400 Wartość parametru code jest nieprawidłowa.
unsupported_grant_type 400 Wartość parametru grant_type jest nieprawidłowa.

Wywołanie interfejsów API Google

Gdy aplikacja uzyska token dostępu, możesz go używać do wywoływania interfejsu API Google w imieniu danego konta użytkownika, jeśli przyznano zakresy dostępu wymagane przez interfejs API. Aby to zrobić, umieść token dostępu w żądaniu do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka Authorization nagłówka Bearer. W miarę możliwości zalecamy użycie nagłówka HTTP, ponieważ ciągi zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków biblioteki klienta możesz skonfigurować, aby wywoływać wywołania interfejsów API Google (na przykład podczas wywoływania interfejsu Drive Files API).

Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w Play OAuth 2.0 Playground.

Przykłady użycia HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) z nagłówkiem HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz określić własny token dostępu:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Oto wywołanie tego samego interfejsu API dla uwierzytelnionego użytkownika z wykorzystaniem parametru ciągu zapytania access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Przykłady zapytań z operatorem curl

Te polecenia możesz przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład z użyciem opcji nagłówka HTTP (co jest zalecane):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Możesz też skorzystać z parametru ciągu zapytania:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Odświeżanie tokena dostępu

Tokeny dostępu okresowo tracą ważność i stają się nieprawidłowe poświadczenia powiązanego żądania interfejsu API. Jeśli chcesz uzyskać dostęp offline do zakresów powiązanych z tokenem, możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (w tym, gdy nie ma użytkownika).

Aby odświeżyć token dostępu, aplikacja wysyła żądanie HTTPS POST do serwera autoryzacji Google (https://oauth2.googleapis.com/token) zawierającego te parametry:

Pola
client_id Identyfikator klienta uzyskany z API Console.
client_secret Obiekt tajny klienta uzyskany z API Console.
grant_type Zgodnie z definicją w specyfikacji OAuth 2.0 to pole musi mieć wartość refresh_token.
refresh_token Token odświeżania zwrócony z wymiany kodu autoryzacji.

Ten fragment kodu zawiera przykładowe żądanie:

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Dopóki użytkownik nie anuluje dostępu aplikacji, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Ten fragment kodu zawiera przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Pamiętaj, że obowiązuje limit liczby tokenów odświeżania, które mogą zostać zrealizowane: jeden limit na kombinację klienta i użytkownika i jeden na użytkownika we wszystkich klientach. Zapisz tokeny odświeżania w długoterminowym miejscu i używaj ich, dopóki będą ważne. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, może to spowodować przekroczenie tych limitów. W takim przypadku starsze tokeny odświeżania przestaną działać.

Unieważnianie tokena

W niektórych przypadkach użytkownik może unieważnić dostęp aplikacji. Użytkownik może cofnąć dostęp w ustawieniach konta. Więcej informacji znajdziesz w sekcji pomocy dotyczącej usuwania dostępu do witryn i aplikacji z witryn i aplikacji innych firm, które mają dostęp do Twojego konta.

Możliwe jest też unieważnienie przez aplikację przyznanego dostępu. Automatyczne unieważnienie jest ważne, jeśli użytkownik anuluje subskrypcję, usunie aplikację lub zasoby interfejsu API wymagane przez aplikację znacznie się zmieniły. Oznacza to, że część procesu usuwania może obejmować żądanie interfejsu API, które zapewnia usunięcie wcześniej przyznanych uprawnień aplikacji.

Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i uwzględnia go jako parametr:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Może to być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma przypisany token odświeżania, też zostanie on unieważniony.

Jeśli odwołanie zostało pomyślnie przetworzone, kod stanu HTTP odpowiedzi będzie wynosił 200. W przypadku błędów zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

Dozwolone zakresy

Przepływ OAuth 2.0 na urządzeniach jest obsługiwany tylko w przypadku tych zakresów:

OpenID Connect, Logowanie przez Google

  • email
  • openid
  • profile

Interfejs Drive API

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

Interfejs YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly