OAuth 2.0 na potrzeby aplikacji mobilnych i komputerowych

Ten dokument wyjaśnia, w jaki sposób aplikacje zainstalowane na urządzeniach takich jak telefony, tablety i komputery używają punktów końcowych OAuth 2.0 Google do autoryzowania dostępu do interfejsu YouTube Data API.

OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy jednoczesnym zachowaniu prywatności nazw użytkowników, haseł i innych informacji. Aplikacja może na przykład korzystać z protokołu OAuth 2.0, aby uzyskać pozwolenie na przesyłanie filmów na kanał YouTube użytkownika.

Zainstalowane aplikacje są rozpowszechniane na poszczególnych urządzeniach. Zakładamy, że nie mogą zachowywać tajemnic. Mogą uzyskiwać dostęp do interfejsów API Google, gdy użytkownik jest w aplikacji lub gdy aplikacja działa w tle.

Ten proces autoryzacji jest podobny do procesu używanego w przypadku aplikacji serwerów WWW. Główna różnica polega na tym, że zainstalowane aplikacje muszą otwierać przeglądarkę systemową i podać identyfikator URI przekierowania lokalnego, aby obsługiwać odpowiedzi z serwera autoryzacji Google.

Alternatywy

W przypadku aplikacji mobilnych wolisz używać Logowania przez Google na Androidzie lub iOS. Biblioteki klienta logowania przez Google obsługują uwierzytelnianie i autoryzację użytkowników, a ich wdrożenie może być łatwiejsze niż opisany tutaj protokół niższego poziomu.

Informacje o aplikacjach działających na urządzeniach, które nie obsługują przeglądarki systemowej lub które mają ograniczone możliwości wprowadzania (np. telewizory, konsole do gier, kamery czy drukarki), znajdziesz w artykule o protokole OAuth 2.0 na telewizory i urządzenia lub Logowanie się na telewizorach i ograniczonych urządzeniach wejściowych.

Biblioteki i przykłady

Zalecamy skorzystanie z tych bibliotek i przykładów, które ułatwiają wdrożenie przepływu OAuth 2.0 opisanego w tym dokumencie:

• Biblioteka AppAuth na Androida
• Biblioteka AppAuth na iOS
• Protokół OAuth w aplikacjach: przykłady w systemie Windows

Wymagania wstępne

Włączanie interfejsów API w projekcie

Każda aplikacja, która wywołuje interfejsy API Google, musi je włączyć 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 możesz znaleźć i włączyć interfejs YouTube Data API. Znajdź i włącz wszystkie inne interfejsy API, których będzie używać Twoja aplikacja.

Tworzenie danych uwierzytelniających

Każda aplikacja korzystająca z protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google musi mieć dane uwierzytelniające, które identyfikują aplikację na serwerze Google OAuth 2.0. Poniżej znajdziesz instrukcje tworzenia danych logowania dla projektu. Aplikacje będą mogły 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 dane logowania > Identyfikator klienta OAuth.
3. W poniższych sekcjach opisano typy klientów i metody przekierowania obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nadaj mu nazwę i odpowiednio ustaw pozostałe pola w formularzu.

Określanie zakresów dostępu

Zakresy pozwalają aplikacji prosić o dostęp tylko do zasobów, których potrzebuje, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu, który przyznają aplikacji. Dlatego może występować 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ć uprawnień dostępu.

Interfejs YouTube Data API w wersji 3 korzysta z tych zakresów:

Dokument Zakresy interfejsu API OAuth 2.0 zawiera pełną listę zakresów, których możesz używać do uzyskiwania dostępu do interfejsów API Google.

Uzyskiwanie tokenów dostępu OAuth 2.0

Z podanych niżej instrukcji dowiesz się, jak Twoja aplikacja wchodzi w interakcję z serwerem Google OAuth 2.0, aby uzyskać zgodę użytkownika na wykonanie żądania do interfejsu API w jego imieniu. Twoja aplikacja musi uzyskać tę zgodę, zanim będzie mogła wykonać żądanie do interfejsu API Google wymagające autoryzacji użytkownika.

Krok 1. Wygeneruj weryfikator kodu i test zabezpieczający

Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo przepływu instalowanej aplikacji. Dla każdego żądania autoryzacji tworzony jest unikalny weryfikator kodu, a jego przekształcona wartość o nazwie „code_challenge” jest wysyłana do serwera autoryzacji w celu uzyskania kodu autoryzacji.

Tworzenie weryfikatora kodu

code_verifier to losowy ciąg kryptograficzny o wysokiej entropii, w którym niezastrzeżone znaki to [A–Z] / [a–z] / [0–9] / „-” / „.” / „_” / „~”. Jego minimalna długość to 43 znaki i maksymalna długość 128 znaków.

Weryfikator kodu powinien mieć wystarczającą entropię, aby odgadnięcie wartości było niemożliwe.

Utwórz zadanie związane z kodem

Obsługiwane są 2 metody tworzenia zadania zabezpieczającego kod.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Krok 2. Wyślij żądanie na serwer OAuth 2.0 Google

Aby uzyskać autoryzację użytkownika, wyślij żądanie do serwera autoryzacji Google na adres https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy obsługuje wyszukiwanie aktywnych sesji, uwierzytelnia użytkownika i uzyskuje jego zgodę. Punkt końcowy jest dostępny tylko przez SSL i odrzuca połączenia HTTP (bez SSL).

