OAuth 2.0 dla aplikacji mobilnych i komputerowych

W tym omówieniu podsumowujemy procesy OAuth 2.0 obsługiwane przez Google, co pomoże Ci wybrać odpowiedni proces dla Twojej aplikacji.

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 interfejsów API Google.

Protokół 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 korzystać z protokołu OAuth 2.0, aby uzyskiwać od użytkowników uprawnienia do przechowywania plików na ich Dyskach Google.

Zainstalowane aplikacje są dystrybuowane na poszczególnych urządzeniach. Przyjmuje się, że nie mogą one zachowywać obiektów tajnych. Mogą korzystać z interfejsów API Google, gdy użytkownik korzysta z aplikacji lub gdy aplikacja działa w tle.

Ten proces autoryzacji jest podobny do procesu stosowanego w przypadku aplikacji serwera WWW. Główna różnica polega na tym, że zainstalowane aplikacje muszą otworzyć przeglądarkę systemu i dostarczyć lokalny identyfikator URI przekierowania do obsługi odpowiedzi z serwera autoryzacji Google.

Alternatywy

W aplikacjach mobilnych możesz preferować korzystanie z Logowania przez Google na Androida lub iOS. Biblioteki klienta Logowania przez Google obsługują uwierzytelnianie i autoryzację użytkowników. Ich implementacja może być prostsza niż opisany tutaj protokół niższego poziomu.

W przypadku aplikacji działających na urządzeniach nieobsługujących przeglądarki systemowej lub mających ograniczone możliwości wprowadzania danych (takich jak telewizory, konsole do gier, kamery czy drukarki), zapoznaj się z artykułem na temat protokołu OAuth 2.0 na telewizory i urządzenia oraz logowania się na telewizorach i urządzeniach z ograniczonym dostępem.

Biblioteki i przykłady

Zalecamy użycie tych bibliotek i przykładów, które pomogą Ci wdrożyć proces OAuth 2.0 opisany w tym dokumencie:

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

Wymagania wstępne

Włącz interfejsy API w projekcie

Każda aplikacja wywołująca interfejsy API Google musi włączyć te interfejsy w elemencie 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 uporządkowanych według rodziny usług i popularności. Jeśli interfejsu API, który chcesz włączyć, nie ma na liście, znajdź go przy użyciu wyszukiwarki 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.

Utwórz dane logowania

Każda aplikacja korzystająca z protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google musi mieć dane logowania, które identyfikują aplikację na serwerze Google OAuth 2.0. Podane niżej instrukcje wyjaśniają, jak utworzyć dane logowania do projektu. Aplikacje mogą używać tych danych logowania, aby uzyskiwać dostęp 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 sekcjach poniżej opisujemy typy klientów i metody przekierowania obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nazwij klienta OAuth i odpowiednio ustaw inne pola formularza.

Android

1. Wybierz typ aplikacji Android.
2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana na Credentials page Twojego projektu, aby umożliwić identyfikację klienta.
3. Wpisz nazwę pakietu swojej aplikacji na Androida. Ta wartość jest określona w atrybucie package elementu <manifest> w pliku manifestu aplikacji.
4. Wpisz odcisk cyfrowy certyfikatu podpisywania SHA-1 dystrybucji aplikacji.
   • Jeśli 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 podpisywania, użyj narzędzia keytool dołączonego do Javy, aby wydrukować informacje o certyfikacie w formacie zrozumiałym dla człowieka. Skopiuj wartość SHA1 z sekcji Certificate fingerprints 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 wyświetlana na Credentials page Twojego projektu, aby umożliwić identyfikację klienta.
