OAuth 2.0 na potrzeby aplikacji telewizyjnych i urządzeń o ograniczonych wejściach

Z tego dokumentu dowiesz się, jak zaimplementować autoryzację OAuth 2.0, aby uzyskać dostęp do interfejsów API Google za pomocą aplikacji działających na urządzeniach takich jak telewizory, konsole do gier czy drukarki. Proces ten jest przeznaczony do 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 procesu są rozpowszechniane na poszczególne urządzenia, dlatego zakłada się, że nie mogą one trzymać w tajemnicy. Mogą one uzyskiwać dostęp do interfejsów API Google, gdy użytkownik korzysta z aplikacji lub gdy aplikacja działa w tle.

Możliwości

Jeśli piszesz aplikację na platformę, np. Android, iOS, macOS, Linux lub Windows (w tym Universal Windows Platform), 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 komputera. (powinieneś użyć tego procesu nawet wtedy, gdy Twoja aplikacja jest narzędziem wiersza poleceń bez interfejsu graficznego).

Jeśli tylko chcesz, aby użytkownicy logowali się na swoje konta Google i używali tokena identyfikującego JWT, aby uzyskać podstawowe informacje z profilu użytkownika, zapoznaj się z artykułem 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. API Library Wyświetla wszystkie dostępne interfejsy API pogrupowane według rodziny produktów i popularności. Jeśli interfejs API, który chcesz włączyć, nie jest widoczny na liście, wyszukaj go lub kliknij Wyświetl wszystkie w grupie produktów, 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 używa OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google, musi mieć poświadczenia autoryzacyjne, które identyfikują ją na serwerze OAuth 2.0 Google. Z tych instrukcji dowiesz się, jak utworzyć poświadczenia tożsamości do projektu. Twoje aplikacje mogą wtedy używać tych danych logowania do uzyskiwania dostępu do interfejsów API, które zostały włączone w tym projekcie.

1. Go to the Credentials page.
2. Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
3. Wybierz typ aplikacji TV i urządzenia z ograniczoną możliwością wpisywania.
4. Podaj nazwę klienta OAuth 2.0 i kliknij Utwórz.

Określanie zakresów dostępu

Zakresy umożliwiają aplikacji żądanie dostępu tylko do zasobów, których potrzebuje, a także kontrolowanie przez użytkowników zakresu dostępu przyznawanego aplikacji. Dlatego może istnieć odwrotna zależność między liczbą żądanych zakresów uprawnień a prawdopodobieństwom uzyskania zgody użytkownika.

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

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

Pobieranie tokenów dostępu OAuth 2.0

Chociaż aplikacja działa na urządzeniu z ograniczonymi możliwościami wprowadzania danych, użytkownicy muszą mieć osobny dostęp do urządzenia z bogatszymi możliwościami wprowadzania danych, aby ukończyć proces autoryzacji. Proces składa się z tych kroków:

1. Aplikacja wysyła żądanie do serwera autoryzacji Google, który identyfikuje zakresy. Aplikacja poprosi o dostęp do tych zakresów.
2. Serwer odpowiada kilkoma informacjami, które są używane w kolejnych krokach, takimi 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 ustalić, czy użytkownik zaaprobował Twoją aplikację.
5. Użytkownik przełącza się na urządzenie z bogatszymi możliwościami wprowadzania danych, uruchamia przeglądarkę, przechodzi do adresu URL wyświetlonego w kroku 3 i wpisuje kod, który również wyświetla się w kroku 3. Użytkownik może wtedy przyznać (lub odmówić) dostęp do aplikacji.
6. Następna odpowiedź na żądanie sondowania zawiera tokeny, których aplikacja potrzebuje do autoryzacji żądań w imieniu użytkownika. Jeśli użytkownik odmówił dostępu do aplikacji, odpowiedź nie będzie zawierać tokenów.

Proces ten obrazuje obraz poniżej:

W następnych sekcjach znajdziesz szczegółowe instrukcje. Ze względu na zakres możliwości i środowiska wykonawczego, z których mogą korzystać urządzenia, przykłady w tym dokumencie korzystają z utility wiersza poleceń curl. Te przykłady powinny być łatwe do przeportowania na różne języki i platformy.

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

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

Przykłady

Ten 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=email%20profile

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

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

Krok 2. Przetwórz odpowiedź serwera uwierzytelniania

Serwer autoryzacji zwróci jedną z tych odpowiedzi:

Odpowiedź na powodzenie

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

Ten 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ź na przekroczenie limitu

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

{
  "error_code": "rate_limit_exceeded"
}

W takim przypadku użyj strategii wycofywania się, aby zmniejszyć częstotliwość żą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. Treści wyświetlane użytkownikowi powinny zawierać instrukcje przejścia na verification_url na osobnym urządzeniu i wpisania kodu user_code.

Podczas projektowania interfejsu 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 wyświetlić kod WWWWWWWWWWWWWWWprawidłowo, interfejs jest prawidłowy. Zalecamy używanie tej wartości ciągu znaków podczas testowania sposobu wyświetlania wartości user_code w interfejsie.
  • Wielkość liter w identyfikatorze user_code ma znaczenie i nie należy go w żaden sposób modyfikować, np. przez zmianę wielkości liter lub wstawianie innych znaków formatowania.
