OAuth 2.0 na potrzeby aplikacji TV i urządzeń o ograniczonym dostępie

W tym dokumencie wyjaśniono, jak wdrożyć autoryzację OAuth 2.0 w celu uzyskania dostępu do interfejsu API danych YouTube za pośrednictwem aplikacji działających na urządzeniach takich jak telewizory, konsole do gier i drukarki. Dokładniej rzecz ujmując, przepływ ten jest przeznaczony dla urządzeń, które nie mają dostępu do przeglądarki lub mają ograniczone możliwości wprowadzania danych.

OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy jednoczesnym zachowaniu poufności nazw, haseł i innych informacji. Na przykład aplikacja telewizyjna może wykorzystać protokół OAuth 2.0, aby uzyskać pozwolenie na wybranie pliku przechowywanego na Dysku Google.

Ponieważ aplikacje wykorzystujące ten przepływ są rozproszone na poszczególnych urządzeniach, zakłada się, że aplikacje nie mogą zachowywać tajemnic. Mogą uzyskiwać dostęp do interfejsów API Google, gdy użytkownik korzysta z aplikacji lub gdy aplikacja działa w tle.

Alternatywy

Jeśli piszesz aplikację przeznaczoną na platformę Android, iOS, macOS, Linux lub Windows (w tym Universal Windows Platform), która ma dostęp do przeglądarki i oferuje pełne możliwości wprowadzania danych, użyj protokołu OAuth 2.0 dla aplikacji mobilnych i stacjonarnych. (Należy stosować ten przepływ nawet jeśli aplikacja jest narzędziem wiersza poleceń bez graficznego interfejsu.)

Jeśli tylko chcesz logować użytkowników za pomocą ich kont Google i używać tokena identyfikacyjnego JWT do uzyskiwania podstawowych informacji o profilu użytkownika, zapoznaj się z artykułem Logowanie na telewizorach i urządzeniach wejściowych o ograniczonej liczbie wejść.

Wymagania wstępne

Włączanie interfejsów API w projekcie

Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć te interfejsy 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. Aby znaleźć i włączyć interfejs API danych YouTube, skorzystaj ze strony Biblioteka. Znajdź inne interfejsy API, z których będzie korzystać Twoja aplikacja i włącz je również.

Tworzenie danych uwierzytelniających

Każda aplikacja, która używa OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google, musi mieć dane logowania autoryzacji, które identyfikują aplikację na serwerze OAuth 2.0 Google. Poniżej znajdziesz instrukcje tworzenia danych logowania do projektu. Aplikacje mogą następnie używać tych danych logowania do uzyskiwania dostępu do interfejsów API włączonych w tym projekcie.

1. Go to the Clients page.
2. Kliknij Utwórz klienta.
3. Wybierz typ aplikacji Telewizory i urządzenia o ograniczonym wejściu.
4. Nadaj nazwę klientowi OAuth 2.0 i kliknij Utwórz.

Zidentyfikuj zakresy dostępu

Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych jej zasobów, a użytkownikom – kontrolowanie zakresu dostępu przyznawanego aplikacji. Dlatego może istnieć odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Zanim zaczniesz wdrażać autoryzację OAuth 2.0, określ zakresy, do których Twoja aplikacja będzie potrzebować dostępu.

Interfejs YouTube Data API v3 używa tych zakresów:

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

Uzyskiwanie tokenów dostępu OAuth 2.0

Nawet jeśli aplikacja działa na urządzeniu o ograniczonych możliwościach wprowadzania danych, użytkownicy muszą mieć oddzielny dostęp do urządzenia o większych możliwościach wprowadzania danych, aby ukończyć ten proces autoryzacji. Proces składa się z tych kroków:

