Ten dokument wyjaśnia, jak wdrożyć autoryzację OAuth 2.0 do korzystania z interfejsów Google API za pomocą aplikacji działających na urządzeniach takich jak telewizory, konsole do gier i drukarki. A konkretnie ta metoda jest przeznaczona dla urządzeń, które nie mają dostępu do przeglądarki lub których funkcje wprowadzania są ograniczone.
Protokół OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji, a jednocześnie chroni ich nazwy użytkowników, hasła i inne informacje. Na przykład aplikacja telewizyjna może używać protokołu OAuth 2.0 do uzyskania uprawnień do wyboru pliku zapisanego na Dysku Google.
Aplikacje, które używają tego przepływu, są rozprowadzane na poszczególne urządzenia, dlatego zakłada się, że nie mogą one przechowywać obiektów tajnych. Mają dostęp do interfejsów API Google, gdy użytkownik jest obecny w aplikacji lub gdy działa w tle.
Alternatywy
Jeśli piszesz aplikację na platformę, taką jak Android, iOS, macOS, Linux lub Windows (w tym platformę Universal Windows Platform), która ma dostęp do przeglądarki i daje pełne możliwości wprowadzania tekstu, użyj procesu OAuth 2.0 w przypadku aplikacji mobilnych i stacjonarnych. Należy z niego skorzystać, nawet jeśli aplikacja jest narzędziem wiersza poleceń bez interfejsu graficznego).
Jeśli chcesz tylko logować się przy użyciu kont Google i używać tokena tożsamości JWT do uzyskiwania podstawowych informacji o profilu użytkownika, przeczytaj artykuł dotyczący logowania 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 interfejsu API, który chcesz włączyć, nie ma na liście, użyj wyszukiwarki, aby go znaleźć, lub kliknij Wyświetl wszystkie 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 logowania
Każda aplikacja, która używa OAuth 2.0 do korzystania z interfejsów API Google, musi mieć dane uwierzytelniające, które identyfikują ją na serwerze OAuth 2.0 Google. Poniżej znajdziesz instrukcje tworzenia danych logowania w Twoim projekcie. Twoje aplikacje mogą następnie używać danych logowania do uzyskiwania dostępu 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 z ograniczonym dostępem.
- Nazwij klienta OAuth 2.0 i kliknij Utwórz.
Określ zakresy dostępu
Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, jednocześnie umożliwiając użytkownikom kontrolę nad poziomem dostępu, który przyznają aplikacji. W związku z tym może wystąpić 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 aplikacja będzie potrzebować dostępu.
Zobacz listę Dozwolonych zakresów dla zainstalowanych aplikacji lub urządzeń.
Uzyskiwanie tokenów dostępu OAuth 2.0
Mimo że aplikacja działa na urządzeniu z ograniczonymi możliwościami wprowadzania danych, użytkownicy muszą mieć oddzielny dostęp do urządzenia z dodatkowymi możliwościami wprowadzania danych, aby ukończyć proces autoryzacji. Proces przebiega w następujący sposób:
- Aplikacja wysyła żądanie do serwera autoryzacji Google, który identyfikuje zakresy, do których aplikacja będzie prosić o dostęp.
- W odpowiedzi wysyła on kilka informacji używanych w kolejnych krokach, takich jak kod urządzenia i kod użytkownika.
- Wyświetlasz informacje, które użytkownik może wpisać na innym urządzeniu w celu autoryzacji aplikacji.
- Aplikacja rozpocznie odpytywanie serwera autoryzacji Google, aby określić, czy użytkownik autoryzował aplikację.
- Użytkownik przełącza się na urządzenie z bogatszymi możliwościami wprowadzania tekstu, uruchamia przeglądarkę internetową, otwiera URL wyświetlany w kroku 3 i wpisuje kod wyświetlany także 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 Twojej aplikacji, odpowiedź nie będzie zawierać tokenów).
Poniższa ilustracja przedstawia ten proces:

