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:
- Open the API Library w: Google API Console.
- If prompted, select a project, or create a new one.
- 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.
- Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
- If prompted, enable billing.
- 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.
- Go to the Credentials page.
- Kliknij Utwórz dane logowania > identyfikator klienta OAuth.
- Wybierz typ aplikacji Telewizory i urządzenia wejściowe z ograniczonym dostępem.
- 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:
- Aplikacja wysyła żądanie do serwera autoryzacji Google i wskazuje zakresy, do których aplikacja będzie prosić o dostęp.
- W odpowiedzi serwer przesyła kilka informacji wykorzystywanych w kolejnych krokach, np. kod urządzenia i kod użytkownika.
- Możesz wyświetlać informacje, które użytkownik może wpisać na innym urządzeniu, aby autoryzować swoją aplikację.
- Twoja aplikacja rozpoczyna odpytywanie serwera autoryzacji Google i określa, czy użytkownik autoryzował Twoją aplikację.
- 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.
- 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:

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ć kodWWWWWWWWWWWWWWW
, Twój interfejs użytkownika jest prawidłowy i zalecamy użycie tej wartości ciągu podczas testowania sposobu wyświetlaniauser_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.
- Element
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 wariantyhttp
, jak ihttps
.
- Przestrzeń, w której wyświetla się
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:

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

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