3. Wpisz identyfikator pakietu swojej aplikacji. Identyfikator pakietu to wartość klucza CFBundleIdentifier w pliku zasobów z listą właściwości informacji o aplikacji (info.plist). Ta wartość jest najczęściej wyświetlana w panelu Ogólne lub panelu Podpisywanie i możliwości w edytorze projektu Xcode. Identyfikator pakietu jest też wyświetlany w sekcji Informacje ogólne na stronie Informacje o aplikacji w witrynie Apple App Store Connect.
4. (Opcjonalne)

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

   1. Na urządzeniu z iOS lub iPadOS otwórz aplikację Apple App Store.
   2. Wyszukaj swoją aplikację.
   3. Wybierz przycisk Udostępnij (symbol kwadratowy i strzałka w górę).
   4. Kliknij Kopiuj link.
   5. Wklej link do edytora tekstu. Identyfikator App Store to końcowa część adresu URL.

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

5. (Opcjonalne)

   Wpisz identyfikator zespołu. Więcej informacji znajdziesz w sekcji Znajdowanie identyfikatora zespołu w dokumentacji konta dewelopera Apple.

6. Kliknij Utwórz.

platforma UWP

1. Wybierz typ aplikacji Universal Windows Platform.
2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana na Credentials page Twojego projektu, aby umożliwić identyfikację klienta.
3. Wpisz 12-znakowy identyfikator Microsoft Store swojej aplikacji. Tę wartość znajdziesz 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.

Niestandardowy schemat identyfikatora URI (Android, iOS, UWP)

Niestandardowe schematy URI to rodzaj precyzyjnych linków, w których do otwierania aplikacji używany jest niestandardowy schemat adresu URL.

Ważne: niestandardowe schematy URI nie są już obsługiwane w nowych aplikacjach Chrome i są domyślnie wyłączone w nowych klientach na Androida ze względu na ryzyko podszywania się pod inne aplikacje.

Alternatywa dla niestandardowych schematów URI na Androidzie

Użyj pakietu SDK Google Sign-In na Androida, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując potrzebę podawania identyfikatora URI przekierowania.

Jak przejść na pakiet SDK Google Sign-In dla Androida

Jeśli do integracji OAuth na Androidzie używasz obecnie schematu niestandardowego, musisz wykonać poniższe działania, aby w pełni przejść na zalecany pakiet SDK logowania Google na Androida:

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

Uwaga: zanim wyłączysz obsługę schematów niestandardowych w konsoli interfejsów API Google, zakończ i wdróż aktualizacje kodu (uwzględniając czas rozpowszechnienia na kontach użytkowników i starszych urządzeniach), aby uniknąć wyświetlania komunikatu o błędzie invalid_request podczas próby użycia aplikacji.

Aby przejść na pakiet SDK Google Sign-In na Androida, wykonaj te czynności:

1. Zaktualizuj kod, aby używać pakietu SDK do logowania się przez Google na Androida:
   1. Sprawdź kod, aby określić, gdzie wysyłasz żądanie do serwera Google OAuth 2.0. Jeśli używasz schematu niestandardowego, żą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 schematu niestandardowego w powyższym przykładzie. 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 potrzebujesz do skonfigurowania pakietu Google Sign-In SDK.
      Uwaga: jeśli używasz biblioteki zewnętrznej, poszukaj tych informacji w jej pliku konfiguracji.
   3. Skonfiguruj pakiet SDK, postępując zgodnie z instrukcjami rozpoczynania integracji logowania przez Google z aplikacją na Androida. Możesz pominąć krok pobierania identyfikatora klienta OAuth 2.0 serwera backendu, ponieważ w ten sam sposób możesz użyć client_id pobranego w poprzednim kroku.
   4. Postępuj zgodnie z instrukcjami włączania dostępu do interfejsu API po stronie serwera. Wykonaj te czynności:
      1. Aby pobrać kod autoryzacji dla zakresów, do których prosisz o uprawnienia, użyj metody getServerAuthCode.
      2. Wyślij kod autoryzacji do backendu aplikacji, aby wymienić go na token dostępu i odświeżenia.
      3. Pobrany token dostępu służy do wywoływania interfejsów API Google w imieniu użytkownika.
      Uwaga: jeśli Twoja aplikacja nie wymaga dostępu offline, wykonaj te instrukcje, aby poprosić o dostęp do interfejsu API po stronie klienta.
