OAuth 2.0 na potrzeby aplikacji mobilnych i komputerowych

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:

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.

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.

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

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)

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.

Ręczne kopiowanie i wklejanie

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.

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.

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

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.

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

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.

Dalsza lektura

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