1. Aplikacja wysyła do serwera autoryzacji Google żądanie, które identyfikuje zakresy, do których aplikacja będzie prosić o uprawnienia dostępu.
2. Serwer odpowiada, przesyłając kilka informacji, które są używane w kolejnych krokach, takich jak kod urządzenia i kod użytkownika.
3. Wyświetlasz informacje, które użytkownik może wpisać na osobnym urządzeniu, aby autoryzować aplikację.
4. Aplikacja zaczyna wysyłać zapytania do serwera autoryzacji Google, aby sprawdzić, czy użytkownik autoryzował aplikację.
5. Użytkownik przełącza się na urządzenie z większymi możliwościami wprowadzania danych, uruchamia przeglądarkę internetową, otwiera adres URL wyświetlony w kroku 3 i wpisuje kod, który również jest wyświetlony w kroku 3. Użytkownik może wtedy przyznać (lub odmówić) dostępu do aplikacji.
6. Następna odpowiedź na Twoje żądanie odpytywania zawiera tokeny, których aplikacja potrzebuje do autoryzowania żądań w imieniu użytkownika. (Jeśli użytkownik odmówi dostępu do aplikacji, odpowiedź nie będzie zawierać tokenów).

Ten proces ilustruje poniższy obraz:

W sekcjach poniżej znajdziesz szczegółowe wyjaśnienie tych kroków. Biorąc pod uwagę zakres możliwości i środowisk wykonawczych, w jakich mogą działać urządzenia, przykłady przedstawione w tym dokumencie wykorzystują narzędzie wiersza poleceń curl. Przykłady te powinny dać się łatwo przenieść do różnych języków i środowisk wykonawczych.

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

Na tym etapie urządzenie wysyła żądanie HTTP POST do serwera autoryzacji Google pod adresem https://oauth2.googleapis.com/device/code, które identyfikuje Twoją aplikację oraz zakresy dostępu, do których Twoja aplikacja chce uzyskać dostęp w imieniu użytkownika. Należy pobrać ten adres URL z dokumentu Discovery, korzystając z wartości metadanych device_authorization_endpoint. Uwzględnij następujące parametry żądania HTTP:

Przykłady

Poniższy fragment kodu pokazuje 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

Ten przykład pokazuje polecenie curl do wysłania tego samego żądania:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

Krok 2. Przetwórz odpowiedź serwera autoryzacji

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

Odpowiedź o sukcesie

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

Poniższy fragment kodu pokazuje 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
}

Odpowiedź o przekroczeniu limitu

Jeśli liczba żądań kodu urządzenia przekroczy limit powiązany z Twoim identyfikatorem klienta, otrzymasz odpowiedź 403 zawierającą ten błąd:

{
  "error_code": "rate_limit_exceeded"
}

W takim przypadku użyj strategii wycofywania, aby zmniejszyć częstotliwość wysyłania żądań.

Krok 3. Wyświetl kod użytkownika

Wyświetl użytkownikowi wartości verification_url i user_code uzyskane w kroku 2. Obie wartości mogą zawierać dowolny znak z zestawu znaków US-ASCII, który można wydrukować. Treści wyświetlane użytkownikowi powinny zawierać instrukcje, aby otworzył on stronę verification_url na innym urządzeniu i wpisał user_code.

Projektując interfejs, pamiętaj o tych zasadach:

• user_code
  • Wartość user_code musi być wyświetlana w polu, które może pomieścić 15 znaków o rozmiarze „W”. Innymi słowy, jeśli możesz prawidłowo wyświetlić kod WWWWWWWWWWWWWWW, interfejs jest prawidłowy i zalecamy użycie tego ciągu znaków podczas testowania sposobu wyświetlania user_code w interfejsie.
  • Znak user_code uwzględnia wielkość liter i nie należy go w żaden sposób modyfikować, np. zmieniać wielkości liter ani wstawiać innych znaków formatowania.