2. Wyłącz obsługę schematu niestandardowego w konsoli interfejsów API Google:
   1. Otwórz listę danych uwierzytelniających OAuth 2.0 i wybierz swojego 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łączam niestandardowy schemat URI

Jeśli zalecana alternatywa Ci nie odpowiada, możesz włączyć niestandardowe schematy URI w swoim kliencie na Androida, wykonując te instrukcje:

1. Otwórz listę danych uwierzytelniających OAuth 2.0 i wybierz swojego 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ę niestandardowych schematów URI.

Alternatywa dla niestandardowych schematów URI w aplikacjach Chrome

Skorzystaj z interfejsu Chrome Identity API, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując potrzebę identyfikatora URI przekierowania.

Weryfikowanie własności aplikacji (Android, Chrome)

Możesz zweryfikować własność aplikacji, aby zmniejszyć ryzyko podszywania się pod nią.

Android

Uwaga: weryfikacja własności aplikacji na Androida jest obecnie dostępna tylko w przypadku aplikacji z Google Play.

Aby ukończyć proces weryfikacji, możesz użyć swojego konta dewelopera w Google Play, jeśli je masz, a Twoja aplikacja jest zarejestrowana w Konsoli Google Play. Aby weryfikacja przebiegła pomyślnie, musisz spełniać te wymagania:

• Musisz mieć zarejestrowaną aplikację w Konsoli Google Play z tą samą nazwą pakietu i odciskiem cyfrowym w zapisie SHA-1 co klient OAuth na Androida, którego dotyczy proces weryfikacji.
• Musisz mieć uprawnienia administratora aplikacji w Konsoli Google Play. Dowiedz się więcej o zarządzaniu dostępem w Konsoli Google Play.

W sekcji Zweryfikuj własność aplikacji klienta Androida kliknij przycisk Zweryfikuj własność, aby zakończyć proces weryfikacji.

Jeśli weryfikacja się powiedzie, zobaczysz powiadomienie z potwierdzeniem. W przeciwnym razie pojawi się komunikat o błędzie.

Aby poprawić błędy weryfikacji, wykonaj te czynności:

• Upewnij się, że aplikacja, którą chcesz zweryfikować, jest zarejestrowana w Konsoli Google Play.
• Sprawdź, czy masz uprawnienia administratora aplikacji w Konsoli Google Play.

Chrome

Aby zakończyć proces weryfikacji, użyj konta dewelopera w Chrome Web Store. Aby weryfikacja przebiegła pomyślnie, musisz spełniać te wymagania:

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

Aby zakończyć proces weryfikacji, w sekcji Zweryfikuj własność aplikacji klienta rozszerzenia do Chrome kliknij przycisk Zweryfikuj własność.

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

Jeśli weryfikacja się powiedzie, zobaczysz powiadomienie z potwierdzeniem. W przeciwnym razie pojawi się komunikat o błędzie.

Aby poprawić błędy weryfikacji, wykonaj te czynności:

• Sprawdź, czy w panelu dewelopera Chrome Web Store znajduje się zarejestrowany produkt o tym samym identyfikatorze co klient OAuth rozszerzenia do Chrome, którego dotyczy weryfikacja.
• Upewnij się, że jesteś wydawcą aplikacji, czyli zarówno indywidualnym, jak i grupowym wydawcą 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ę wydawców grupowych, sprawdź, czy jest ona zsynchronizowana w panelu dewelopera Chrome Web Store. Dowiedz się więcej o synchronizowaniu listy członków wydawcy.

Adres IP sprzężenia zwrotnego (macOS, Linux, Windows na komputerze)

