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:

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.
Android
  1. Wybierz typ aplikacji Android.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest widoczna na stronie projektu Credentials page , aby umożliwić identyfikację klienta.
  3. Wpisz nazwę pakietu aplikacji na Androida. Ta wartość jest zdefiniowana w  atrybutcie package elementu <manifest> w pliku manifestu aplikacji.
  4. Wpisz odcisk cyfrowy certyfikatu podpisującego SHA-1 dystrybucji aplikacji.
    • Jeśli Twoja aplikacja korzysta z podpisywania aplikacji przez Google Play, skopiuj odcisk cyfrowy SHA-1 ze strony podpisywania aplikacji w Konsoli Play.
    • Jeśli zarządzasz własnym magazynem kluczy i kluczami podpisowymi, użyj narzędzia keytool dołączonego do Java, aby wydrukować informacje o certyfikacie w formatowalnym dla człowieka formacie. Skopiuj wartość SHA1 w sekcji Certificate fingerprints w danych wyjściowych narzędzia keytool. Więcej informacji znajdziesz w sekcji Uwierzytelnianie klienta w dokumentacji interfejsów API Google na Androida.
  5. (Opcjonalnie) Zweryfikuj własność aplikacji na Androida.
  6. Kliknij Utwórz.
iOS
  1. Wybierz typ aplikacji iOS.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest widoczna na stronie projektu Credentials page , aby umożliwić identyfikację klienta.
  3. Wpisz identyfikator pakietu aplikacji. Identyfikator pakietu to wartość klucza CFBundleIdentifier w pliku zasobu z informacjami o aplikacji (info.plist). Wartość ta jest najczęściej wyświetlana w panelu Ogólne lub w panelu Podpisywanie i możliwości edytora projektu Xcode. Identyfikator pakietu jest też widoczny w sekcji Informacje ogólne na stronie Informacje o aplikacji w usłudze App Store Connect firmy Apple.

    Sprawdź, czy używasz prawidłowego identyfikatora pakietu aplikacji, ponieważ nie będzie można go zmienić, jeśli korzystasz z funkcji Sprawdzanie aplikacji.

  4. (Opcjonalnie)

    Podaj identyfikator aplikacji w sklepie App Store, jeśli została ona opublikowana w sklepie App Store firmy Apple. Identyfikator sklepu to ciąg liczbowy zawarty w każdym adresie URL Apple App Store.

    1. Otwórz aplikację App Store na urządzeniu z iOS lub iPadOS.
    2. Wyszukaj swoją aplikację.
    3. Kliknij przycisk Udostępnij (symbol kwadratu z strzałką skierowaną w górę).
    4. Kliknij Kopiuj link.
    5. Wklej link w edytorze tekstu. Identyfikator App Store to ostatnia część adresu URL.

      Przykład: https://apps.apple.com/app/google/id284815942

  5. (Opcjonalnie)

    Wpisz identyfikator zespołu. Więcej informacji znajdziesz w dokumentacji dotyczącej konta dewelopera Apple w sekcji Znajdź identyfikator zespołu.

    Uwaga: jeśli włączasz Sprawdzanie aplikacji dla klienta, pole Identyfikator zespołu jest wymagane.
  6. (Opcjonalnie)

    Włącz Sprawdzanie aplikacji w przypadku aplikacji na iOS. Gdy włączysz Sprawdzanie aplikacji, usługa App Attest firmy Apple będzie używana do sprawdzania, czy żądania OAuth 2.0 pochodzące z Twojego klienta OAuth są autentyczne i pochodzą z Twojej aplikacji. Pomaga to zmniejszyć ryzyko podszywania się pod aplikację. Więcej informacji o włączaniu Sprawdzania aplikacji w przypadku aplikacji na iOS

  7. Kliknij Utwórz.
UWP
  1. Wybierz typ aplikacji Universal Windows Platform.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest widoczna na stronie projektu Credentials page , aby umożliwić identyfikację klienta.
  3. Wpisz 12-znakowy identyfikator aplikacji w Microsoft Store. Znajdziesz ją w Microsoft Partner Center na stronie Tożsamość aplikacji w sekcji Zarządzanie aplikacjami.
  4. Kliknij Utwórz.

W przypadku aplikacji UWP niestandardowy schemat URI nie może mieć więcej niż 39 znaków.

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.