• verification_url
  • Miejsce, w którym wyświetlasz wartość verification_url, musi być wystarczająco szerokie, aby pomieścić ciąg URL o długości 40 znaków.
  • Nie modyfikuj w żaden sposób znaku verification_url, z wyjątkiem opcjonalnego usunięcia schematu na potrzeby wyświetlania. Jeśli planujesz usunąć schemat (np. https://) z adresu URL ze względu na wyświetlanie, upewnij się, że Twoja aplikacja obsługuje warianty http i https.

Krok 4. Wyślij zapytanie do serwera autoryzacji Google

Użytkownik będzie korzystać z osobnego urządzenia, aby przejść do verification_url i przyznać (lub odmówić) dostępu, więc urządzenie wysyłające żądanie nie otrzyma automatycznie powiadomienia, gdy użytkownik odpowie na żądanie dostępu. Z tego powodu urządzenie wysyłające żądanie musi odpytywać serwer autoryzacji Google, aby określić, kiedy użytkownik odpowie na żądanie.

Urządzenie wysyłające prośbę powinno kontynuować wysyłanie żądań odpytywania, dopóki nie otrzyma odpowiedzi wskazującej, że użytkownik odpowiedział na prośbę o dostęp, lub dopóki nie wygasną wartości device_code i user_code uzyskane w  kroku 2. Wartość interval zwrócona w kroku 2 określa czas oczekiwania w sekundach między żądaniami.

Adres URL punktu końcowego do sondowania to https://oauth2.googleapis.com/token. Żądanie odpytywania zawiera te parametry:

Przykłady

Poniższy fragment kodu pokazuje 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

Ten przykład pokazuje polecenie curl do wysłania tego samego żądania:

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" \
         https://oauth2.googleapis.com/token

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

Na ilustracji poniżej widać stronę podobną do tej, którą użytkownicy zobaczą po kliknięciu ikony verification_url wyświetlonej w kroku 3:

Po wpisaniu znaku user_code i zalogowaniu się w Google (jeśli użytkownik nie jest jeszcze zalogowany) wyświetli się ekran zgody podobny do tego poniżej:

Krok 6. Przetwarzanie odpowiedzi na prośby o głosowanie

Serwer autoryzacji Google odpowiada na każde żądanie sprawdzające 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 i token odświeżania. Te tokeny umożliwiają urządzeniu 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 urządzenie ma dostęp).

W tym przypadku odpowiedź interfejsu API zawiera te pola:

Poniższy fragment przedstawia 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 okres ważności. Jeśli Twoja aplikacja potrzebuje dostępu do interfejsu API przez dłuższy czas, może użyć tokena odświeżania w celu uzyskania nowego tokena dostępu. Jeśli Twoja aplikacja potrzebuje tego typu dostępu, powinna zapisać token odświeżania do późniejszego wykorzystania.

Odmowa dostępu

Jeśli użytkownik odmówi udzielenia dostępu do urządzenia, serwer odpowie kodem stanu odpowiedzi HTTP 403 (Forbidden). Odpowiedź zawiera następujący błąd:

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

Oczekiwanie na autoryzację

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

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

Zbyt częste przeprowadzanie ankiet

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

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

Inne błędy

Serwer autoryzacji zwraca również błędy, jeśli żądanie sondowania nie zawiera wymaganych parametrów lub ma nieprawidłową wartość parametru. Te żądania zwykle mają kod stanu odpowiedzi HTTP 400 (Bad Request) lub 401 (Unauthorized). Do błędów tych zaliczają się:

Wywoływanie interfejsów API Google

Gdy aplikacja uzyska token dostępu, może go używać do wywoływania interfejsu Google API w imieniu danego konta użytkownika, jeśli przyznano zakresy dostępu wymagane przez interfejs API. Aby to zrobić, uwzględnij token dostępu w żądaniu do interfejsu API, dodając parametr zapytania access_token lub wartość nagłówka HTTP AuthorizationBearer. W miarę możliwości preferowany jest nagłówek HTTP, ponieważ ciągi zapytań są zwykle widoczne w logach serwera. W większości przypadków możesz użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (na przykład podczas wywoływania interfejsu API YouTube Live Streaming API).