Ważne: opcja przekierowania adresu IP w pętli zwrotnej jest WYCOFANY w przypadku klientów OAuth na Androida, aplikacja Chrome i iOS. Instrukcje migracji do obsługiwanej opcji alternatywnej znajdziesz w przewodniku po migracji adresów IP w pętli.

Aby odebrać 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. Jest to zalecany mechanizm uzyskiwania kodu autoryzacji, o ile Twoja platforma go obsługuje.

Gdy aplikacja otrzymuje odpowiedź autoryzacyjną, powinna w pełni wykorzystać tę funkcję, wyświetlając stronę HTML z instrukcją dla użytkownika, aby zamknął przeglądarkę i wrócił do aplikacji.

Zalecane wykorzystanie	aplikacje komputerowe dla systemów macOS, Linux i Windows (ale nie na uniwersalnej platformie Windows);
Wartości formularza	Ustaw typ aplikacji na Aplikacja komputerowa.

Uwaga: więcej informacji o adresie IP sprzężenia zwrotnego znajdziesz w definicji parametru redirect_uri. Zamiast adresu IP sprzężenia zwrotnego możesz też użyć localhost, ale ta konfiguracja może powodować problemy z zaporami sieciowymi klienta. Większość zapór sieciowych (ale nie wszystkie) zezwala na komunikację w pętli.

Ręczne kopiowanie i wklejanie

Ważne: opcja ręcznego kopiowania i wklejania, zwana też metodą przekierowania poza zakresem (OOB), nie jest już obsługiwana. Instrukcje przejścia na bezpieczną alternatywę znajdziesz w przewodniku po migracji OOB.

Zidentyfikuj zakresy dostępu

Zakresy pozwalają aplikacji prosić o dostęp tylko do tych 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 zidentyfikowanie zakresów, do których aplikacja będzie potrzebować uprawnień dostępu.

Uwaga: autoryzacja przyrostowa nie jest obsługiwana w przypadku zainstalowanych aplikacji ani urządzeń.

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

Jeśli Twoja publiczna aplikacja korzysta z zakresów umożliwiających dostęp do określonych danych użytkownika, musi ona przejść proces weryfikacji. Jeśli podczas testowania aplikacji na ekranie zobaczysz niezweryfikowaną aplikację, musisz przesłać prośbę o weryfikację, aby ją usunąć. Dowiedz się więcej o niezweryfikowanych aplikacjach i poznaj odpowiedzi na najczęstsze pytania dotyczące weryfikacji aplikacji w Centrum pomocy.

Uzyskiwanie tokenów dostępu OAuth 2.0

Poniższe kroki pokazują, jak Twoja aplikacja współpracuje z serwerem Google OAuth 2.0, aby uzyskać zgodę użytkownika na wykonanie żądania do interfejsu API w jego imieniu. Twoja aplikacja musi uzyskać taką zgodę, zanim będzie mogła wykonać żądanie do interfejsu Google API wymagające autoryzacji użytkownika.

Krok 1. Wygeneruj weryfikatora kodu i test zabezpieczający logowanie

Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo przepływu zainstalowanej 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, który zawiera niezarezerwowane znaki [A–Z] / [a–z] / [0–9] / „-” / „.” / „_” / "~", o minimalnej długości 43 znaków i maksymalnej długości 128 znaków.

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

Utwórz zadanie z kodem

Obsługiwane są 2 metody tworzenia testów zabezpieczających logowanie.

Metody generowania wyzwań związanych z kodem
S256 (zalecane)	Wyzwanie kodu jest zakodowanym w Base64URL (bez dopełnienia) haszem weryfikatora kodu w SHA256. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
zwykły	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 na adres https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy obsługuje wyszukiwanie sesji, uwierzytelnia użytkownika i uzyskuje jego zgodę. Punkt końcowy jest dostępny tylko przez protokół SSL i odrzuca połączenia HTTP (bez SSL).

Serwer autoryzacji obsługuje następujące parametry ciągu zapytania dla zainstalowanych aplikacji:

Parametry
client_id	Wymagany Identyfikator klienta Twojej aplikacji. Tę wartość znajdziesz tutaj: API Console Credentials page.
redirect_uri	Wymagany Określa, w jaki sposób serwer autoryzacji Google wysyła odpowiedź do Twojej aplikacji. Zainstalowane aplikacje mają kilka opcji przekierowania. Musisz też skonfigurować dane logowania pod kątem określonej metody przekierowania. Wartość musi być dokładnie taka sama jak jeden z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanych w pliku API Console Credentials pageklienta. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI, wystąpi błąd redirect_uri_mismatch. W tabeli poniżej znajdziesz wartości parametru redirect_uri odpowiednie dla każdej metody: Wartości redirect_uri Niestandardowy schemat identyfikatora URI com.example.app:redirect_uri_path lub to com.googleusercontent.apps.123:redirect_uri_path com.example.app to odwrotny zapis DNS domeny pod Twoją kontrolą. Schemat niestandardowy musi zawierać kropkę. com.googleusercontent.apps.123 to odwrotna notacja DNS identyfikatora klienta. redirect_uri_path to opcjonalny komponent ścieżki, np. /oauth2redirect. Pamiętaj, że ścieżka powinna zaczynać się od pojedynczego ukośnika, który różni się od zwykłych adresów URL HTTP. Uwaga : niestandardowe schematy URI nie są już obsługiwane w aplikacjach Chrome i są domyślnie wyłączone na Androidzie. Dowiedz się więcej o alternatywnych schematach niestandardowych do aplikacji na Androida i aplikacje Chrome. Adres IP sprzężenia zwrotnego http://127.0.0.1:port lub http://[::1]:port Wyślij do platformy zapytanie o odpowiedni adres IP sprzężenia zwrotnego i uruchom odbiornik HTTP na losowym dostępnym porcie. Zastąp port rzeczywistym numerem portu, na którym nasłuchuje aplikacja. Pamiętaj, że obsługa opcji przekierowania adresu IP w pętli w aplikacjach mobilnych została WYCOFANY.
response_type	Wymagany Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji. Ustaw wartość parametru na code dla zainstalowanych aplikacji.
scope	Wymagany Lista rozdzielonych spacjami zakresów określających zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują o ekranie zgody, który Google wyświetla użytkownikowi. Zakresy pozwalają aplikacji prosić o dostęp tylko do tych zasobów, których potrzebuje, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu, który przyznają aplikacji. Dlatego występuje odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.
code_challenge	Zalecane Określa zakodowany code_verifier, który będzie używany jako test zabezpieczający po stronie serwera podczas wymiany kodów autoryzacji. Więcej informacji znajdziesz w sekcji o tworzeniu kodu zabezpieczającego powyżej.
code_challenge_method	Zalecane Określa metodę użytą do kodowania obiektu code_verifier, który będzie używany podczas wymiany kodów autoryzacji. Tego parametru należy używać z opisem powyżej parametru code_challenge. Jeśli żądanie zawiera code_challenge, wartość code_challenge_method jest domyślnie ustawiana na plain. Jedyne obsługiwane wartości tego parametru to S256 i plain.
state	Zalecane Określa dowolną wartość ciągu znaków, której aplikacja używa do utrzymywania 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 (#) parametru redirect_uri, gdy użytkownik wyrazi zgodę na dostęp aplikacji lub go odrzuci. Możesz używać tego parametru do różnych celów, np. do kierowania użytkownika do właściwego zasobu w aplikacji, wysyłania liczb jednorazowych i zapobiegania fałszowaniu żądań z innych witryn. Ponieważ redirect_uri można odgadnąć, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli wygenerujesz losowy ciąg lub zakodujesz skrót pliku cookie bądź inną wartość, która przechwytuje stan klienta, możesz zweryfikować odpowiedź, by dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zabezpiecza to przed atakami, takimi jak fałszowanie żądań z innych witryn. Przykład tworzenia i potwierdzania 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 wskazać serwerowi uwierzytelniania Google wskazówkę. Serwer korzysta z tej podpowiedzi, aby uprościć proces logowania, wstępnie wypełniając pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania. Ustaw wartość parametru na adres e-mail lub identyfikator sub, który odpowiada identyfikatorowi Google użytkownika.

Uwaga: autoryzacja przyrostowa w przypadku zainstalowanych aplikacji nie jest obsługiwana, ponieważ klient nie może zachować poufności client_secret.

Przykładowe adresy URL autoryzacji

Na kartach poniżej znajdziesz 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 ułatwiające czytelność.

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 sprzężenia zwrotnego

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ę

W tym kroku użytkownik decyduje, czy przyznać Twojej aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody z nazwą Twojej aplikacji i usług interfejsu Google API, do których prosi o pozwolenie na dostęp. Służą do tego dane logowania użytkownika, a także podsumowanie zakresów przyznanych dostępu. Użytkownik może wówczas wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu żądanego przez Twoją aplikację lub odrzucić prośbę.

Na tym etapie Twoja aplikacja nie musi nic robić, ponieważ czeka na odpowiedź serwera Google OAuth 2.0 z informacją o przyznaniu dostępu. Odpowiedź wyjaśnimy w następnym kroku.

Błędy

Żądania wysyłane do punktu końcowego autoryzacji OAuth 2.0 Google mogą wyświetlać komunikaty o błędach, które widzą użytkownicy, zamiast oczekiwanych przepływów uwierzytelniania i autoryzacji. Poniżej znajdziesz typowe kody błędów i sugerowane rozwiązania.

admin_policy_enforced

Na koncie Google nie można autoryzować co najmniej 1 żądanego zakresu ze względu na zasady administratora Google Workspace. Przeczytaj artykuł pomocy dla administratorów Google Workspace Określanie, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace, aby dowiedzieć się więcej o tym, jak administrator może ograniczać dostęp do wszystkich zakresów albo do zakresów wrażliwych i zakresów z ograniczeniami do czasu jednoznacznego przyznania dostępu do Twojego identyfikatora klienta OAuth.

disallowed_useragent

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

Android

Deweloperzy aplikacji na Androida mogą napotkać ten komunikat o błędzie podczas otwierania żądań autoryzacji w android.webkit.WebView. Deweloperzy powinni zamiast tego używać bibliotek Androida, takich jak Google Sign-In for Android lub AppAuth for Android fundacji OpenID Foundation.

Programiści stron internetowych mogą napotkać ten błąd, gdy aplikacja na Androida otwiera ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przechodzi z Twojej witryny do punktu końcowego autoryzacji OAuth 2.0 Google. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który obejmuje moduły obsługi linków aplikacji na Androida i domyślną aplikację przeglądarki. Obsługiwaną opcją jest też biblioteka kart niestandardowych na Androida.

iOS

Deweloperzy aplikacji na iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView. Deweloperzy powinni zamiast tego używać bibliotek iOS, takich jak Google Sign-In for iOS lub AppAuth for iOS opracowanych przez OpenID Foundation.

Programiści stron internetowych mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otworzy ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przejdzie z Twojej witryny do punktu końcowego autoryzacji OAuth 2.0 Google. Deweloperzy powinni zezwalać na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który obejmuje moduły obsługi linków uniwersalnych i domyślną aplikację przeglądarki. Obsługiwaną opcją jest też biblioteka SFSafariViewController.

org_internal

Identyfikator klienta OAuth w żądaniu jest częścią projektu ograniczającego dostęp do kont Google w określonej organizacji Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w sekcji Typ użytkownika artykułu pomocy dotyczącego konfigurowania ekranu zgody OAuth.

invalid_grant

Jeśli używasz weryfikatora kodu i testu zabezpieczającego, parametr code_callenge jest nieprawidłowy lub go brak. Upewnij się, że parametr code_challenge jest skonfigurowany prawidłowo.

Podczas odświeżania tokena dostępu token mógł wygasnąć lub został unieważniony. Ponownie uwierzytelnij użytkownika i poproś o zgodę na uzyskanie nowych tokenów. Jeśli ten błąd nadal się pojawia, sprawdź, czy Twoja aplikacja została poprawnie skonfigurowana oraz czy w żądaniu używasz 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 pasuje do autoryzowanego identyfikatora URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania w Google API Console Credentials page.

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

Parametr redirect_uri może odnosić się do zewnętrznego procesu OAuth, który został wycofany i nie jest już obsługiwany. Informacje o tym, jak zaktualizować integrację, znajdziesz w przewodniku po migracji.

invalid_request

Coś jest nie tak z przesłaną przez Ciebie prośbą. Istnieje kilka możliwych przyczyn tej sytuacji:

• Żądanie nie jest prawidłowo sformatowane
• W żądaniu brakowało wymaganych parametrów
• Żądanie wykorzystuje metodę autoryzacji, która nie jest obsługiwana przez Google. Sprawdź, czy integracja OAuth korzysta z zalecanej metody integracji
• Identyfikator URI przekierowania używa niestandardowego schematu : jeśli zobaczysz komunikat o błędzie Niestandardowy schemat URI nie jest obsługiwany w aplikacjach Chrome lub Niestandardowy schemat identyfikatora URI nie został włączony w Twoim kliencie na Androida, oznacza to, że używasz niestandardowego schematu URI, który nie jest obsługiwany w aplikacjach Chrome i jest domyślnie wyłączony w Androidzie. Więcej informacji o alternatywach dla niestandardowych schematów URI

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacyjną, zależy od używanego przez nią schematu URI przekierowania. Niezależnie od schematu odpowiedź może 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 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. Wymiana kodu autoryzacji 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:

Pola
client_id	Identyfikator klienta uzyskany z API Console Credentials page.
client_secret	Klucz klienta uzyskany z API Console Credentials page.
code	Kod autoryzacji zwrócony w wyniku początkowego żądania.
code_verifier	Weryfikator kodu utworzony w kroku 1.
grant_type	Zgodnie ze specyfikacją OAuth 2.0 to pole musi mieć wartość authorization_code.
redirect_uri	Jeden z identyfikatorów URI przekierowania podanych w przypadku danego projektu client_id w polu API Console Credentials page .

Ten fragment kodu zawiera 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

Google odpowiada na to żądanie, zwracając obiekt JSON zawierający token dostępu o ograniczonym czasie ważności i token odświeżania.

Odpowiedź zawiera te pola:

Pola
access_token	Token wysyłany przez aplikację w celu autoryzacji żądania do interfejsu API Google.
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 żądanie zawiera zakres tożsamości, taki jak openid, profile lub email. Wartością jest token sieciowy JSON (JWT) zawierający podpisane cyfrowo informacje o tożsamości użytkownika.
refresh_token	Token, za pomocą którego możesz uzyskać nowy token dostępu. Tokeny odświeżania są ważne, dopóki użytkownik nie unieważni dostępu. Pamiętaj, że tokeny odświeżania zawsze są zwracane dla zainstalowanych aplikacji.
scope	Zakresy dostępu przyznane przez usługę access_token wyrażone w postaci listy ciągów rozdzielanych spacjami (z uwzględnieniem wielkości liter).
token_type	Typ zwróconego tokena. Obecnie wartość tego pola jest zawsze ustawiona na Bearer.

Ważne: aplikacja powinna przechowywać oba tokeny w bezpiecznej, długoterminowej lokalizacji, która jest dostępna między różnymi wywołaniami aplikacji. Token odświeżania umożliwia aplikacji uzyskanie nowego tokena dostępu, jeśli ten, który już stracił ważność. Jeśli więc aplikacja utraci token odświeżania, użytkownik będzie musiał powtórzyć proces uzyskiwania zgody OAuth 2.0, aby aplikacja mogła uzyskać nowy token odświeżania.

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"
}

