OAuth 2.0 na potrzeby aplikacji mobilnych i komputerowych

Z tego dokumentu dowiesz się, jak aplikacje instalowane na urządzeniach takich jak telefony, tablety i korzystają z punktów końcowych OAuth 2.0 Google do autoryzowania dostępu interfejsów API Google.

OAuth 2.0 pozwala użytkownikom udostępniać określone dane aplikacji przy zachowaniu nazw użytkowników, haseł i innych informacji. Na przykład aplikacja może używać protokołu OAuth 2.0, aby uzyskiwać uprawnienia na przechowywanie plików na Dysku Google przez użytkowników.

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

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

Alternatywy

W przypadku aplikacji mobilnych możesz używać Logowania przez Google na Android lub iOS: Logowanie przez Google biblioteki klienta obsługują uwierzytelnianie i autoryzację użytkownika, a przy tym mogą być prostsze niż omówiony tutaj protokół niższego poziomu.

Aplikacje działające na urządzeniach, które nie obsługują przeglądarki systemowej lub które mają ograniczoną funkcjonalność wprowadzania danych takich jak telewizory, konsole do gier, kamery czy drukarki, Protokół OAuth 2.0 na telewizory Urządzenia lub logowanie się na telewizorach i niektórych urządzeniach wejściowych.

Biblioteki i przykłady

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

• Biblioteka AppAuth na Androida
• Biblioteka AppAuth na iOS
• Protokół OAuth w aplikacjach: Windows Sample

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 funkcji 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 zawiera listę wszystkich dostępnych interfejsów API pogrupowanych według usługi rodzina i popularność. Jeśli interfejsu API, który chcesz włączyć, nie ma na liście, użyj wyszukiwania, aby znajdź go lub kliknij Wyświetl wszystkie w rodzinie usług, 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 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 opisujemy, jak utworzysz dane logowania dla swojego projektu. Dzięki temu aplikacje mogą uzyskiwać dostęp do interfejsów API za pomocą danych logowania włączone 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 stosowane przez obsługiwanych przez serwer autoryzacji. Wybierz typ klienta zalecany dla Twojej aplikacji, nadaj mu nazwę klienta OAuth i ustaw pozostałe pola w formularzu jako odpowiednie.

Określanie zakresów dostępu

Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych zasobów. co pozwala użytkownikom kontrolować zakres dostępu przyznawany do aplikacji. Dlatego też może być odwrotną zależnością między liczbą żądanych zakresów a prawdopodobieństwem w celu uzyskania zgody użytkownika.

Przed rozpoczęciem wdrażania autoryzacji OAuth 2.0 zalecamy określenie zakresów do których aplikacja potrzebuje uprawnień dostępu.

Dokument Zakresy interfejsu API OAuth 2.0 zawiera pełne 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

Poniższe kroki pokazują, w jaki sposób Twoja aplikacja współpracuje z serwerem Google OAuth 2.0 w celu zgody użytkownika na wykonanie żądania do interfejsu API w jego imieniu. Aplikacja musi zawierać te uzyskać zgodę użytkownika przed wykonaniem żądania do interfejsu API Google, które wymaga autoryzacji użytkownika.

Krok 1. Wygeneruj weryfikator kodu i test zabezpieczający

Google obsługuje dokument potwierdzający klucz do wymiany kodu protokół PKCE (PKCE), który zwiększa bezpieczeństwo instalacji instalowanej aplikacji. W przypadku każdego typu kampanii tworzony jest unikalny weryfikator kodu. żądania autoryzacji i jego przekształcona wartość, „code_challenge”, są wysyłane do funkcji serwera autoryzacji, aby uzyskać kod autoryzacji.

Tworzenie weryfikatora kodu

code_verifier to kryptograficzny ciąg losowy o wysokiej entropii wykorzystujący niezarezerwowane wartości znaki [A–Z] / [a–z] / [0–9] / „-” / . / „_” / „~”; minimalna długość 43 znaków o maksymalnej długości 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 następujące parametry ciągu zapytania w przypadku instalacji aplikacje:

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 jako opcjonalny parametr state. Każdy URL zawiera podziały wierszy i spacje dla i czytelność.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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=email%20profile&
 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. W tym miejscu Google wyświetla okno z prośbą o zgodę, w którym wyświetla się nazwa aplikacji i interfejs API Google usług, do których żąda dostępu za pomocą danych uwierzytelniających użytkownika podsumowanie zakresów dostępu, jakie należy przyznać. użytkownik może wyrazić zgodę na przyznanie dostępu do co najmniej jednego zakresu żądanego przez aplikację lub odrzucić tę prośbę.

