OAuth 2.0 na potrzeby aplikacji mobilnych i komputerowych

Z tego dokumentu dowiesz się, jak aplikacje zainstalowane na urządzeniach takich jak telefony, tablety i komputery używają punktów końcowych OAuth 2.0 Google do autoryzacji dostępu do interfejsów API Google.

OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy jednoczesnym zachowaniu poufności nazw, haseł i innych informacji. Aplikacja może na przykład używać OAuth 2.0, aby uzyskać od użytkowników uprawnienia do przechowywania plików na Dysku Google.

Zainstalowane aplikacje są rozpowszechniane na poszczególne urządzenia i zakłada się, że te aplikacje nie są w stanie chronić tajemnic. Mogą one uzyskiwać dostęp do interfejsów API Google, gdy użytkownik korzysta z aplikacji lub gdy aplikacja działa w tle.

Ten proces autoryzacji jest podobny do tego, który jest używany w aplikacji serwera WWW. Główna różnica polega na tym, że zainstalowane aplikacje muszą otworzyć przeglądarkę systemową i podać lokalny identyfikator URI przekierowania, aby obsłużyć odpowiedzi z serwera autoryzacji Google.

Możliwości

W przypadku aplikacji mobilnych możesz użyć funkcji logowania w Google na Android lub iOS. Biblioteki klienta logowania w Google obsługują uwierzytelnianie i autoryzację użytkownika. Ich wdrożenie może być prostsze niż w przypadku opisanego tutaj protokołu niskiego poziomu.

W przypadku aplikacji działających na urządzeniach, które nie obsługują przeglądarki systemowej lub mają ograniczone możliwości wprowadzania danych (np. telewizory, konsole do gier, kamery czy drukarki), zapoznaj się z artykułami OAuth 2.0 na telewizorach i urządzeniach z ograniczoną możliwością wprowadzania danych lub Logowanie na telewizorach i urządzeniach z ograniczoną możliwością wprowadzania danych.

Biblioteki i próbki

Aby ułatwić Ci implementację opisanego w tym dokumencie procesu OAuth 2.0, zalecamy użycie tych bibliotek i próbek:

• Biblioteka AppAuth for Android
• Biblioteka AppAuth for iOS
• OAuth dla aplikacji: przykłady dla systemu Windows

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. W następnych sekcjach opisujemy typy klientów obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nadaj nazwę klientowi OAuth i właściwie skonfiguruj pozostałe pola formularza.

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.

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.

Pobieranie tokenów dostępu OAuth 2.0

Te czynności pokazują, jak aplikacja wchodzi w interakcję z serwerem OAuth 2.0 Google, aby uzyskać zgodę użytkownika na wykonanie żądania interfejsu API w imieniu tego użytkownika. Aplikacja musi mieć tę zgodę, zanim będzie mogła wykonać żądanie interfejsu Google API, które wymaga autoryzacji użytkownika.

Krok 1. Wygeneruj weryfikator kodu i wyzwanie

Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo procesu instalowania aplikacji. W przypadku każdego żądania autoryzacji tworzony jest unikalny weryfikator kodu, a jego przekształcona wartość, zwana „code_challenge”, jest wysyłana na serwer autoryzacji w celu uzyskania kodu autoryzacji.

Tworzenie weryfikatora kodu

code_verifier to losowy ciąg znaków kryptograficznych o wysokiej entropii, który wykorzystuje niezarezerwowane znaki [A-Z] / [a-z] / [0-9] / „-” / „.” / „_” / „~”, o długości co najmniej 43 znaków i maksymalnie 128 znaków.

Weryfikator kodu powinien mieć wystarczającą ilość entropii, aby uniemożliwić odgadnięcie wartości.

Tworzenie zadania z programowania

Obsługiwane są 2 metody tworzenia kodu weryfikacyjnego.

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

code_challenge = code_verifier

Krok 2. Wyślij żądanie do serwera Google OAuth 2.0

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

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

Przykładowe adresy URL autoryzacji

Na kartach poniżej znajdziesz przykładowe adresy URL autoryzacji dla różnych opcji przekierowania URI.

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 wiersza i spacje w celu ułatwienia czytelności.

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ć Twojej aplikacji wymagany dostęp. Na tym etapie Google wyświetla okno zgody, w którym podaje nazwę aplikacji i usługi interfejsu API Google, do której chce uzyskać dostęp, wraz z danymi autoryzującymi użytkownika oraz podsumowaniem zakresów dostępu. Użytkownik może wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu żądanego przez Twoją aplikację lub odrzucić prośbę.

Na tym etapie aplikacja nie musi nic robić, ponieważ czeka na odpowiedź z serwera OAuth 2.0 Google, która wskazuje, czy przyznano dostęp. Odpowiedź na to pytanie znajdziesz w następnym kroku.

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

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

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

Krok 5. Wymień kod autoryzacji na tokeny 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:

Ten fragment kodu pokazuje przykładowe żądanie:

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 krótkotrwały token dostępu i token odświeżania.

Odpowiedź zawiera te pola:

Ten fragment kodu pokazuje przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Krok 6. Sprawdź, jakie zakresy przyznali użytkownicy

Gdy żądasz dostępu do wielu zakresów naraz, użytkownicy mogą nie przyznać dostępu do wszystkich zakresów, o które prosi Twoja aplikacja. Aplikacja powinna zawsze sprawdzać, jakie zakresy zostały przyznane przez użytkownika, i w przypadku odmowy przyznania zakresu wyłączać odpowiednie funkcje. Więcej informacji znajdziesz w artykule Zarządzanie szczegółowymi uprawnieniami.

Aby sprawdzić, czy użytkownik przyznał aplikacji dostęp do określonego zakresu, sprawdź pole scope w odpowiedzi na żądanie tokena dostępu. Zakresy dostępu przyznawane przez token dostępu w postaci listy ciągów znaków oddzielonych spacjami, w których rozróżniane są wielkość liter.

Na przykład ta przykładowa odpowiedź na żądanie tokena dostępu wskazuje, że użytkownik przyznał Twojej aplikacji uprawnienia do odczytu aktywności na Dysku i do wydarzeń w Kalendarzu:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

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.

Metody przekierowania aplikacji

Chroń swoje aplikacje

Więcej informacji

Wiele sprawdzonych metod opisanych w tym dokumencie zostało podanych w raporcie IETF OAuth 2.0 for Native Apps (Najlepsze metody IETF dotyczące OAuth 2.0 w przypadku aplikacji natywnych).