Szczegółowo opisujemy to w kolejnych sekcjach. Biorąc pod uwagę zakres funkcji i środowiska wykonawczych, z których korzystają urządzenia, w przykładach przedstawionych w tym dokumencie użyto narzędzia wiersza poleceń curl
. 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 wysyła żądanie POST HTTP do serwera autoryzacji Google (https://oauth2.googleapis.com/device/code
), który identyfikuje aplikację oraz zakresy dostępu, do których aplikacja ma uzyskiwać dostęp w imieniu użytkownika.
Ten adres URL możesz pobrać z dokumentu Discovery, używając wartości metadanych device_authorization_endpoint
. Uwzględnij te parametry żądania HTTP:
Parametry | |
---|---|
client_id |
Wymagane
Identyfikator klienta aplikacji. Tę wartość możesz znaleźć w API Console Credentials page. |
scope |
Wymagane
Lista rozdzielonych spacjami zakresów określających zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Wartości te informują ekran zgody, który Google wyświetla użytkownikowi. Zobacz listę Dozwolonych zakresów dla zainstalowanych aplikacji lub urządzeń. Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, jednocześnie umożliwiając użytkownikom kontrolę nad poziomem dostępu, który przyznają aplikacji. Występuje więc odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika. |
Przykłady
Ten 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=email%20profile
Ten przykład pokazuje polecenie curl
do wysłania tego samego żądania:
curl -d "client_id=client_id&scope=email%20profile" \ https://oauth2.googleapis.com/device/code
Krok 2. Przetwórz odpowiedź serwera autoryzacji
Serwer autoryzacji zwraca jedną z tych odpowiedzi:
Odpowiedź powodzenia
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 jednoznacznie przez Google do identyfikowania urządzenia, na którym jest uruchamiana aplikacja żądająca autoryzacji. Użytkownik autoryzuje to urządzenie na innym urządzeniu o bogatszych możliwościach wprowadzania danych. Użytkownik może na przykład autoryzować aplikację działającą na telewizorze, korzystając z laptopa lub telefonu komórkowego. W tym przypadku device_code określa telewizor.
Kod pozwala urządzeniu bezpiecznie uruchamiać aplikację i decydować, czy użytkownik przyznał do niego dostęp, czy go odmówił. |
expires_in |
Czas ważności (w sekundach) właściwości device_code i user_code . Jeśli w tym czasie użytkownik nie dokończy procesu autoryzacji, a Twoje urządzenie nie będzie mogło przeprowadzić ankiety w celu pobrania informacji o jego decyzji, konieczne może być ponowne uruchomienie tego procesu od kroku 1. |
interval |
Czas oczekiwania urządzenia (w sekundach) między żądaniami odpytywania. Jeśli np. wartość to 5 , Twoje urządzenie powinno wysyłać żądanie odpytywania do serwera autoryzacji Google co 5 sekund. Więcej informacji znajdziesz w kroku 3. |
user_code |
Wielkość liter ma znaczenie – w przypadku Google aplikacja określa zakresy, do których aplikacja chce uzyskać dostęp. Twój interfejs poinformuje użytkownika, aby wpisał tę wartość na osobnym urządzeniu z bardziej rozbudowanymi możliwościami wpisywania danych. Następnie Google używa tej wartości do wyświetlania poprawnego zestawu zakresów, gdy prosi użytkownika o przyznanie dostępu do aplikacji. |
verification_url |
Adres URL, z którego użytkownik musi korzystać na innym urządzeniu, aby wpisać user_code i przyznać lub odrzucić dostęp do aplikacji. Ta wartość będzie też wyświetlana w interfejsie użytkownika. |
Ten 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 dla odpowiedzi
Jeśli żądania dotyczące kodu urządzenia przekroczyły limit powiązany z Twoim identyfikatorem klienta, otrzymasz odpowiedź 403 z tym błędem:
{ "error_code": "rate_limit_exceeded" }
W takim przypadku należy zastosować strategię ponowienia, aby ograniczyć częstotliwość żądań.
Krok 3. Wyświetl kod użytkownika
Wyświetlaj dane verification_url
i user_code
uzyskane w kroku 2. Obie wartości mogą zawierać dowolne możliwe do wydrukowania znaki z zestawu US-ASCII. Treści, które pokazujesz użytkownikowi, powinny poprosić go o wejście na stronę verification_url
na osobnym urządzeniu i wpisanie user_code
.
Zaprojektuj interfejs użytkownika z uwzględnieniem tych reguł:
user_code
user_code
musi być wyświetlany w polu, który obsługuje 15 znaków o rozmiarze „W”. Innymi słowy, jeśli możesz wyświetlać kodWWWWWWWWWWWWWWW
prawidłowo, Twój interfejs jest prawidłowy i zalecamy użycie tej wartości ciągu podczas testowania sposobu wyświetlaniauser_code
w interfejsie.- W pliku
user_code
wielkość liter ma znaczenie, więc nie należy go w żaden sposób zmieniać, na przykład zmieniać wielkości liter ani używać innych znaków formatowania.
verification_url
- Przestrzeń, w której wyświetla się
verification_url
, musi być na tyle szeroka, aby można było w nim używać ciągu znaków o długości 40 znaków. - Nie należy w żaden sposób modyfikować obiektu
verification_url
, z wyjątkiem opcjonalnego usunięcia schematu wyświetlania. Jeśli chcesz usunąć schemat z adresu URL (np.https://
) z powodu wyświetlania, upewnij się, że aplikacja może obsługiwać zarówno wersjehttp
, jak ihttps
.
- Przestrzeń, w której wyświetla się
Krok 4. Skonsultuj się z serwerem autoryzacji Google
Ponieważ użytkownik użyje innego urządzenia do przejścia do aplikacji verification_url
i przyznania lub odrzucenia dostępu, urządzenie wysyłające prośbę nie zostanie automatycznie powiadomione, gdy użytkownik odpowie na prośbę o dostęp. Z tego powodu urządzenie żądające musi sprawdzić dane na serwerze autoryzacji Google, aby określić, kiedy użytkownik odpowiedział na żądanie.
Urządzenie wysyłające żądanie powinno nadal wysyłać żądania odpytywania do momentu otrzymania odpowiedzi informującej, że użytkownik odpowiedział na prośbę o dostęp lub do momentu wygaśnięcia device_code
i user_code
uzyskanych w
kroku 2. Wartość interval
zwrócona w kroku 2 określa czas oczekiwania między żądaniami w sekundach.
URL punktu końcowego do ankiety to https://oauth2.googleapis.com/token
. Żądanie dotyczące ankiety zawiera te parametry:
Parametry | |
---|---|
client_id |
Identyfikator klienta aplikacji. Tę wartość możesz znaleźć w API Console Credentials page. |
client_secret |
Tajny klucz klienta dla podanego client_id . Tę wartość możesz znaleźć w API Console
Credentials 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 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
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
Poniższa ilustracja przedstawia stronę podobną do tej, którą użytkownicy widzą po kliknięciu 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 ankiet
Serwer autoryzacji Google odpowiada na każde żądanie odpytywania za pomocą jednej 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 API Google w imieniu użytkownika. Właściwość scope
w odpowiedzi określa interfejsy API, do których urządzenie ma dostęp.
W tym przypadku odpowiedź interfejsu API zawiera te pola:
Pola | |
---|---|
access_token |
Token, który wysyłasz przez aplikację, aby autoryzować żądanie do interfejsu API Google. |
expires_in |
Pozostały okres dostępu do tokena dostępu (w sekundach). |
refresh_token |
Token, którego możesz użyć do uzyskania nowego tokena dostępu. Tokeny odświeżania są ważne do momentu anulowania dostępu użytkownika. Pamiętaj, że tokeny odświeżania są zawsze zwracane w przypadku urządzeń. |
scope |
Zakresy dostępu przyznawane przez access_token mają postać listy ciągów znaków rozdzielanych spacjami, w których jest rozróżniana wielkość liter. |
token_type |
Typ zwróconego tokena. W tej chwili wartość tego pola jest zawsze ustawiona na Bearer . |
Ten 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 są ograniczone czasowo. 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 zapisać token odświeżania do późniejszego użycia.
Odmowa dostępu
Jeśli użytkownik nie wyrazi zgody na dostęp do urządzenia, odpowiedź serwera zawiera kod stanu odpowiedzi 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ł 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 zbyt często wysyła żądania odpytywania, serwer zwraca kod stanu odpowiedzi 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 dotyczącym odpytywania brakuje wymaganych parametrów lub ma ona nieprawidłową wartość. Żądania te mają zwykle kod stanu odpowiedzi 400
(Bad Request
) lub 401
(Unauthorized
). Błędy te obejmują:
Błąd | Kod stanu HTTP | Opis |
---|---|---|
admin_policy_enforced |
400 |
Z powodu zasad określonych przez administratora Google Workspace konto Google nie może autoryzować co najmniej 1 zakresu, o który prosisz. Zapoznaj się z artykułem pomocy dla administratorów Google Workspace w artykule Kontrola nad tym, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace. Znajdziesz w nim więcej informacji o tym, jak administrator może ograniczyć dostęp do zakresów, dopóki dostęp do identyfikatora klienta OAuth nie zostanie jawnie przyznany. |
invalid_client |
401 |
Nie znaleziono klienta OAuth. Ten błąd występuje na przykład wtedy, gdy wartość parametru Typ klienta OAuth jest nieprawidłowy. Sprawdź, czy typ aplikacji dla identyfikatora klienta jest ustawiony na Telewizory i urządzenia z ograniczonym dostępem. |
invalid_grant |
400 |
Wartość parametru code jest nieprawidłowa, została już zgłoszona lub nie można jej przeanalizować. |
unsupported_grant_type |
400 |
Wartość parametru grant_type jest nieprawidłowa. |
org_internal |
403 |
Identyfikator klienta OAuth w żądaniu jest częścią projektu ograniczającego dostęp do kont Google w określonej organizacji Google Cloud. Potwierdź konfigurację typu użytkownika aplikacji OAuth. |
Wywoływanie interfejsów API Google
Gdy aplikacja otrzyma token dostępu, możesz go używać do wywoływania interfejsu Google API w imieniu danego konta użytkownika, jeśli zakresy dostępu wymagane przez ten interfejs API zostały przyznane. W tym celu umieść w żądaniu żądanie do interfejsu API token dostępu, podając w zapytaniu parametr access_token
lub wartość nagłówka HTTP Authorization
Bearer
. W miarę możliwości zalecamy używanie nagłówka HTTP, ponieważ ciągi zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków możesz użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (np. podczas wywoływania interfejsu Drive Files API).
Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w Play 2.0 Playground.
Przykłady HTTP GET
Wywołanie punktu końcowego
drive.files
(interfejsu Drive Files API) przy użyciu nagłówka 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 uwierzytelnionego użytkownika używającego 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 użycia opcji nagłówka HTTP (zalecane):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Możesz też użyć opcji 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 dane logowania dla powiązanego żądania interfejsu API. Jeśli prośba o dostęp offline do zakresów powiązanych z tokenem została wysłana, możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (także wtedy, gdy go nie ma).
Aby odświeżyć token dostępu, aplikacja wysyła żądanie HTTPS POST
do serwera autoryzacji Google (https://oauth2.googleapis.com/token
), który zawiera te parametry:
Pola | |
---|---|
client_id |
Identyfikator klienta uzyskany od: API Console. |
client_secret |
Tajny klucz klienta uzyskany z API Console. |
grant_type |
Zgodnie z definicją podaną 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 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 unieważni dostępu przyznanego aplikacji, serwer tokenów zwróci 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" }
Istnieją limity liczby tokenów odświeżania: jeden limit dla każdej kombinacji klienta i użytkownika i jeden dla każdego klienta. Tokeny odświeżania należy zapisywać w pamięci długoterminowej i używać ich tak długo, jak długo są ważne. Jeśli aplikacja poprosi o zbyt wiele tokenów odświeżania, może dojść do 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 odwołać dostęp do aplikacji. Użytkownik może cofnąć dostęp, korzystając z ustawień konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu witryn lub aplikacji do stron i aplikacji innych firm z dostępem do Twojego konta.
Aplikacja może też automatycznie anulować przyznany jej dostęp. Automatyczne unieważnienie jest ważne wtedy, gdy użytkownik anuluje subskrypcję, usunie aplikację lub zmienią się zasoby interfejsu API wymagane przez aplikację. Inaczej mówiąc, część procesu usuwania może obejmować żądanie do interfejsu API, aby zapewnić uprawnienia przyznane wcześniej aplikacji.
Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke
i zawiera 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, zostanie on też unieważniony.
Jeśli odwołanie zostało przetworzone, kod stanu HTTP odpowiedzi będzie miał wartość 200
. W przypadku warunków błędu zwracany jest kod stanu HTTP 400
wraz z kodem błędu.
Dozwolone zakresy
Procedura OAuth 2.0 dla urządzeń jest obsługiwana tylko w przypadku tych zakresów:
OpenID Connect, Logowanie przez Google
email
openid
profile
Drive API
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.readonly