• verification_url
  • Miejsce, w którym wyświetlasz element verification_url, musi być wystarczająco szerokie, aby pomieścić ciąg znaków adresu URL o długości 40 znaków.
  • Nie należy modyfikować elementu verification_url w żaden sposób, z wyjątkiem opcjonalnego usunięcia schematu wyświetlania. Jeśli z powodu wyświetlania chcesz usunąć schemat (np. https://) z adresu URL, upewnij się, że Twoja aplikacja może obsługiwać warianty http i https.

Krok 4. Odpytuj serwer autoryzacji Google

Użytkownik będzie używać osobnego urządzenia do przechodzenia do verification_url i przyznawania (lub odmowy przyznania) dostępu, więc urządzenie wysyłające żądanie nie zostanie automatycznie powiadomione, gdy użytkownik odpowie na prośbę o dostęp. Dlatego urządzenie wysyłające żądanie musi odpytywać serwer autoryzacji Google, aby określić, kiedy użytkownik odpowiedział na żądanie.

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

Adres URL punktu końcowego, z którego chcesz pobrać dane, to https://oauth2.googleapis.com/token. Żądanie sprawdzania zawiera te parametry:

Przykłady

Ten 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, 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 poniższym obrazku widać stronę podobną do tej, którą użytkownicy widzą po przejściu do strony verification_url wyświetlonej w kroku 3:

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

Krok 6. Przetwarzaj odpowiedzi na żądania głosowania

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. Tokeny umożliwiają urządzeniu dostęp do interfejsów Google API w imieniu użytkownika. (Właściwość scope w odpowiedzi określa, do których interfejsów API ma dostęp dane urządzenie).

W tym przypadku odpowiedź interfejsu API zawiera te pola:

Ten 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 aplikacja potrzebuje tego typu dostępu, powinna przechowywać token odświeżania na potrzeby późniejszego użycia.

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 ukoń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ęsto przeprowadzać ankiety;

Jeśli urządzenie wysyła żądania sondowania zbyt często, 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 sondowania brakuje wymaganych parametrów lub ich wartości są nieprawidłowe. Te żądania mają zwykle 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żesz używać tego tokena do wywoływania interfejsów API Google w imieniu danego konta użytkownika, jeśli przyznano uprawnienia dostępu wymagane przez interfejs API. Aby to zrobić, dodaj token dostępu do żądania do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka HTTP Authorization Bearer. Jeśli to możliwe, zalecamy użycie nagłówka HTTP, ponieważ ciągi znaków zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków do konfigurowania wywołań interfejsów API Google możesz użyć biblioteki klienta (np. podczas wywołania interfejsu Drive API).

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

Przykłady żądań HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) za pomocą nagłówka HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz podać 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 za pomocą parametru ciągu zapytania access_token:

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

curl przykładu

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

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

Możesz też użyć 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 wygasają i stają się nieprawidłowymi danymi logowania w przypadku powiązanego żądania interfejsu API. Jeśli poprosisz o dostęp offline do zakresów powiązanych z tokenem, możesz odświeżyć token dostępu bez wyświetlania użytkownikowi prośby o pozwolenie (także wtedy, gdy użytkownika nie ma w pobliżu).

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:

Ten 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&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Dopóki użytkownik nie cofnie przyznanego aplikacji dostępu, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Ten 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 wydawanych tokenów odświeżania jest ograniczona. Jeden limit dotyczy kombinacji klient/użytkownik, a drugi – wszystkich klientów. Tokeny odświeżania należy zapisać w długoterminowym magazynie danych i nadal z nich korzystać, dopóki są ważne. Jeśli aplikacja wysyła zbyt dużo żądań dotyczących 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 aplikacji. Użytkownik może cofnąć dostęp, otwierając Ustawienia konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu strony lub aplikacji do Twojego konta w dokumentacji pomocy Strony internetowe i aplikacje innych firm z dostępem do Twojego konta.

Aplikacja może też automatycznie cofnąć przyznany dostęp. Automatyczne odwoływanie jest ważne w przypadkach, gdy użytkownik zrezygnuje z subskrypcji, usunie aplikację lub zasoby interfejsu API wymagane przez aplikację ulegną znacznym zmianom. Innymi słowy, część procesu usuwania może obejmować żądanie interfejsu API, aby usunąć uprawnienia wcześniej przyznane aplikacji.

Aby programowo unieważnić token, aplikacja wysyła żądanie do interfejsu https://oauth2.googleapis.com/revoke, dołączając token jako parametr:

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

Token może być tokenem dostępu lub tokenem odświeżania. Jeśli token jest tokenem dostępu i ma odpowiadający mu token odświeżania, token odświeżania zostanie również cofnięty.

Jeśli odwołanie zostało przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędów zwracany jest kod stanu HTTP 400 oraz kod błędu.

Dozwolone zakresy

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