Metody generowania zadań testu zabezpieczającego
S256 (zalecane) Wyzwanie kodu to skrót SHA256 z kodowaniem Base64URL (bez dopełnienia) weryfikatora kodu.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain Wyzwanie kodu ma taką samą wartość jak wygenerowany powyżej weryfikator kodu.
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:

Parametry
client_id Wymagany

Identyfikator klienta Twojej aplikacji. Znajdziesz ją w sekcji API Console: Credentials page.
redirect_uri Wymagany

Określa sposób, w jaki serwer autoryzacji Google wysyła odpowiedź do Twojej aplikacji. Dostępnych jest kilka opcji przekierowania do zainstalowanych aplikacji. Musisz skonfigurować uprawnienia autoryzacji z uwzględnieniem konkretnej metody przekierowania.

Wartość musi dokładnie pasować do jednego z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API Console Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego adresu URI, pojawi się błąd redirect_uri_mismatch.

Tabela poniżej zawiera odpowiednią wartość parametru redirect_uri dla każdej metody:

Wartości redirect_uri
Niestandardowy schemat identyfikatora URI com.example.app:redirect_uri_path

lub

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app to odwrotna notacja DNS domeny, którą kontrolujesz. Aby schemat niestandardowy był prawidłowy, musi zawierać okres.
  • com.googleusercontent.apps.123 to odwrotna notacja DNS identyfikatora klienta.
  • redirect_uri_path to opcjonalny element ścieżki, np. /oauth2redirect. Pamiętaj, że ścieżka powinna zaczynać się od pojedynczego ukośnika, co różni ją od zwykłych adresów URL HTTP.
Adres IP sprzężenia zwrotnego http://127.0.0.1:port lub http://[::1]:port

Wyszukaj na platformie odpowiedni adres IP pętli zwrotnej i uruchom detektor HTTP na losowym dostępnym porcie. Zastąp port rzeczywistym numerem portu, na którym nasłuchuje aplikacja.

Pamiętaj, że w aplikacjach mobilnych nie obsługujemy już opcji przekierowania adresu IP pętli zwrotnej..
response_type Wymagany

Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji.

W przypadku zainstalowanych aplikacji ustaw wartość parametru na code.
scope Wymagany

Oddzielona spacjami lista zakresów, które identyfikują zasoby, do których aplikacja może uzyskać dostęp w imieniu użytkownika. Te wartości informują o ekranie zgody, który Google wyświetla użytkownikowi.

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. W związku z tym istnieje odwrotna zależność między liczbą żądanych zakresów uprawnień a prawdopodobieństwom uzyskania zgody użytkownika.
code_challenge Zalecane

Określa zakodowany code_verifier, który będzie używany jako wyzwanie po stronie serwera podczas wymiany kodu autoryzacji. Więcej informacji znajdziesz w sekcji wyzwanie dotyczące tworzenia kodu.
code_challenge_method Zalecane

Określa metodę użytą do zakodowania code_verifier, która będzie używana podczas wymiany kodu autoryzacji. Ten parametr musi być używany z parametrem code_challenge opisanym powyżej. Jeśli wartość code_challenge_method nie występuje w żądaniu zawierającym code_challenge, przyjmuje domyślnie wartość plain. Jedynymi obsługiwanymi wartościami tego parametru są S256 i plain.
state Zalecane