Należy pamiętać, że interfejs API YouTube Live Streaming nie obsługuje przepływu konta usługi. Ponieważ nie ma możliwości połączenia konta usługi z kontem YouTube, próby autoryzacji żądań za pomocą tego przepływu spowodują błąd NoLinkedYouTubeAccount.

Wszystkie interfejsy API Google i ich zakresy możesz wypróbować na stronie OAuth 2.0 Playground.

Przykłady żądań HTTP GET

Wywołanie punktu końcowego liveBroadcasts.list (interfejs API YouTube Live Streaming) przy użyciu nagłówka HTTP Authorization: Bearer może wyglądać następująco. Pamiętaj, że musisz podać własny token dostępu:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl przykładu

Możesz przetestować te polecenia za pomocą aplikacji wiersza poleceń curl. Oto przykład, w którym użyto opcji nagłówka HTTP (preferowanej):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Możesz też wybrać opcję parametru ciągu zapytania:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Odświeżanie tokena dostępu

Tokeny dostępu okresowo wygasają i stają się nieprawidłowymi danymi uwierzytelniającymi dla powiązanego żądania API. Możesz odświeżyć token dostępu bez proszenia użytkownika o uprawnienia (nawet gdy użytkownik jest nieobecny), jeśli poprosisz o dostęp offline do zakresów powiązanych z tokenem.

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

Poniższy fragment kodu pokazuje przykładowe żądanie:

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

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

Dopóki użytkownik nie cofnie dostępu przyznanego aplikacji, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Poniższy fragment kodu pokazuje przykładową odpowiedź:

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

Pamiętaj, że liczba tokenów odświeżania, które zostaną wydane, jest ograniczona. Obowiązuje limit dla każdej kombinacji klient/użytkownik i inny limit dla każdego użytkownika we wszystkich klientach. Tokeny odświeżania należy zapisywać w pamięci długoterminowej i używać ich tak długo, jak są ważne. Jeśli aplikacja wyśle zbyt wiele żądań tokenów odświeżania, może przekroczyć te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.

Unieważnienie tokena

W niektórych przypadkach użytkownik może chcieć cofnąć dostęp przyznany aplikacji. Użytkownik może cofnąć dostęp, otwierając Ustawienia konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu strony lub aplikacji w artykule pomocy Strony internetowe i aplikacje innych firm z dostępem do Twojego konta.

Aplikacja może też programowo unieważnić przyznany jej dostęp. Programowe wycofywanie jest ważne w przypadkach, gdy użytkownik rezygnuje z subskrypcji, usuwa aplikację lub zasoby interfejsu API wymagane przez aplikację uległy znacznym zmianom. Innymi słowy, część procesu usuwania może obejmować żądanie interfejsu API, aby upewnić się, że uprawnienia przyznane wcześniej aplikacji zostały usunięte.

Aby programowo unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i dołącza token 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 odpowiedni token odświeżania, token odświeżania również zostanie unieważniony.

Jeśli wycofanie zostanie przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędów zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

Dozwolone zakresy

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

Dostęp zależny od czasu

Dostęp czasowy umożliwia użytkownikowi przyznanie aplikacji dostępu do jego danych na ograniczony czas w celu wykonania działania. Dostęp czasowy jest dostępny w wybranych usługach Google podczas procesu uzyskiwania zgody. Użytkownicy mogą przyznać dostęp na ograniczony czas. Przykładem jest interfejs Data Portability API, który umożliwia jednorazowe przeniesienie danych.

Gdy użytkownik przyzna Twojej aplikacji dostęp czasowy, token odświeżania wygaśnie po upływie określonego czasu. Pamiętaj, że tokeny odświeżania mogą zostać unieważnione wcześniej w określonych okolicznościach. Szczegółowe informacje znajdziesz w tych przypadkach. Pole refresh_token_expires_in zwrócone w odpowiedzi wymiany kodu autoryzacji w takich przypadkach reprezentuje czas pozostały do wygaśnięcia tokena odświeżania.