Serwer autoryzacji obsługuje te parametry ciągu zapytania w przypadku zainstalowanych aplikacji:

Przykładowe autoryzacyjne adresy URL

Poniższe karty zawierają przykładowe adresy URL autoryzacji dla różnych opcji identyfikatora URI przekierowania.

Adresy URL są identyczne z wyjątkiem wartości parametru redirect_uri. Adresy URL zawierają też wymagane parametry response_type i client_id, a także opcjonalny parametr state. Każdy adres URL zawiera podziały wierszy i spacje, aby zapewnić czytelność.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Krok 3. Google prosi użytkownika o zgodę

Na tym etapie użytkownik decyduje, czy przyznać aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody, w którym widoczna jest nazwa Twojej aplikacji i usług interfejsów API Google, do których aplikacja prosi o dostęp (wraz z danymi uwierzytelniającymi użytkownika) oraz podsumowanie zakresów dostępu. Użytkownik może wtedy wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu żądanego przez aplikację lub odrzucić żądanie.

Na tym etapie Twoja aplikacja nie musi nic robić, ponieważ czeka na odpowiedź z serwera OAuth 2.0 Google wskazującą, czy przyznano dostęp. Odpowiedź na to pytanie zostanie objaśniona w kolejnym kroku.

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacyjną, zależy od używanego w niej schematu identyfikatora URI przekierowania. Niezależnie od schematu odpowiedź będzie zawierać kod autoryzacji (code) lub błąd (error). Na przykład error=access_denied oznacza, że użytkownik odrzucił żądanie.

Jeśli użytkownik przyzna dostęp do Twojej aplikacji, możesz wymienić kod autoryzacji na token dostępu i token odświeżania zgodnie z opisem w następnym kroku.

Krok 5. Kod autoryzacji Exchange dla tokenów odświeżania i dostępu

Aby wymienić kod autoryzacji na token dostępu, wywołaj punkt końcowy https://oauth2.googleapis.com/token i ustaw te parametry:

Oto przykładowy fragment kodu:

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

W odpowiedzi na to żądanie Google zwraca obiekt JSON zawierający token dostępu o ograniczonym czasie ważności i token odświeżania.

Odpowiedź zawiera te pola:

Ten fragment kodu zawiera przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Wywoływanie interfejsów API Google

Gdy aplikacja uzyska token dostępu, możesz za jego pomocą wywoływać interfejs API Google w imieniu danego konta użytkownika, jeśli zostały przyznane zakresy dostępu wymagane przez interfejs API. Aby to zrobić, uwzględnij token dostępu w żądaniu wysyłanym do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka HTTP Bearer Authorization. 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 (na przykład wywołując YouTube Data API).

Pamiętaj, że interfejs YouTube Data API obsługuje konta usługi tylko w przypadku właścicieli treści YouTube, którzy są właścicielami wielu kanałów YouTube, takich jak wytwórnie płytowe i studia filmowe, i zarządzają nimi.

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

Przykłady żądań HTTP GET

Wywołanie punktu końcowego youtube.channels (YouTube Data API) przy użyciu nagłówka HTTP Authorization: Bearer może wyglądać tak. Pamiętaj, że musisz podać własny token dostępu:

GET /youtube/v3/channels?part=snippet&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/channels?access_token=access_token&part=snippet&mine=true

curl przykładu

Możesz je przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład z wykorzystaniem opcji nagłówka HTTP (preferowana):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Możesz też użyć opcji parametru ciągu zapytania:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Odświeżanie tokena dostępu

Tokeny dostępu okresowo tracą ważność i stają się nieprawidłowymi danymi logowania dla powiązanego żądania do interfejsu API. Możesz odświeżyć token dostępu bez pytania użytkownika o uprawnienia (także wtedy, gdy użytkownik nie jest obecny), jeśli poprosisz o dostęp offline do zakresów powiązanych z tokenem.

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

Oto przykładowy fragment kodu:

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

Jeśli użytkownik nie unieważnił dostępu przyznanego 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 w przypadku wszystkich klientów obowiązują limity liczby tokenów odświeżania: jeden limit na kombinację klienta/użytkownika, a drugi na użytkownika w przypadku wszystkich klientów. Tokeny odświeżania należy zapisać w pamięci długoterminowej i używać ich, dopóki są ważne. Jeśli aplikacja żą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 cofnąć dostęp przyznany aplikacji. Użytkownik może anulować dostęp w Ustawieniach konta. Więcej informacji znajdziesz w artykule pomocy Usuwanie dostępu witryny lub aplikacji do Twojego konta.

Aplikacja może też automatycznie anulować przyznany dostęp. Automatyczne anulowanie jest ważne w sytuacjach, gdy użytkownik anuluje subskrypcję, usuwa aplikację lub znacznie zmieniły się zasoby interfejsu API wymagane przez aplikację. Inaczej mówiąc, część procesu usuwania może obejmować żądanie do interfejsu API dające pewność, że uprawnienia przyznane wcześniej aplikacji zostaną usunięte.

Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i uwzględnia token jako parametr:

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

Tokenem może 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 odwołanie zostanie przetworzone, kod stanu HTTP odpowiedzi będzie miał postać 200. W przypadku wystąpienia błędu zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

Dalsza lektura

Sprawdzone metody IETF dotyczące protokołu OAuth 2.0 dla aplikacji natywnych obejmują wiele opisanych tu sprawdzonych metod.