Określa dowolną wartość ciągu znaków, której aplikacja używa do zachowania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Serwer zwraca dokładną wartość, którą wysyłasz jako parę name=value w identyfikatorze fragmentu adresu URL (#) redirect_uri, gdy użytkownik wyrazi zgodę na żądanie dostępu aplikacji lub odmówi jego udzielenia.

Parametru tego można używać do różnych celów, np. do kierowania użytkownika do odpowiedniego zasobu w aplikacji, wysyłania identyfikatorów jednorazowych i ograniczania fałszowania żądań między witrynami. Ponieważ wartość redirect_uri można odgadnąć, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia. Jeśli wygenerujesz losowy ciąg znaków lub zakodujesz hasz pliku cookie lub inną wartość, która odzwierciedla stan klienta, możesz dodatkowo sprawdzić odpowiedź, aby upewnić się, że żądanie i odpowiedź pochodzą z tego samego przeglądarki. Zapewnia to ochronę przed atakami takimi jak fałszowanie żądań między witrynami. Przykład utworzenia i potwierdzenia tokena state znajdziesz w dokumentacji OpenID Connect.
login_hint Opcjonalny

Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby przekazać wskazówkę serwerowi uwierzytelniania Google. Serwer używa tego podpowiedzi do uproszczenia procesu logowania, wypełniając wstępnie pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję logowania wielokrotnego.

Ustaw wartość parametru jako adres e-mail lub identyfikator sub, który jest równoważny z identyfikatorem Google użytkownika.

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.

Niestandardowy schemat identyfikatora URI

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

Adres IP pętli zwrotnej

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.

Błędy

Żądania do punktu końcowego autoryzacji OAuth 2.0 Google mogą wyświetlać komunikaty o błędach zamiast oczekiwanych procesów uwierzytelniania i autoryzacji. Poniżej znajdziesz listę typowych kodów błędów i sugerowanych rozwiązań.

admin_policy_enforced

Konto Google nie może autoryzować co najmniej 1 żądanego zakresu uprawnień z powodu zasad administratora Google Workspace. Więcej informacji o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów poufnych i ograniczonych, dopóki nie zostanie wyraźnie przyznany dostęp do Twojego identyfikatora klienta OAuth, znajdziesz w artykule pomocy dla administratorów Google Workspace Control which third-party & internal apps access Google Workspace data.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany w ramach wbudowanego użytkownika-agenta, który jest niedozwolony przez zasady OAuth 2.0 Google.

Android

Deweloperzy aplikacji na Androida mogą zobaczyć ten komunikat o błędzie podczas otwierania żądań autoryzacji w android.webkit.WebView. Deweloperzy powinni zamiast tego używać bibliotek Androida, takich jak Logowanie przez Google na Androida czy AppAuth na Androida od OpenID Foundation.

Deweloperzy mogą napotkać ten błąd, gdy aplikacja na Androida otwiera ogólny link internetowy w osadzonym user-agent i użytkownik przechodzi na punkt końcowy autoryzacji OAuth 2 Google z Twojej witryny. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym obsłudze linków systemu operacyjnego, co obejmuje zarówno obsługę linków aplikacji na Androida, jak i domyślną aplikację przeglądarki. Biblioteka kart niestandardowych Androida jest też obsługiwaną opcją.

iOS

Deweloperzy iOS i macOS mogą napotkać ten błąd podczas otwierania próśb o autoryzację w WKWebView. Deweloperzy powinni zamiast tego używać bibliotek iOS, takich jak Google Sign-In na iOS czy AppAuth na iOS od OpenID Foundation.

Deweloperzy witryn mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otwiera ogólny link internetowy w osadzonym user-agent i użytkownik przechodzi do punktu autoryzacji OAuth 2.0 Google z Twojej witryny. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym obsłudze linków systemu operacyjnego, który obejmuje zarówno obsługę linków uniwersalnych, jak i domyślną aplikację przeglądarki. Biblioteka SFSafariViewController jest też obsługiwaną opcją.
org_internal

Identyfikator klienta OAuth w żądaniu należy do projektu, który ogranicza dostęp do kont Google w określonej organizacji Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w sekcji Typ użytkownika w artykule pomocy Konfigurowanie ekranu zgody OAuth.

invalid_grant

Jeśli używasz weryfikatora kodu i wyzwania, parametr code_callenge jest nieprawidłowy lub go brakuje. Sprawdź, czy parametr code_challenge jest prawidłowo skonfigurowany.

Podczas odświeżania tokena dostępu może się okazać, że token wygasł lub został unieważniony. Użytkownik musi się ponownie uwierzytelnić i wyrazić zgodę na uzyskanie nowych tokenów. Jeśli ten błąd będzie się powtarzał, sprawdź, czy aplikacja jest prawidłowo skonfigurowana i czy używasz w żądaniu prawidłowych tokenów i parametrów. W przeciwnym razie konto użytkownika mogło zostać usunięte lub wyłączone.

redirect_uri_mismatch

Wartość redirect_uri przekazana w żądaniu autoryzacji nie odpowiada autoryzowanemu identyfikatorowi URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania w sekcji Google API Console Credentials page.

Podana wartość redirect_uri może być nieprawidłowa dla typu klienta.

Parametr redirect_uri może odnosić się do przesyłania poza pasmem (OOB) w ramach protokołu OAuth, które zostało wycofane i nie jest już obsługiwane. Aby zaktualizować integrację, zapoznaj się z przewodnikiem po migracji.

invalid_request

Coś poszło nie tak z Twoją prośbą. Może to wynikać z kilku powodów:

  • żądanie jest nieprawidłowo sformatowane;
  • Brak wymaganych parametrów w prośbie
  • Żądanie używa metody autoryzacji, której Google nie obsługuje. Sprawdź, czy integracja OAuth używa zalecanej metody integracji
  • W przypadku adresu URI przekierowania używany jest niestandardowy schemat : jeśli widzisz komunikat o błędzie Niestandardowy schemat URI nie jest obsługiwany w aplikacjach Chrome lub Niestandardowy schemat URI nie jest włączony dla klienta na Androida, oznacza to, że używasz niestandardowego schematu URI, który nie jest obsługiwany w aplikacjach Chrome i domyślnie jest wyłączony na Androidzie. Dowiedz się więcej o niestandardowych schematach URI i ich alternatywach

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:

Pola
client_id Identyfikator klienta uzyskany z  API Console Credentials page.
client_secret Tajny klucz klienta uzyskany z  API Console Credentials page.
code Kod autoryzacji zwrócony w odpowiedzi na początkowe żądanie.
code_verifier Weryfikator kodu utworzony w kroku 1.
grant_type Zgodnie ze specyfikacją OAuth 2.0 wartość tego pola musi wynosić authorization_code.
redirect_uri Jeden z identyfikatorów URI przekierowania podanych w przypadku Twojego projektu w sekcji API Console Credentials page w przypadku danego client_id.

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:

Pola
access_token Token wysyłany przez aplikację w celu autoryzacji żądania interfejsu Google API.
expires_in Pozostały czas ważności tokena dostępu w sekundach.
id_token Uwaga: ta właściwość jest zwracana tylko wtedy, gdy Twoje żądanie zawiera zakres tożsamości, taki jak openid, profile lub email. Wartość to token sieciowy JSON (JWT), który zawiera podpisane cyfrowo informacje o tożsamości użytkownika.
refresh_token Token, którego możesz użyć do uzyskania nowego tokena dostępu. Tokeny odświeżania są ważne do czasu, gdy użytkownik anuluje dostęp. Pamiętaj, że tokeny odświeżania są zawsze zwracane w przypadku zainstalowanych aplikacji.
scope Zakresy dostępu przyznane przez access_token wyrażone jako lista rozróżniających wielkość liter ciągów znaków oddzielonych spacjami.
token_type Typ zwróconego tokena. Obecnie wartość tego pola zawsze wynosiBearer.

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:

Pola
client_id Identyfikator klienta uzyskany z  API Console.
client_secret Tajny klucz klienta uzyskany z  API Console. (client_secret nie dotyczy żądań od klientów zarejestrowanych jako aplikacje na Androida, iOS lub Chrome).
grant_type Zgodnie z specyfikacją OAuth 2.0 wartość tego pola musi wynosić refresh_token.
refresh_token Token odświeżania zwrócony z wymiany kodu autoryzacji.

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

Niestandardowy schemat identyfikatora URI (Android, iOS, UWP)

Niestandardowe schematy identyfikatorów URI to forma precyzyjnych linków, które do otwierania aplikacji używają niestandardowego schematu.

Alternatywa dla korzystania z niestandardowych schematów URI na Androidzie

Użyj pakietu SDK logowania Google na Androida, który przekazuje odpowiedź OAuth 2.0 bezpośrednio do aplikacji, co eliminuje konieczność korzystania z adresu URI przekierowania.

Jak przejść na pakiet SDK Logowania przez Google na Androida

Jeśli do integracji OAuth na Androidzie używasz niestandardowego schematu, musisz wykonać te czynności, aby w pełni przejść na zalecany pakiet SDK Logowania w Google na Androida:

  1. Zaktualizuj kod, aby używać pakietu SDK logowania w Google.
  2. Wyłącz obsługę schematu niestandardowego w Konsoli interfejsów API Google.

Aby przejść na pakiet Android SDK logowania w Google, wykonaj te czynności:

  1. Zaktualizuj kod, aby używać pakietu Android SDK do logowania się w Google:
    1. Sprawdź kod, aby znaleźć miejsce, w którym wysyłasz żądanie do serwera OAuth 2.0 Google. Jeśli używasz schematu niestandardowego, Twoje żądanie będzie wyglądać tak: 
        https://accounts.google.com/o/oauth2/v2/auth?
  scope=<SCOPES>&
  response_type=code&
  &state=<STATE>&
  redirect_uri=com.example.app:/oauth2redirect&
  client_id=<CLIENT_ID>
      com.example.app:/oauth2redirect to identyfikator URI przekierowania w ramach schematu niestandardowego w przykładzie powyżej. Więcej informacji o formacie wartości niestandardowego schematu URI znajdziesz w definicji parametru redirect_uri.
    2. Zanotuj parametry żądania scope i client_id, których będziesz potrzebować do skonfigurowania pakietu SDK logowania w Google.
    3. Aby skonfigurować pakiet SDK, wykonaj instrukcje podane w artykule Rozpoczęcie integracji logowania Google z aplikacją na Androida. Możesz pominąć krok Uzyskaj identyfikator klienta OAuth 2.0 serwera zaplecza, ponieważ client_id uzyskany w poprzednim kroku będzie używany ponownie.
    4. Wykonaj czynności opisane w  instrukcji włączania dostępu do interfejsu API po stronie serwera. Obejmuje ona te czynności:
      1. Aby pobrać kod uwierzytelniający dla zakresów, których dotyczy prośba o uprawnienia, użyj metody getServerAuthCode.
      2. Wyślij kod uwierzytelniający do backendu aplikacji, aby wymienić go na token dostępu i odświeżania.
      3. Użyj pobranego tokena dostępu, aby wywoływać interfejsy API Google w imieniu użytkownika.
  2. Wyłącz obsługę schematu niestandardowego w Konsoli interfejsów API Google:
    1. Otwórz listę Dane logowania OAuth 2.0 i wybierz klienta na Androida.
    2. Przejdź do sekcji Ustawienia zaawansowane, odznacz pole wyboru Włącz niestandardowy schemat URI i kliknij Zapisz, aby wyłączyć obsługę niestandardowego schematu URI.

Włącz niestandardowy schemat URI

Jeśli zalecana alternatywa nie działa, możesz włączyć niestandardowe schematy URI dla klienta Androida, wykonując te czynności:
  1. Otwórz listę Dane logowania OAuth 2.0 i wybierz klienta na Androida.
  2. Przejdź do sekcji Ustawienia zaawansowane, zaznacz pole wyboru Włącz niestandardowy schemat URI i kliknij Zapisz, aby włączyć obsługę niestandardowego schematu URI.

Alternatywa dla korzystania z niestandardowych schematów URI w aplikacjach Chrome

Użyj interfejsu Chrome Identity API, który przekazuje odpowiedź OAuth 2.0 bezpośrednio do aplikacji, co eliminuje konieczność korzystania z identyfikatora URI przekierowania.

Adres IP loopback (macOS, Linux, Windows na komputerze)

Aby otrzymać kod autoryzacji za pomocą tego adresu URL, aplikacja musi nasłuchiwać na lokalnym serwerze WWW. Jest to możliwe na wielu platformach, ale nie na wszystkich. Jeśli jednak Twoja platforma to obsługuje, jest to zalecany mechanizm uzyskiwania kodu autoryzacji.

Gdy aplikacja otrzyma odpowiedź autoryzacyjną, powinna wyświetlić stronę HTML z instrukcją, aby użytkownik zamknął przeglądarkę i wrócił do aplikacji.

Zalecane użycie aplikacje na komputery z systemem macOS, Linux i Windows (ale nie na platformę uniwersalną systemu Windows);
Wartości formularzy Jako typ aplikacji wybierz Aplikacja na komputer.

Ręczne kopiowanie/wklejanie (wycofane)

Chroń swoje aplikacje

Potwierdzanie prawa własności do aplikacji (Android, Chrome)

Aby zmniejszyć ryzyko podszywania się pod aplikację, możesz zweryfikować prawo własności do niej.

Android

Aby przejść proces weryfikacji, możesz użyć konta dewelopera w Google Play, jeśli je masz, a Twoja aplikacja jest zarejestrowana w Konsoli Google Play. Aby przejść weryfikację, musisz spełnić te wymagania:

  • W Konsoli Google Play musisz mieć zarejestrowaną aplikację z tą samą nazwą pakietu i odciskiem cyfrowym certyfikatu podpisującego SHA-1 co klient OAuth na Androida, którego weryfikację chcesz przeprowadzić.
  • W Konsoli Google Play musisz mieć uprawnienia Administratora w przypadku tej aplikacji. Dowiedz się więcej o zarządzaniu dostępem w Konsoli Google Play.

W sekcji Weryfikacja własności aplikacji w kliencie na Androida kliknij przycisk Zweryfikuj własność, aby dokończyć proces weryfikacji.

Jeśli weryfikacja się powiedzie, wyświetli się powiadomienie z potwierdzeniem zakończenia procesu weryfikacji. W przeciwnym razie pojawi się komunikat o błędzie.

Aby naprawić nieudaną weryfikację:

  • Upewnij się, że aplikacja, którą weryfikujesz, jest zarejestrowana w Konsoli Google Play.
  • Sprawdź, czy w Konsoli Google Play masz uprawnienia administratora w odniesieniu do tej aplikacji.
Chrome

Aby ukończyć proces weryfikacji, musisz użyć konta dewelopera w Chrome Web Store. Aby przejść weryfikację, musisz spełnić te wymagania:

  • Musisz mieć zarejestrowany produkt w panelu dewelopera Chrome Web Store z tym samym identyfikatorem produktu co klient OAuth rozszerzenia Chrome, którego dotyczy weryfikacja.
  • Musisz być wydawcą produktu w Chrome Web Store. Dowiedz się więcej o zarządzaniu dostępem w panelu dewelopera Chrome Web Store.

W sekcji Zweryfikuj własność aplikacji w kliencie rozszerzenia Chrome kliknij przycisk Zweryfikuj własność, aby dokończyć proces weryfikacji.

Uwaga: po przyznaniu dostępu do konta odczekaj kilka minut, zanim zakończysz proces weryfikacji.

Jeśli weryfikacja się powiedzie, wyświetli się powiadomienie z potwierdzeniem zakończenia procesu weryfikacji. W przeciwnym razie pojawi się komunikat o błędzie.

Aby naprawić nieudaną weryfikację:

  • Upewnij się, że w panelu dewelopera Chrome Web Store jest zarejestrowany produkt z tym samym identyfikatorem produktu co klient OAuth rozszerzenia Chrome, którego dotyczy weryfikacja.
  • Upewnij się, że jesteś wydawcą aplikacji, czyli jesteś albo wydawcą indywidualnym, albo członkiem grupy wydawców aplikacji. Dowiedz się więcej o zarządzaniu dostępem w panelu dewelopera w Chrome Web Store.
  • Jeśli właśnie zaktualizowałeś listę grup wydawców, sprawdź, czy lista członków grupy wydawców jest zsynchronizowana w panelu dewelopera Chrome Web Store. Dowiedz się więcej o synchronizowaniu listy wydawców.

Sprawdzanie aplikacji (tylko iOS)

Funkcja Sprawdzanie aplikacji pomaga chronić aplikacje na iOS przed nieautoryzowanym użyciem. Wykorzystuje do tego usługę App Attest firmy Apple, aby sprawdzać, czy żądania wysyłane do punktów końcowych Google OAuth 2.0 pochodzą z Twoich autentycznych aplikacji. Pomaga to zmniejszyć ryzyko podszywania się w aplikacji.

Włącz Sprawdzanie aplikacji dla klienta na iOS

Aby móc włączyć Sprawdzanie aplikacji dla klienta na iOS, musisz spełnić te wymagania:
  • Musisz podać identyfikator zespołu dla klienta na iOS.
  • W identyfikatorze pakietu nie można używać symboli wieloznacznych, ponieważ może to spowodować, że identyfikator będzie wskazywał więcej niż 1 aplikację. Oznacza to, że identyfikator pakietu nie może zawierać symbolu gwiazdki (*).
Aby włączyć Sprawdzanie aplikacji, w widoku edycji klienta na iOS włącz przełącznik Chroń klienta OAuth przed nadużyciami przy pomocy funkcji Sprawdzanie aplikacji Firebase.

Po włączeniu Sprawdzania aplikacji w oknie edycji klienta OAuth zaczniesz widzieć dane dotyczące żądań OAuth z Twojego klienta. Żądania z niezweryfikowanych źródeł nie będą blokowane, dopóki nie włączysz sprawdzania aplikacji. Informacje na stronie monitorowania wskaźników mogą pomóc Ci określić, kiedy rozpocząć egzekwowanie zasad.

Po włączeniu funkcji sprawdzania aplikacji na urządzeniu z iOS mogą pojawić się błędy związane z tą funkcją. Aby je naprawić, wykonaj te czynności:

  • Sprawdź, czy podany identyfikator pakietu i identyfikator zespołu są prawidłowe.
  • Sprawdź, czy identyfikator pakietu nie zawiera symbolu wieloznacznego.

Wymuszanie Sprawdzania aplikacji na kliencie iOS

Włączenie Sprawdzania aplikacji nie powoduje automatycznego blokowania nierozpoznanych żądań. Aby zastosować to zabezpieczenie, przejdź do widoku edycji klienta na iOS. Po prawej stronie strony w sekcji Tożsamość Google w iOS znajdziesz dane Sprawdzania aplikacji. Dane obejmują:
  • Liczba zweryfikowanych żądań – żądania z prawidłowym tokenem Sprawdzania aplikacji. Gdy włączysz egzekwowanie kontroli aplikacji, tylko żądania z tej kategorii będą się udawać.
  • Liczba niezweryfikowanych żądań: prawdopodobnie nieaktualne żądania klienta – żądania, w których brakuje tokena Sprawdzania aplikacji. Mogą one pochodzić ze starszej wersji aplikacji, która nie zawiera implementacji Sprawdzania aplikacji.
  • Liczba niezweryfikowanych żądań: żądania nieznanego pochodzenia – żądania, w których brakuje tokena Sprawdzania aplikacji i które nie wyglądają na pochodzące z Twojej aplikacji.
  • Liczba niezweryfikowanych żądań: nieprawidłowe żądania – żądania z nieprawidłowym tokenem Sprawdzania aplikacji, który może pochodzić od nieautentycznego klienta próbującego podszyć się pod Twoją aplikację lub ze środowisk emulowanych.
Zapoznaj się z tymi danymi, aby dowiedzieć się, jak wymuszanie weryfikacji aplikacji wpłynie na użytkowników.

Aby wymusić sprawdzanie aplikacji, kliknij przycisk ENFORCE i potwierdź swój wybór. Gdy wymuszanie będzie aktywne, wszystkie niezweryfikowane żądania wysyłane przez Twojego klienta będą odrzucane.

Uwaga: po włączeniu egzekwowania zmian może minąć do 15 minut, zanim zaczną one obowiązywać.

Wyłącz wymuszanie Sprawdzania aplikacji w przypadku klienta na iOS

Wyłączenie wymuszania Sprawdzania aplikacji spowoduje zaprzestanie wymuszania i zezwoli na wszystkie żądania wysyłane przez Twojego klienta do punktów końcowych Google OAuth 2.0, w tym niezweryfikowane żądania.

Aby wyłączyć sprawdzanie aplikacji w przypadku klienta na iOS, otwórz widok edycji klienta na iOS i kliknij przycisk WYŁĄCZ, a potem potwierdź swój wybór.

Uwaga: po wyłączeniu sprawdzania aplikacji wprowadzenie zmian może potrwać do 15 minut.

Wyłączanie Sprawdzania aplikacji w przypadku klienta iOS

Wyłączenie Sprawdzania aplikacji spowoduje zaprzestanie wszystkich działań związanych z monitorowaniem i wymuszaniem. Rozważ wyłączenie Sprawdzania aplikacji, aby móc nadal monitorować dane klienta.

Aby wyłączyć Sprawdzanie aplikacji dla klienta na iOS, otwórz widok edycji klienta na iOS i wyłącz przełącznik Chroń klienta OAuth przed nadużyciami przy pomocy Sprawdzania aplikacji Firebase.

Uwaga: po wyłączeniu funkcji sprawdzania aplikacji wprowadzenie zmian może potrwać do 15 minut.

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

Wdrażanie Ochrony wszystkich kont

Dodatkowym krokiem, który należy wykonać, aby chronić konta użytkowników, jest wdrożenie ochrony na wielu kontach za pomocą usługi Google Cross-Account Protection. Ta usługa umożliwia subskrybowanie powiadomień o zdarzeniach związanych z bezpieczeństwem, które dostarczają aplikacji informacji o ważnych zmianach na koncie użytkownika. Następnie możesz podjąć odpowiednie działania w zależności od tego, jak chcesz reagować na zdarzenia.

Przykłady typów zdarzeń wysyłanych do Twojej aplikacji przez usługę ochrony na wielu kontach:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

Więcej informacji o wdrażaniu ochrony wszystkich kont oraz pełną listę dostępnych zdarzeń znajdziesz na stronie Ochrona kont użytkowników za pomocą ochrony wszystkich kont .