Uwaga: aplikacja powinna ignorować wszelkie nierozpoznane pola w odpowiedzi.

Wywoływanie interfejsów API Google

Gdy aplikacja uzyska token dostępu, możesz za jego pomocą wywoływać interfejs Google API w imieniu danego konta użytkownika(o ile 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, uwzględniając parametr zapytania access_token lub wartość nagłówka HTTP Authorization Bearer. 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 do skonfigurowania wywołań interfejsów API Google (np. podczas wywołania interfejsu Drive Files API).

Wszystkie interfejsy API Google możesz wypróbować i zobaczyć ich zakresy w OAuth 2.0 Playground.

Przykłady 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 określić 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

Przykłady zapytań z operatorem curl

Możesz przetestować te polecenia za pomocą aplikacji wiersza poleceń curl. Oto przykład, w którym użyto opcji 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 uwierzytelniającymi dla powiązanego żądania do interfejsu API. Możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (nawet wtedy, gdy użytkownika nie ma), jeśli poprosisz o dostęp offline do zakresów powiązanych z tokenem.

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

Pola
client_id	Identyfikator klienta uzyskany z: API Console.
client_secret	Klucz klienta uzyskany z API Console. (Pole client_secret nie ma zastosowania w przypadku żądań wysyłanych z klientów zarejestrowanych jako aplikacje na Androida, iOS lub aplikacje Chrome).
grant_type	Zgodnie z definicją w specyfikacji OAuth 2.0, wartość tego pola musi być ustawiona na refresh_token.
refresh_token	Token odświeżania zwrócony z wymiany kodów autoryzacji.

Ten fragment kodu zawiera 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 anuluje dostępu przyznanego aplikacji, serwer tokenów zwróci 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"
}

