OAuth 2.0 na potrzeby aplikacji mobilnych i komputerowych

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Z tego dokumentu dowiesz się, jak aplikacje zainstalowane na urządzeniach takich jak telefony, tablety i komputery korzystają z punktów końcowych OAuth 2.0 Google, aby autoryzować dostęp 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 ich Dyskach 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.

Alternatywy

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 na platformie 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 danym projekcie.

1. Go to the Credentials page.
2. Kliknij Utwórz klienta.
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 tych zasobów, których potrzebuje, a także kontrolowanie zakresu dostępu przyznawanego aplikacji przez użytkowników. 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ć zgadnięcie wartości.

Tworzenie wyzwania dotyczącego kodu

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 na potrzeby 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. W tym momencie 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ź od 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

Jeśli żądasz wielu uprawnień (zakresów), użytkownicy mogą nie przyznać Twojej aplikacji dostępu do wszystkich z nich. Aplikacja musi sprawdzić, które zakresy zostały faktycznie przyznane, i odpowiednio zareagować na sytuacje, gdy niektóre uprawnienia zostaną odrzucone (zazwyczaj przez wyłączenie funkcji, które korzystają z tych zakresów).

Są jednak wyjątki. Aplikacje Google Workspace Enterprise z delegowaniem uprawnień na poziomie całej domeny lub aplikacje oznaczone jako Zaufane pomijają ekran zgody na szczegółowe uprawnienia. W przypadku tych aplikacji użytkownicy nie zobaczą szczegółowego ekranu z prośbą o uprawnienia. Zamiast tego Twoja aplikacja otrzyma wszystkie żądane zakresy lub żadne.

Więcej informacji znajdziesz w artykule Zarządzanie szczegółowymi uprawnieniami.

Aby sprawdzić, czy użytkownik przyznał Twojej 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 go używać 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 możesz użyć biblioteki klienta, aby skonfigurować wywołania interfejsów API Google (np. wywołując interfejs 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 przez 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 zwróci 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 Twoja aplikacja wysyła zbyt wiele żądań 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 adresu 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

Dostęp zależny od czasu

Dostęp czasowy umożliwia użytkownikowi przyznanie aplikacji dostępu do jego danych na ograniczony czas, aby wykonać określone działanie. Dostęp ograniczony czasowo jest dostępny w wybranych usługach Google podczas procesu uzyskiwania zgody. Użytkownicy mogą przyznać dostęp na ograniczony czas. Przykładem jest interfejs Data Portability API, który umożliwia jednokrotny transfer danych.

Gdy użytkownik przyzna aplikacji dostęp czasowy, token odświeżania wygaśnie po określonym czasie. Pamiętaj, że w określonych okolicznościach tokeny odświeżania mogą zostać unieważnione wcześniej. Więcej informacji znajdziesz w tych przypadkach. W takich przypadkach pole refresh_token_expires_in zwrócone w odpowiedzi na żądanie exchange dotyczące kodu autoryzacji zawiera czas pozostały do wygaśnięcia tokena odświeżania.

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).