OAuth 2.0 na potrzeby aplikacji mobilnych i komputerowych

Uwaga: jeśli dopiero zaczynasz korzystać z OAuth 2.0, przeczytaj Omówienie protokołu OAuth 2.0, zanim zaczniesz. podsumowuje przepływy OAuth 2.0 obsługiwane przez Google, dzięki czemu możesz mieć pewność, możesz wybrać odpowiednią procedurę dla swojej aplikacji.

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

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

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

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

Alternatywy

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

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

Biblioteki i przykłady

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

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

Wymagania wstępne

Włączanie interfejsów API w projekcie

Każda aplikacja, która wywołuje interfejsy API Google, musi je włączyć w funkcji API Console

Aby włączyć interfejs API w projekcie:

1. Open the API Library w Google API Console
2. If prompted, select a project, or create a new one.
3. API Library zawiera listę wszystkich dostępnych interfejsów API pogrupowanych według usługi rodzina i popularność. Jeśli interfejsu API, który chcesz włączyć, nie ma na liście, użyj wyszukiwania, aby znajdź go lub kliknij Wyświetl wszystkie w rodzinie usług, do której należy.
4. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Tworzenie danych uwierzytelniających

Każda aplikacja korzystająca z protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google musi mieć dane uwierzytelniające które identyfikują aplikację na serwerze Google OAuth 2.0. Poniżej opisujemy, jak utworzysz dane logowania dla swojego projektu. Dzięki temu aplikacje mogą uzyskiwać dostęp do interfejsów API za pomocą danych logowania włączone w tym projekcie.

1. Go to the Credentials page.
2. Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
3. W poniższych sekcjach opisano typy klientów i metody przekierowania stosowane przez obsługiwanych przez serwer autoryzacji. Wybierz typ klienta zalecany dla Twojej aplikacji, nadaj mu nazwę klienta OAuth i ustaw pozostałe pola w formularzu jako odpowiednie.

Android

1. Wybierz typ aplikacji Android.
2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page identyfikacji klienta.
3. Wpisz nazwę pakietu aplikacji na Androida. Wartość jest określona w tagu Atrybut package elementu <manifest> w pliku manifestu aplikacji.
4. Wpisz odcisk cyfrowy certyfikatu podpisywania SHA-1 dystrybucji aplikacji.
   • Jeśli aplikacja używa app podpisywanie przez Google Play, skopiuj 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łączonych do języka Java w celu wydrukowania informacji o certyfikacie w formacie czytelnym dla człowieka. Skopiuj SHA1 w sekcji Certificate fingerprints parametru Dane wyjściowe narzędzia keytool. Zobacz Uwierzytelnianie klienta w Dokumentacja interfejsów API Google na Androida.
5. (Opcjonalnie) Potwierdź własność urządzenia z Androidem aplikacji.
6. Kliknij Utwórz.

iOS

1. Wybierz typ aplikacji iOS.
2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page identyfikacji klienta.
3. Podaj identyfikator pakietu aplikacji. Identyfikator pakietu to wartość atrybutu CFBundleIdentifier w pliku zasobów listy właściwości informacji o aplikacji (info.plist). Wartość jest najczęściej wyświetlany w panelu Ogólne lub w sekcji Signing & Okienko funkcji Edytor projektów Xcode. Identyfikator pakietu jest też wyświetlany w sekcji Informacje ogólne w stronie z informacjami o aplikacji witrynie App Store Connect firmy Apple.
4. (Opcjonalnie)

   Wpisz identyfikator App Store swojej aplikacji, jeśli została ona opublikowana w sklepie App Store firmy Apple. Identyfikator sklepu to do każdego adresu URL w Apple App Store.

   1. Otwórz aplikację Aplikacja Apple App Store na urządzeniu z iOS lub iPadOS.
   2. Wyszukaj swoją aplikację.
   3. Kliknij przycisk Udostępnij (kwadrat i strzałka w górę).
   4. Wybierz 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. (Opcjonalnie)

   Wpisz identyfikator zespołu. Zobacz Znajdź swój identyfikator zespołu w dokumentacji konta dewelopera Apple.

6. Kliknij Utwórz.

UWP

