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

Z tego dokumentu dowiesz się, jak wdrożyć autoryzację OAuth 2.0, aby uzyskać dostęp do interfejsu YouTube Data API za pomocą aplikacji działających na urządzeniach takich jak telewizory, konsole do gier i drukarki. Ten proces jest przeznaczony w szczególności 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 na telewizor może używać OAuth 2.0, aby uzyskać uprawnienia do wybrania pliku zapisanego na Dysku Google.

Aplikacje korzystające z tego przepływu są rozpowszechniane na poszczególnych urządzeniach, więc zakłada się, że nie mogą one zachować tajemnicy. Mogą one uzyskiwać dostęp do interfejsów API Google, gdy użytkownik korzysta z aplikacji lub gdy działa ona w tle.

Alternatywne adresy

Jeśli piszesz aplikację na platformę taką jak Android, iOS, macOS, Linux lub Windows (w tym uniwersalną platformę Windows), która ma dostęp do przeglądarki i pełne możliwości wprowadzania danych, użyj przepływu OAuth 2.0 w przypadku aplikacji mobilnych i na komputery. (Należy użyć tego procesu nawet wtedy, gdy aplikacja jest narzędziem wiersza poleceń bez interfejsu graficznego).

Jeśli chcesz tylko 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 sekcją Logowanie na telewizorach i urządzeniach z ograniczonymi możliwościami wprowadzania danych.

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. Na stronie Biblioteka znajdź i włącz interfejs YouTube Data API. Znajdź inne interfejsy API, z których będzie korzystać Twoja aplikacja, i też je włącz.

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 Credentials page.
2. Kliknij Utwórz klienta.
3. Wybierz typ aplikacji Telewizory i urządzenia z ograniczoną możliwością wpisywania.
4. Nadaj nazwę klientowi OAuth 2.0 i kliknij Utwórz.

Określanie zakresów 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, zalecamy określenie zakresów, 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 dostęp.
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świetlany 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 instrukcje. Ze względu na różnorodność możliwości i środowisk wykonawczych, jakie mogą mieć urządzenia, w przykładach podanych w tym dokumencie użyto narzędzia wiersza poleceń curl. Przykłady te powinny być łatwe do przeniesienia na różne języki i środowiska wykonawcze.

Krok 1. Poproś o kody urządzenia i użytkownika

W tym kroku urządzenie wysyła żądanie HTTP POST do serwera autoryzacji Google pod adresem https://oauth2.googleapis.com/device/code, które identyfikuje aplikację oraz zakresy dostępu, do których aplikacja chce uzyskać dostęp w imieniu użytkownika. Ten adres URL należy pobrać z dokumentu Discovery za pomocą wartości metadanych device_authorization_endpoint. Uwzględnij te parametry żądania HTTP:

Przykłady

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

Ten przykład pokazuje polecenie curl, które wysyła to samo żądanie:

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 tych 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 użytkownik otworzył verification_url na osobnym 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 tej wartości ciągu znaków podczas testowania sposobu wyświetlania znaku 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 czy 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 elementu 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ęp, 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 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

Ten przykład pokazuje polecenie curl, które wysył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" \
         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 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 sondowanie

Serwer autoryzacji Google odpowiada na każde żądanie sondowania 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 takim przypadku odpowiedź interfejsu API zawiera te pola:

Poniższy fragment kodu pokazuje 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 ważności. Jeśli aplikacja potrzebuje dostępu do interfejsu API przez dłuższy czas, 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 późniejszego wykorzystania.

Odmowa dostępu

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

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

Oczekuje 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"
}

Zbyt częste odpytywanie

Jeśli urządzenie wysyła żądania sondowania zbyt często, 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 też błędy, jeśli w żądaniu odpytywania brakuje wymaganych parametrów lub ma ono nieprawidłową wartość parametru. Te żądania zwykle mają kod stanu odpowiedzi HTTP 400 (Bad Request) lub 401 (Unauthorized). Do takich błędów należą:

Wywoływanie interfejsów API Google

Gdy aplikacja uzyska token dostępu, może go używać do wywoływania interfejsu API Google w imieniu danego konta użytkownika, jeśli zakresy dostępu wymagane przez interfejs API zostały przyznane. Aby to zrobić, dołącz token dostępu do żądania wysyłanego do interfejsu API, uwzględniają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, aby skonfigurować wywołania interfejsów API Google (np. podczas wywoływania interfejsu YouTube Live Streaming API).

Pamiętaj, że interfejs YouTube Live Streaming API nie obsługuje przepływu konta usługi. Nie ma możliwości połączenia konta usługi z kontem YouTube, więc próby autoryzacji żądań za pomocą tego procesu będą generować 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 YouTube Live Streaming API) z nagłówkiem HTTP Authorization: Bearer może wyglądać tak: 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. Token dostępu możesz odświeżyć 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 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 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 na kombinację klient/użytkownik i limit na 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 zażąda zbyt wielu tokenów odświeżania, może przekroczyć te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.

Unieważnianie 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 witryny 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 wskazuje w takich przypadkach czas pozostały do wygaśnięcia tokena odświeżania.