Zwróć uwagę, że istnieją limity liczby tokenów odświeżania: 1 na kombinację klienta i użytkownika i 1 na użytkownika w przypadku wszystkich klientów. Zapisz tokeny odświeżania w pamięci długoterminowej i używaj ich, dopóki pozostaną ważne. Jeśli Twoja aplikacja żąda zbyt wielu tokenów odświeżania, limity te mogą zostać osiągnięte i starsze tokeny odświeżania przestaną działać.

Unieważnianie tokena

W niektórych przypadkach użytkownik może zechcieć anulować dostęp przyznany aplikacji. Użytkownik może odebrać dostęp w Ustawieniach konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu witryny lub aplikacji do Twojego konta w witrynie lub aplikacji innych firm, które mają dostęp do Twojego konta.

Aplikacja może też automatycznie anulować przyznany jej dostęp. Automatyczne unieważnienie jest ważne w przypadkach, gdy użytkownik anuluje subskrypcję, usunie aplikację lub znacząco zmienią się zasoby API wymagane przez aplikację. Innymi słowy, część procesu usuwania może obejmować żądanie do interfejsu API, aby zapewnić, że uprawnienia przyznane wcześniej aplikacji zostaną usunięte.

Aby programowo unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i umieszcza 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 jest to token dostępu, który ma odpowiedni token odświeżania, token odświeżania również zostanie unieważniony.

Jeśli odwołanie zostanie przetworzone pomyślnie, kod stanu HTTP odpowiedzi to 200. W przypadku wystąpienia błędu zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

Uwaga: po pomyślnej odpowiedzi na prośbę o unieważnienie może minąć trochę czasu, zanim będzie ono w pełni widoczne.

Dalsza lektura

Wiele opisanych tutaj sprawdzonych metod można znaleźć w sprawdzonych metodach protokołu OAuth 2.0 dla aplikacji natywnych IETF.