1. Wybierz typ aplikacji Platforma uniwersalna Windows.
2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page identyfikacji klienta.
3. Wpisz 12-znakowy identyfikator Microsoft Store swojej aplikacji. Tę wartość znajdziesz tutaj: Centrum Partnerów Microsoft w 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, platforma UWP)

Niestandardowe schematy URI to forma precyzyjnych linków, które używają niestandardowego schematu otwierającego aplikację.

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

. Alternatywa dla używania niestandardowych schematów URI na Androidzie

Użyj Pakiet SDK do logowania przez Google na Androida który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując konieczność stosowania identyfikator URI przekierowania.

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

Jeśli obecnie do integracji OAuth na Androidzie używasz schematu niestandardowego, musisz wykonaj poniższe działania, aby w pełni przejść na zalecane Logowanie przez Google w domenie Pakiet SDK na Androida:

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

.

Uwaga: należy dokończyć i wdrożyć aktualizacje kodu (uwzględniając czas wdrożenia użytkowników i starszych urządzeń) przed wyłączeniem obsługi schematów niestandardowych Konsola interfejsów API Google, dzięki której użytkownicy nie będą otrzymywać Komunikat o błędzie invalid_request gdy próbują użyć Twojej aplikacji.

Wykonaj te czynności, aby przejść na pakiet SDK funkcji Google Sign-In na Androida:

1. Zaktualizuj kod, aby używać pakietu SDK funkcji Google Sign-In na Androida:
   1. Przeanalizuj swój kod, aby określić, gdzie się znajdujesz wysyłanie żądania na serwer Google OAuth 2.0; W przypadku korzystania ze 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 parametrze powyżej. Zobacz Definicja parametru redirect_uri, aby uzyskać więcej informacji o formacie wartości niestandardowego schematu URI.
   2. Zwróć uwagę na parametry żądania scope i client_id, które musisz skonfigurować pakiet Google Sign-In SDK.
      Uwaga: jeśli używasz biblioteki innej firmy, zapoznaj się z jej .
   3. Postępuj zgodnie z Zacznij integrować logowanie przez Google z aplikacją na Androida jak skonfigurować pakiet SDK. Możesz pominąć Pobierz identyfikator klienta OAuth 2.0 serwera backendu, tak jak w przypadku ponownego użycia wartość client_id otrzymaną w poprzednim kroku.
   4. Postępuj zgodnie z Włączam dostęp do interfejsu API po stronie serwera za instrukcje. W tym celu:
      1. Użyj metody getServerAuthCode, aby pobrać kod autoryzacji dla platformy zakresy, do których chcesz uzyskać uprawnienia.
      2. Wyślij kod autoryzacji do backendu aplikacji, aby wymienić go na dostęp odświeżyć token.
      3. Używanie pobranego tokena dostępu do wywoływania interfejsów API Google w imieniu użytkownika.
      .
      Uwaga: jeśli Twoja aplikacja nie wymaga dostępu offline, postępuj zgodnie z 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. Przejdź do Dane logowania OAuth 2.0 i wybierz swojego klienta na Androida.
   2. Przejdź do sekcji Ustawienia zaawansowane i odznacz pole wyboru Włącz niestandardowy schemat URI, a potem kliknij Zapisz w wyłączyć obsługę niestandardowego schematu URI.

Włączam niestandardowy schemat URI

Jeśli nie działa zalecana alternatywa, możesz włączyć niestandardowe schematy URI w swojej witrynie klienta na Androida, postępując zgodnie z instrukcjami poniżej:

1. Przejdź do listę danych logowania OAuth 2.0 oraz wybierz klienta na Androida.
2. Przejdź do sekcji Ustawienia zaawansowane, sprawdź pole wyboru Włącz niestandardowy schemat URI, a potem kliknij Zapisz, aby go włączyć. obsługę niestandardowego schematu URI.

. Alternatywa dla używania niestandardowych schematów URI w aplikacjach Chrome

Użyj Interfejs Chrome Identity API który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując konieczność stosowania identyfikator URI przekierowania.

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

Aby zmniejszyć ryzyko podszywania się pod inne osoby, możesz potwierdzić własność aplikacji.

Android

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