Na tym etapie aplikacja nie musi nic robić, ponieważ czeka na odpowiedź Serwer Google OAuth 2.0 wskazujący, czy przyznano dostęp. Odpowiedź ta została wyjaśniona tutaj: w następujący sposób.

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacyjną, zależy od schemat URI przekierowania, którego używa. Bez względu na schemat odpowiedź będzie zawierać kod autoryzacji (code) lub błąd (error). Na przykład error=access_denied oznacza, że użytkownik odrzucił prośbę.

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

Krok 5. Kod autoryzacji Exchange w celu odświeżenia i dostępu tokeny

Aby wymienić kod autoryzacji na token dostępu, wywołaj metodę 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

Google w odpowiedzi na to żądanie zwraca obiekt JSON z dostępem krótkotrwałym. token 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/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Wywoływanie interfejsów API Google

Gdy aplikacja uzyska token dostępu, możesz go używać do wywoływania API w imieniu danego konta użytkownika, jeśli zostały przyznane zakresy dostępu wymagane przez interfejs API. Aby to zrobić, dołącz token dostępu w żądaniu wysyłanym do interfejsu API przez uwzględnienie zapytania access_token; lub wartość nagłówka HTTP Authorization Bearer. Jeśli to możliwe, preferowany jest nagłówek HTTP, ponieważ ciągi zapytań są zwykle widoczne w dziennikach serwera. Najwięcej można użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (na przykład wywołaniem interfejsu Drive Files API).

Wszystkie interfejsy API Google możesz wypróbować i przejrzeć ich zakresy na stronie OAuth 2.0 Playground.

Przykłady żądań HTTP GET

Wywołanie funkcji drive.files (interfejs Drive Files API) korzystający z protokołu HTTP Authorization: Bearer nagłówek 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ą interfejsu access_token parametr ciągu zapytania:

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

curl przykładu

Możesz je przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład wykorzystujący opcję nagłówka HTTP (preferowane):

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łowymi danymi logowania dla powiązanego żądania do interfejsu API. Ty może odświeżać token dostępu bez pytania użytkownika o zgodę (także wtedy, gdy nie występuje), jeśli została wysłana prośba o dostęp offline do zakresów powiązanych z tokenem.

Aby odświeżyć token dostępu, aplikacja wysyła żądanie POST HTTPS do serwera autoryzacji Google (https://oauth2.googleapis.com/token), który zawiera następujące 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

Dopóki użytkownik nie unieważni dostępu przyznanego aplikacji, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Fragment kodu poniżej zawiera odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Pamiętaj, że liczba przyznanych tokenów odświeżania jest ograniczona. jeden limit na kombinacja klient/użytkownik oraz inna kombinacja na użytkownika w przypadku wszystkich klientów. Należy zapisać tokeny odświeżania do przechowywania długoterminowego i używać ich, dopóki są ważne. Jeśli Twoja aplikacja żąda zbyt wielu tokenów odświeżania, mogą wystąpić te limity. W takim przypadku starsze tokeny odświeżania przestanie 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 odwiedzając stronę Ustawienia konta. Zobacz Usuń sekcji dostępu do witryny lub aplikacji na stronie Witryny innych firm aplikacje, które mają dostęp do Twojego konta dokumentu pomocy, aby dowiedzieć się więcej.

Aplikacja może też automatycznie anulować przyznany dostęp. Automatyczne unieważnienie jest ważne wtedy, gdy użytkownik anuluje subskrypcję, usuwa aplikacji lub zasoby API wymagane przez aplikację znacznie się zmieniły. Innymi słowy, może obejmować żądanie do interfejsu API mające na celu zapewnienie, że uprawnienia danych aplikacji są usuwane.

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}

Tokenem może być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma parametr 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. z kodem błędu.

Dalsza lektura

Sprawdzona metoda dotycząca IETF OAuth 2.0 dla Aplikacje natywne są oparte na wielu sprawdzonych metodach opisanych w tym artykule.