Aby dokończyć proces weryfikacji, możesz użyć konta dewelopera w Google Play jeśli masz taką funkcję i Twoja aplikacja jest zarejestrowana Konsola Google Play. Poniżej wymagania dotyczące weryfikacji:

• W Konsoli Google Play musisz mieć zarejestrowaną aplikację z takim samym kontem nazwa pakietu i odcisk cyfrowy certyfikatu podpisywania SHA-1 jako klienta OAuth na Androida, którym jesteś przechodząc proces weryfikacji.
• Musisz mieć uprawnienia administratora w aplikacji na Konsola Google Play. Więcej informacji o zarządzaniu dostępem w Konsoli Google Play.

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

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

Aby rozwiązać problem z weryfikacją, która się nie powiodła, wykonaj te czynności:

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

Chrome

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

• Musisz mieć zarejestrowany produkt w Panel dewelopera Chrome Web Store z tym samym identyfikatorem elementu co klient OAuth rozszerzenia do Chrome, którego wykonujesz weryfikacji domeny.
• Musisz być wydawcą elementu w Chrome Web Store. Więcej informacji o zarządzaniu dostępem w Panelu dewelopera Chrome Web Store.

W sekcji Weryfikacja własności aplikacji klienta rozszerzeń do Chrome kliknij kliknij przycisk Zweryfikuj własność, aby zakończyć proces weryfikacji.

Uwaga: odczekaj kilka minut, zanim ukończysz proces weryfikacji. przyznawanie dostępu do konta.

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

Aby rozwiązać problem z weryfikacją, która się nie powiodła, wykonaj te czynności:

• Upewnij się, że w panelu dewelopera Chrome Web Store jest zarejestrowany produkt z taki sam identyfikator produktu jak klient OAuth rozszerzenia do Chrome, w którego przypadku przechodzisz weryfikację.
• Upewnij się, że jesteś wydawcą aplikacji, tzn. musisz być indywidualnym wydawcą należy do wydawcy grupowego aplikacji lub należy do wydawcy tej aplikacji. Więcej informacji o zarządzaniu dostępem w Panelu dewelopera Chrome Web Store.
• Jeśli lista wydawców grupowych została właśnie zaktualizowana, sprawdź, czy członkostwo wydawcy grupowego jest synchronizowana z panelem dewelopera Chrome Web Store. Więcej informacji o synchronizowaniu listy członkostwa wydawcy.

Adres IP sprzężenia zwrotnego (macOS, Linux, komputer z systemem Windows)

Ważne: opcja przekierowania adresu IP w pętli WYCOFANY w przypadku klientów OAuth na Androida, aplikację Chrome i iOS. Sprawdź adres IP zapętleń przewodnik po migracji adresów, w którym znajdziesz instrukcje przejścia na obsługiwaną alternatywę.

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

Gdy aplikacja otrzyma odpowiedź autoryzacyjną, powinna udzielić odpowiedzi do wyświetlając stronę HTML z instrukcjami, jak zamknąć przeglądarkę i wrócić do aplikacji.

Zalecane użycie	Aplikacje komputerowe w systemach macOS, Linux i Windows (ale nie na platformy Universal Windows Platform)
Wartości formularza	Ustaw typ aplikacji na Aplikacja komputerowa.

Uwaga: zapoznaj się z Definicja parametru redirect_uri dla możesz uzyskać więcej informacji na temat adresu IP sprzężenia zwrotnego. Możesz też użyć funkcji localhost zamiast adresu IP pętli, ale ta konfiguracja może powodować problemy z zapory sieciowe klienta. Większość zapór sieciowych, ale nie wszystkie, umożliwia komunikację w pętli.

Ręczne kopiowanie i wklejanie

Ważne: opcja ręcznego kopiowania i wklejania, zwana też jest metoda przekierowania poza zakresem (OOB), . nie są już obsługiwane. Zapoznaj się z przewodnikiem po migracji OOB. , aby dowiedzieć się, jak przejść na bezpieczną alternatywę.

Określanie zakresów dostępu

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

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

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

Dokument Zakresy interfejsu API OAuth 2.0 zawiera pełne listę zakresów, których możesz używać do uzyskiwania dostępu do interfejsów API Google.

Jeśli Twoja aplikacja publiczna używa zakresów, które zezwalają na dostęp do określonych danych użytkownika, musi przejść proces weryfikacji. Jeśli widzisz komunikat Nie zweryfikowano widoczne na ekranie podczas testowania aplikacji, o jego usunięcie. Więcej informacji: niezweryfikowane aplikacje i uzyskuj odpowiedzi na pytania: z odpowiedziami na najczęstsze pytania dotyczące weryfikacji aplikacji w Centrum pomocy.

Uzyskiwanie tokenów dostępu OAuth 2.0

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

Krok 1. Wygeneruj weryfikator kodu i test zabezpieczający

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

Tworzenie weryfikatora kodu

code_verifier to kryptograficzny ciąg losowy o wysokiej entropii wykorzystujący niezarezerwowane wartości znaki [A–Z] / [a–z] / [0–9] / „-” / . / „_” / „~”; minimalna długość 43 znaków o maksymalnej długości 128 znaków.

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

Utwórz zadanie związane z kodem

Obsługiwane są 2 metody tworzenia zadania zabezpieczającego kod.

Metody generowania wyzwania dotyczącego kodu
S256 (zalecany)	Wyzwaniem jest użycie skrótu SHA256 w formacie Base64URL (bez dopełnienia). weryfikatora. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
zwykła	Wyzwanie kodu ma taką samą wartość jak wygenerowany powyżej weryfikator kodu. code_challenge = code_verifier

Krok 2. Wyślij żądanie na serwer OAuth 2.0 Google

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

Serwer autoryzacji obsługuje następujące parametry ciągu zapytania w przypadku instalacji aplikacje:

Parametry
client_id	Wymagany Identyfikator klienta aplikacji. Tę wartość znajdziesz w sekcji API Console Credentials page
redirect_uri	Wymagany Określa, w jaki sposób serwer autoryzacji Google wysyła odpowiedź do Twojej aplikacji. Istnieją dostępnych aplikacji przekierowania. Ty skonfigurujesz dane logowania do autoryzacji za pomocą określonej metody przekierowania pod uwagę. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania protokołu OAuth 2.0 skonfigurowany na koncie klienta API Console Credentials pageJeśli ta wartość nie pasuje do parametru autoryzowany identyfikator URI, wystąpi błąd redirect_uri_mismatch. W tabeli poniżej znajdziesz odpowiednią wartość parametru redirect_uri dla: każdej z tych metod: 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 odwrotny zapis DNS domeny w domenie mają większą kontrolę. Schemat niestandardowy musi zawierać kropkę. com.googleusercontent.apps.123 to odwrotny zapis DNS funkcji identyfikatora klienta. redirect_uri_path to opcjonalny komponent ścieżki, taki jak /oauth2redirect Pamiętaj, że ścieżka powinna zaczynać się od , 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 urządzeniach z Androidem. Więcej informacji o alternatywach schematów niestandardowych w aplikacjach na Androida i 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 pętli i uruchom żądanie HTTP na losowym dostępnym porcie. Zastąp port rzeczywistą wartością numer portu, na którym nasłuchuje Twoja aplikacja. Pamiętaj, że obsługa opcji przekierowania adresu IP w pętli na urządzeniach mobilnych WYCOFANY.
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 O rozdzielane spacjami lista zakresów identyfikujących zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Wartości te informują o ekranie zgody, który Google wyświetla użytkownika. Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych zasobów a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu aplikacji. Dlatego występuje odwrotna zależność między liczbą żądanych zakresów oraz prawdopodobieństwo uzyskania zgody użytkownika.
code_challenge	Zalecane Określa zakodowany plik code_verifier, który będzie używany po stronie serwera w trakcie wymiany kodu autoryzacji. Zobacz utwórz kod wyzwania powyżej, aby dowiedzieć się więcej.
code_challenge_method	Zalecane Określa metodę używaną do kodowania elementu code_verifier, który zostanie użyty podczas wymiany kodu autoryzacji. Tego parametru należy używać razem z funkcją code_challenge parametr opisany powyżej. Wartość atrybutu code_challenge_method domyślna wartość to plain, jeśli nie ma go w żądaniu zawierającym code_challenge Jedyne obsługiwane wartości tego parametru to S256 lub plain.
state	Zalecane Określa dowolną wartość ciągu, której aplikacja używa do utrzymywania stanu między i odpowiedzi serwera autoryzacji. Serwer zwraca dokładną wartość, która została wysłana jako para name=value w polu Identyfikator fragmentu adresu URL (#) z redirect_uri, gdy użytkownik wyrazi zgodę na o dostęp. Tego parametru możesz używać do różnych celów, takich jak kierowanie użytkownika do parametru prawidłowe zasoby w aplikacji, wysyłanie żądań jednorazowych i ograniczanie żądań z innych witryn fałszerstwa. redirect_uri można odgadnąć, więc przy użyciu funkcji state możesz zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia. Jeśli generujesz losowy ciąg lub zakodujesz hasz pliku cookie lub innej wartości, która przechwytuje stan klienta, możesz zweryfikować odpowiedź dodatkowo upewnij się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki, które zapewniają ochronę przed atakami takimi jak żądanie z innej witryny fałszerstwa. Zobacz OpenID Connect dokumentację zawierającą przykład tworzenia i potwierdzania tokena state. Ważne: klient OAuth musi blokować żądanie CSRF zgodnie z informacją Specyfikacja protokołu OAuth2 Można to osiągnąć na przykład za pomocą parametru state, który pozwala utrzymać stan między żądaniem autoryzacji a odpowiedzią serwera autoryzacji.
login_hint	Opcjonalny Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru aby podać wskazówkę dla serwera uwierzytelniania Google. Serwer używa podpowiedzi do uprość proces logowania, wstępnie wypełniając pole adresu e-mail w formularzu wybór odpowiedniej sesji wielokrotnego logowania. Ustaw wartość parametru na adres e-mail lub identyfikator sub, który jest odpowiadający identyfikatorowi Google użytkownika.

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

Przykładowe autoryzacyjne adresy URL

Poniższe karty zawierają przykładowe adresy URL autoryzacji dla różnych opcji identyfikatora URI przekierowania.

Adresy URL są identyczne z wyjątkiem wartości parametru redirect_uri. Adresy URL zawierają też wymagane parametry response_type i client_id jako opcjonalny parametr state. Każdy URL zawiera podziały wierszy i spacje dla i czytelność.

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ę

Na tym etapie użytkownik decyduje, czy przyznać aplikacji dostęp, o który prosisz. W tym miejscu Google wyświetla okno z prośbą o zgodę, w którym wyświetla się nazwa aplikacji i interfejs API Google usług, do których żąda dostępu za pomocą danych uwierzytelniających użytkownika podsumowanie zakresów dostępu, jakie należy przyznać. użytkownik może wyrazić zgodę na przyznanie dostępu do co najmniej jednego zakresu żądanego przez aplikację lub odrzucić tę prośbę.

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

Błędy

Żądania wysyłane do punktu końcowego autoryzacji OAuth 2.0 Google mogą wyświetlać komunikaty o błędach widoczne dla użytkowników zamiast oczekiwanych procesów uwierzytelniania i autoryzacji. Typowe i zalecane kody błędów rozwiązanie problemu znajdziesz poniżej.

admin_policy_enforced

Konto Google nie może autoryzować co najmniej jednego żądanego zakresu ze względu na zasady swoim administratorem Google Workspace. Przeczytaj artykuł pomocy dla administratorów Google Workspace Kontroluj, które zewnętrzne aplikacje wewnętrzne uzyskują dostęp do danych Google Workspace znajdziesz więcej informacji o tym, jak administrator może ograniczać dostęp do wszystkich zakresów lub zakresy z ograniczeniami, dopóki nie zostanie jednoznacznie przyznany dostępowi do identyfikatora klienta OAuth.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany w osadzonym kliencie użytkownika niedozwolonym przez Zasady dotyczące protokołu 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 Logowanie przez Google na Androidzie lub OpenID Foundation AppAuth na Androida.

Deweloperzy stron internetowych mogą napotkać ten błąd, gdy aplikacja na Androida otwiera ogólny link internetowy w osadzony klient użytkownika, a użytkownik przechodzi do punktu końcowego autoryzacji OAuth 2.0 Google w Twojej witrynie. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który zawiera Linki aplikacji na Androida modułów obsługi lub domyślnej aplikacji do przeglądania internetu. Karty niestandardowe na Androida .

iOS

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

Deweloperzy stron internetowych mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otworzy ogólny link internetowy w osadzony klient użytkownika, a użytkownik przechodzi do punktu końcowego autoryzacji OAuth 2.0 Google w Twojej witrynie. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który zawiera Uniwersalne linki modułów obsługi lub domyślnej aplikacji do przeglądania internetu. SFSafariViewController. .

org_internal

Identyfikator klienta OAuth w żądaniu jest częścią projektu ograniczającego dostęp do kont Google w konkretne Organizacja Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w Typ użytkownika w artykule pomocy „Konfigurowanie ekranu zgody OAuth”.

invalid_grant

Jeśli używasz weryfikator kodu wyzwanie, parametr code_callenge jest nieprawidłowy lub go brakuje. Upewnij się, że parametr Parametr code_challenge jest ustawiony prawidłowo.

Podczas odświeżania tokena dostępu token mógł wygasnąć lub mieć została unieważniona. Uwierzytelnij użytkownika ponownie i poproś o zgodę na uzyskanie nowych tokenów. Jeśli kontynuujesz w przypadku tego błędu. Upewnij się, że aplikacja została poprawnie skonfigurowana używając prawidłowych tokenów i parametrów w żądaniu. W przeciwnym razie konto użytkownika mogło mieć została usunięta lub wyłączona.

redirect_uri_mismatch

redirect_uri przekazany w żądaniu autoryzacji nie jest zgodny z autoryzowanym URI przekierowania dla identyfikatora klienta OAuth. Przejrzyj autoryzowane identyfikatory URI przekierowania w Google API Console Credentials page.

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

Parametr redirect_uri może odnosić się do zewnętrznego przepływu OAuth, w którym zastosowano została wycofana i nie jest już obsługiwana. Zapoznaj się z przewodnik po migracji, by zaktualizować i integrację społeczną.

invalid_request

Coś poszło nie tak z Twoją prośbą. Możliwych jest kilka przyczyn tej sytuacji:

• Żądanie było nieprawidłowo sformatowane
• W żądaniu brakowało wymaganych parametrów
• Żądanie używa metody autoryzacji, której Google nie obsługuje. Zweryfikuj OAuth integracja korzysta z zalecanej metody integracji
• Dla przekierowania URI jest używany schemat niestandardowy : jeśli jest wyświetlany komunikat o błędzie Niestandardowy schemat URI nie jest obsługiwany w aplikacjach Chrome ani niestandardowy schemat URI nie jest włączone dla Twojego klienta na Androida, oznacza to, że używasz niestandardowego identyfikatora URI schemat, który nie jest obsługiwany w aplikacjach Chrome i jest domyślnie wyłączony, na urządzeniu z Androidem. Dowiedz się więcej o niestandardowym schemacie URI inne możliwości

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

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

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

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

Aby wymienić kod autoryzacji na token dostępu, wywołaj metodę https://oauth2.googleapis.com/token i ustaw te parametry:

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 z pierwszego żądania.
code_verifier	Utworzony przez Ciebie weryfikator kodu Krok 1.
grant_type	Zgodnie z definicją w protokole OAuth 2.0 specyfikacji, wartość tego pola musi być ustawiona na authorization_code.
redirect_uri	Jeden z identyfikatorów URI przekierowania wymienionych w projekcie API Console Credentials page dla danego client_id

Oto przykładowy fragment kodu:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google w odpowiedzi na to żądanie zwraca obiekt JSON z dostępem krótkotrwałym. token i token odświeżania.

Odpowiedź zawiera te pola:

Pola
access_token	Token wysyłany przez aplikację do autoryzowania żą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, na przykład openid, profile lub email. Wartość to Token internetowy 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 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 ciągów tekstowych rozdzielanych spacjami, w których wielkość liter ma znaczenie.
token_type	Typ zwróconego tokena. Obecnie wartość tego pola jest zawsze ustawiona na Bearer

Ważne: aplikacja powinna przechowywać oba tokeny w bezpiecznym dane o długotrwałej 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 został wygasa. W związku z tym, jeśli aplikacja utraci token odświeżania, użytkownik będzie musiał powtórzyć proces uzyskiwania zgody OAuth 2.0, aby Twoja 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ć nierozpoznane pola zawarte w odpowiedź.

Wywoływanie interfejsów API Google

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

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

Przykłady żądań HTTP GET

Wywołanie funkcji drive.files (interfejs Drive Files API) korzystający z protokołu HTTP Authorization: Bearer nagłówek może wyglądać tak: Pamiętaj, że musisz podać własny token dostępu:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Oto wywołanie tego samego interfejsu API dla uwierzytelnionego użytkownika za pomocą interfejsu access_token parametr ciągu zapytania:

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

curl przykładu

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Możesz też użyć opcji parametru ciągu zapytania:

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

Odświeżanie tokena dostępu

Tokeny dostępu okresowo tracą ważność i stają się nieprawidłowymi danymi logowania dla powiązanego żądania do interfejsu API. Ty może odświeżać token dostępu bez pytania użytkownika o zgodę (także wtedy, gdy nie występuje), jeśli została wysłana prośba o dostęp offline do zakresów powiązanych z tokenem.

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

Pola
client_id	Identyfikator klienta uzyskany z API Console.
client_secret	Tajny klucz klienta uzyskany z API Console. (dokument client_secret nie ma zastosowania w przypadku żądań od klientów zarejestrowanych jako w aplikacjach na Androida, iOS lub Chrome).
grant_type	Jako zdefiniowane w specyfikacja protokołu 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.

Oto przykładowy fragment kodu:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

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

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

Pamiętaj, że liczba przyznanych tokenów odświeżania jest ograniczona. jeden limit na kombinacja klient/użytkownik oraz inna kombinacja na użytkownika w przypadku wszystkich klientów. Należy zapisać tokeny odświeżania do przechowywania długoterminowego i używać ich, dopóki są ważne. Jeśli Twoja aplikacja żąda zbyt wielu tokenów odświeżania, mogą wystąpić te limity. W takim przypadku starsze tokeny odświeżania przestanie działać.

Unieważnianie tokena

W niektórych przypadkach użytkownik może cofnąć dostęp przyznany aplikacji. Użytkownik może anulować dostęp odwiedzając stronę Ustawienia konta. Zobacz Usuń sekcji dostępu do witryny lub aplikacji na stronie Witryny innych firm aplikacje, które mają dostęp do Twojego konta dokumentu pomocy, aby dowiedzieć się więcej.

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

Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i zawiera token jako parametr:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Tokenem może być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma parametr token odświeżania, token odświeżania również zostanie unieważniony.

Jeśli odwołanie zostanie przetworzone, kod stanu HTTP odpowiedzi będzie miał postać 200 W przypadku wystąpienia błędu zwracany jest kod stanu HTTP 400. z kodem błędu.

Uwaga: po pomyślnej odpowiedzi na odwołanie może minąć trochę czasu zanim wycofanie zacznie obowiązywać.

Dalsza lektura

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

Wdrażanie Ochrony wszystkich kont

Dodatkowy krok, który musisz wykonać, aby chronić użytkowników Liczba kont, na których jest zaimplementowane kilka kont ochrony dzięki korzystaniu z oferowanej przez Google usługi ochrony wszystkich kont. Ta usługa pozwala subskrybować powiadomienia o zdarzeniach związanych z bezpieczeństwem, które dostarczają do aplikacji informacje na temat: na koncie użytkownika. Następnie możesz wykorzystać te informacje do podjęcia działań w zależności od tego, podejmowania decyzji o reagowaniu na zdarzenia.

Oto kilka przykładów typów zdarzeń wysyłanych do Twojej aplikacji przez usługę ochrony wszystkich kont Google:

• 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

Zobacz Ochrona kont użytkowników za pomocą strony Ochrona wszystkich kont . , aby dowiedzieć się więcej o wdrażaniu Ochrony wszystkich kont i pełnej listy dostępnych zdarzeń.