OAuth 2.0 na potrzeby aplikacji mobilnych i komputerowych

Z tego dokumentu dowiesz się, jak aplikacje zainstalowane na urządzeniach takich jak telefony, tablety i komputery używają punktów końcowych OAuth 2.0 Google do autoryzowania dostępu do interfejsu YouTube Data API.

Protokół OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy jednoczesnym zachowaniu prywatności nazw użytkowników, haseł i innych informacji. Aplikacja może na przykład korzystać z protokołu OAuth 2.0, aby uzyskać uprawnienia do przesyłania filmów na kanał użytkownika w YouTube.

Zainstalowane aplikacje są rozpowszechniane na poszczególnych urządzeniach i zakłada 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.

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ę systemową i dostarczyć lokalny identyfikator URI przekierowania do obsługi odpowiedzi z serwera autoryzacji Google.

Alternatywy

W przypadku aplikacji mobilnych możesz korzystać z Logowania przez Google na Androida lub iOS. Biblioteki klienta Logowania przez Google obsługują uwierzytelnianie i autoryzację użytkowników, więc ich implementacja może być prostsze niż opisany tutaj protokół niższego poziomu.

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

Biblioteki i próbki

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 API w: API Console.

Aby włączyć interfejs API w projekcie:

  1. Open the API Library w: Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Na stronie Biblioteka znajdź i włącz interfejs YouTube Data API. Znajdź wszystkie inne interfejsy API, których będzie używać Twoja aplikacja, i je włącz.

Tworzenie danych uwierzytelniających

Każda aplikacja korzystająca z OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google musi mieć dane uwierzytelniające, które identyfikują aplikację z serwerem Google OAuth 2.0. Podane niżej kroki wyjaśniają, jak utworzyć dane logowania w projekcie. Aplikacje mogą dzięki temu używać tych danych logowania, aby uzyskiwać dostęp do interfejsów API włączonych w danym 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 w przypadku Twojej aplikacji, nadaj mu nazwę i ustaw odpowiednie pozostałe pola w formularzu.
Android
  1. Wybierz typ aplikacji Android.
  2. Wpisz nazwę klienta OAuth. Jest wyświetlana w panelu Credentials page Twojego projektu, aby umożliwić identyfikację klienta.
  3. Wpisz nazwę pakietu aplikacji na Androida. Ta wartość jest zdefiniowana w atrybucie package elementu <manifest> w pliku manifestu aplikacji.
  4. Wpisz odcisk cyfrowy certyfikatu podpisującego SHA-1 dystrybucji aplikacji.
    • Jeśli Twoja aplikacja korzysta z podpisywania aplikacji przez Google Play, skopiuj odcisk cyfrowy SHA-1 ze strony podpisywania aplikacji w Konsoli Play.
    • Jeśli zarządzasz własnym magazynem kluczy i kluczami podpisywania, użyj narzędzia keytool dołączonego do języka Java, 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. Jest wyświetlana w panelu 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 funkcje w edytorze projektów 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)

    Jeśli aplikacja została opublikowana w App Store firmy Apple, podaj jej identyfikator w sklepie App Store. Identyfikator sklepu to ciąg liczbowy występujący w każdym adresie URL w Apple App Store.

    1. Otwórz aplikację 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. (Opcjonalne)

    Wpisz identyfikator zespołu. Więcej informacji znajdziesz w artykule o znajdowaniu 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. Jest wyświetlana w panelu Credentials page Twojego projektu, aby umożliwić identyfikację klienta.
  3. Wpisz 12-znakowy identyfikator aplikacji w Microsoft Store. 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 URI (Android, iOS, UWP)

Niestandardowe schematy URI to formy precyzyjnych linków, w których do otwierania aplikacji używane są niestandardowe schematy.

Alternatywa dla niestandardowych schematów URI na Androidzie

Użycie pakietu Google Sign-In for Android SDK, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując potrzebę stosowania 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 korzystanie z zalecanego pakietu SDK logowania Google na Androida:

  1. Zaktualizuj kod, aby używać pakietu SDK logowania Google.
  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 korzystać z 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 w przykładzie niestandardowy identyfikator URI przekierowania schematu. 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óre potrzebujesz do skonfigurowania pakietu SDK logowania Google.
    3. Postępuj zgodnie z instrukcjami rozpoczynania integracji logowania przez Google z aplikacją na Androida, aby skonfigurować pakiet SDK. Możesz pominąć krok pobierania identyfikatora klienta OAuth 2.0 serwera backendu, ponieważ w innym przypadku możesz użyć client_id pobranego z poprzedniego kroku.
    4. Postępuj zgodnie z instrukcjami włączania dostępu do interfejsu API po stronie serwera. Obejmuje to m.in.:
      1. Użyj metody getServerAuthCode, aby pobrać kod autoryzacji dla zakresów, do których chcesz uzyskać uprawnienia.
      2. Wyślij kod autoryzacji do backendu aplikacji, aby wymienić go na token dostępu i odświeżania.
      3. Użyj pobranego tokena dostępu 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ę Dane logowania 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 dla klienta na Androida, wykonując te czynności:
  1. Otwórz listę Dane logowania 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ę niestandardowego schematu URI.
Alternatywa dla niestandardowych schematów URI w aplikacjach Chrome

Użycie interfejsu Chrome Identity API, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując potrzebę stosowania 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łnić te wymagania:

  • Musisz mieć zarejestrowaną aplikację w Konsoli Google Play z tą samą nazwą pakietu i odciskiem cyfrowym certyfikatu podpisującego SHA-1 co klient OAuth na Androida, którego dotyczy weryfikacja.
  • 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 na Androida kliknij przycisk Zweryfikuj własność, aby zakończyć proces weryfikacji.

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

Aby poprawić nieudaną weryfikację:

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

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

  • Musisz mieć zarejestrowany produkt w panelu dewelopera Chrome Web Store o tym samym identyfikatorze co klient 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.

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

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

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

Aby poprawić nieudaną weryfikację:

  • Sprawdź, czy w panelu dewelopera Chrome Web Store występuje zarejestrowany produkt z tym samym identyfikatorem co klient OAuth rozszerzenia do Chrome, którego dotyczy weryfikacja.
  • Upewnij się, że jesteś wydawcą aplikacji, tzn. 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 lista wydawców grupy została przed chwilą zaktualizowana, sprawdź w panelu dewelopera Chrome Web Store, czy jest ona synchronizowana. Dowiedz się więcej o synchronizowaniu listy członków wydawcy.

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

Aby możliwe było odebranie kodu autoryzacji przy użyciu tego adresu URL, aplikacja musi nasłuchiwać na lokalnym serwerze WWW. Jest to możliwe na wielu platformach. Jeśli jednak Twoja platforma go obsługuje, jest to zalecany sposób uzyskania kodu autoryzacji.

Gdy aplikacja otrzymuje odpowiedź autoryzacji, dla wygody powinna w odpowiedzi wyświetlić stronę HTML z instrukcjami, aby zamknąć przeglądarkę i wrócić do aplikacji.

Zalecane wykorzystanie aplikacje komputerowe w systemie macOS, Linux i Windows (ale nie na platformie Universal Windows Platform);
Wartości formularza Jako typ aplikacji wybierz Aplikacja komputerowa.

Ręczne kopiowanie i wklejanie

Identyfikowanie zakresów dostępu

Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych zasobów, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu, który przyznają aplikacji. Z tego powodu może występować odwrotny związek między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Przed rozpoczęciem implementacji autoryzacji OAuth 2.0 zalecamy wskazanie zakresów, do których aplikacja będzie potrzebować uprawnień.

Interfejs YouTube Data API w wersji 3 używa tych zakresów:

Zakresy
https://www.googleapis.com/auth/youtubeZarządzanie kontem YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creatorWyświetlanie listy aktualnie aktywnych użytkowników wspierających kanał, ich obecnych poziomów i dat rozpoczęcia wsparcia
https://www.googleapis.com/auth/youtube.force-sslPrzeglądanie, edytowanie i trwałe usuwanie Twoich filmów, ocen, komentarzy i napisów z YouTube
https://www.googleapis.com/auth/youtube.readonlyWyświetlanie konta YouTube
https://www.googleapis.com/auth/youtube.uploadZarządzanie filmami w YouTube
https://www.googleapis.com/auth/youtubepartnerPrzeglądaj zasoby oraz powiązane treści i zarządzaj nimi w serwisie YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditPrzeglądanie prywatnych danych kanału YouTube istotnych podczas rozmowy z partnerem YouTube

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

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 wykonywać żądanie do interfejsu API Google wymagające autoryzacji użytkownika.

Krok 1. Wygeneruj weryfikatora kodu i test zabezpieczający

Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo przepływu instalacji zainstalowanej aplikacji. Dla każdego żądania autoryzacji tworzony jest unikalny weryfikator kodu, a jego przekształcona wartość (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 niezastrzeżone 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.

Tworzenie testu zabezpieczającego w postaci kodu

Obsługiwane są 2 metody tworzenia wyzwania w kodzie.

Metody generowania wyzwania dotyczącego kodu
S256 (zalecany) Wyzwanie kodu to zakodowany w Base64URL (bez dopełnienia) skrót SHA256 weryfikatora kodu.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
zwykły tekst Wyzwanie kodu ma taką samą wartość jak weryfikator kodu wygenerowany powyżej.
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 Wymagane

Identyfikator klienta aplikacji. Tę wartość znajdziesz w API Console Credentials page.

redirect_uri Wymagane

Określa, w jaki sposób serwer autoryzacji Google wysyła odpowiedź do Twojej aplikacji. Zainstalowane aplikacje mają do wyboru kilka opcji przekierowania. Musisz skonfigurować dane logowania autoryzacji pod kątem konkretnej 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 jest zgodna z autoryzowanym identyfikatorem 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

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app to odwrotny zapis DNS domeny, która jest pod Twoją kontrolą. Schemat niestandardowy musi zawierać kropkę, aby był prawidłowy.
  • 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 typu loopback i uruchom detektor 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 Wymagane

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

Ustaw wartość parametru na code dla zainstalowanych aplikacji.

scope Wymagane

Rozdzielona 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 wyświetlanym przez Google użytkownikowi.

Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych zasobów, a także pozwalają użytkownikom kontrolować zakres dostępu, który przyznają aplikacji. Dlatego istnieje odwrotny zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Interfejs YouTube Data API w wersji 3 używa tych zakresów:

Zakresy
https://www.googleapis.com/auth/youtubeZarządzanie kontem YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creatorWyświetlanie listy aktualnie aktywnych użytkowników wspierających kanał, ich obecnych poziomów i dat rozpoczęcia wsparcia
https://www.googleapis.com/auth/youtube.force-sslPrzeglądanie, edytowanie i trwałe usuwanie Twoich filmów, ocen, komentarzy i napisów z YouTube
https://www.googleapis.com/auth/youtube.readonlyWyświetlanie konta YouTube
https://www.googleapis.com/auth/youtube.uploadZarządzanie filmami w YouTube
https://www.googleapis.com/auth/youtubepartnerPrzeglądaj zasoby oraz powiązane treści i zarządzaj nimi w serwisie YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditPrzeglądanie prywatnych danych kanału YouTube istotnych podczas rozmowy z partnerem YouTube

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

code_challenge Zalecane

Określa zakodowany code_verifier, który będzie używany jako test zabezpieczający po stronie serwera podczas wymiany kodu autoryzacji. Więcej informacji znajdziesz powyżej, w sekcji o tworzeniu testu zabezpieczającego w postaci kodu.

code_challenge_method Zalecane

Określa metodę używaną do kodowania elementu code_verifier, który będzie używany podczas wymiany kodu autoryzacji. Tego parametru należy używać z parametrem code_challenge opisanym powyżej. Jeśli żądanie nie zawiera elementu code_challenge, wartość code_challenge_method przyjmuje domyślnie wartość plain. Jedyne obsługiwane wartości tego parametru to S256 i plain.

state Zalecane

Określa dowolną wartość ciągu znaków używaną przez aplikację 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 przekierowywania użytkownika do odpowiedniego zasobu w aplikacji, wysyłania liczb jednorazowych i łagodzenia fałszowania żądań między witrynami. Ponieważ redirect_uri można odgadnąć, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia. Jeśli wygenerujesz losowy ciąg znaków lub zakodujesz skrót pliku cookie bądź inną wartość, która przechwytuje stan klienta, możesz dodatkowo 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 tego, jak utworzyć i potwierdzić token 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 podać wskazówkę dla serwera uwierzytelniania Google. Serwer wykorzystuje wskazówkę, 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 identyfikatorów URI przekierowania.

Każdy adres URL wymaga dostępu do zakresu umożliwiającego przeglądanie konta YouTube użytkownika.

Adresy URL są identyczne z wyjątkiem wartości parametru redirect_uri. Adresy URL zawierają też wymagane parametry response_type i client_id oraz opcjonalny parametr state. Każdy adres URL zawiera podziały wierszy i spacje, aby zwiększyć czytelność.

Niestandardowy schemat identyfikatora URI

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 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ć aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody z nazwą aplikacji i usług Google API, do których chce uzyskać dostęp, za pomocą danych uwierzytelniających użytkownika. Zawiera też podsumowanie zakresów przyznanych dostępu. Użytkownik może następnie zgodzić się na przyznanie dostępu do co najmniej 1 zakresu żądanego przez Twoją aplikację lub odrzucić żądanie.

Na tym etapie aplikacja nie musi nic robić, ponieważ czeka na odpowiedź serwera Google OAuth 2.0 z informacją o przyznaniu dostępu. Tę odpowiedź wyjaśnimy poniżej.

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 jednego żądanego zakresu z powodu zasad jego administratora Google Workspace. Przeczytaj artykuł w Centrum pomocy Google Workspace dla administratorów 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, dopóki nie zostanie wyraźnie przyznany dostęp do Twojego identyfikatora klienta OAuth.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany wewnątrz osadzonego klienta użytkownika niedozwolony przez zasady OAuth 2.0 Google.

Android

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

Ten błąd może wystąpić, gdy aplikacja na Androida otwiera ogólny link internetowy we wbudowanym 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 w systemie operacyjnym, który obejmuje zarówno moduły obsługi linków aplikacji na Androida, jak i domyślną aplikację przeglądarki. Obsługiwana jest też biblioteka kart niestandardowych na Androida.

iOS

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

Programiści stron internetowych mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otwiera ogólny link internetowy w osadzonym 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 uwzględnia zarówno moduły obsługi uniwersalnych linków, jak i domyślną aplikację przeglądarki. Obsługiwana 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 Konfigurowanie ekranu zgody OAuth.

invalid_grant

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

Gdy odświeżasz token dostępu, token mógł wygasnąć lub został unieważniony. Uwierzytelnij ponownie użytkownika i poproś o zgodę na uzyskanie nowych tokenów. Jeśli ten błąd będzie się powtarzał, sprawdź, czy aplikacja została skonfigurowana poprawnie oraz czy w żądaniu używasz prawidłowych tokenów i parametrów. Jeśli tego nie zrobisz, konto użytkownika mogło zostać usunięte lub wyłączone.

redirect_uri_mismatch

Element redirect_uri przekazany w żądaniu autoryzacji nie pasuje do autoryzowanego identyfikatora URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania w pliku 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 poza zakresem protokołu OAuth (OOB), który został wycofany i nie jest już obsługiwany. Informacje o tym, jak zaktualizować integrację, znajdziesz w przewodniku po migracji.

invalid_request

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

  • Żądanie nie było prawidłowo sformatowane
  • W żądaniu brakuje wymaganych parametrów
  • Żądanie używa metody autoryzacji, która nie jest obsługiwana przez Google. Sprawdź, czy integracja OAuth używa zalecanej metody integracji
  • W przypadku identyfikatora URI przekierowania używany jest schemat niestandardowy : jeśli zobaczysz komunikat o błędzie Niestandardowy schemat URI nie jest obsługiwany w aplikacjach Chrome lub Niestandardowy schemat URI nie jest 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 alternatywnych schematach URI

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacji, zależy od używanego 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, jak opisano 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 Tajny klucz klienta uzyskany z API Console Credentials page.
code Kod autoryzacji zwrócony z początkowego żądania.
code_verifier Weryfikator kodu utworzony w kroku 1.
grant_type Zgodnie ze specyfikacją OAuth 2.0 wartość tego pola musi być ustawiona na authorization_code.
redirect_uri Jeden z identyfikatorów URI przekierowania Twojego projektu w polu API Console Credentials page dla wybranego zasobu client_id.

Ten fragment kodu pokazuje przykładowe żądanie:

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

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

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 życia 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), który zawiera cyfrowo podpisane informacje o tożsamości użytkownika.
refresh_token Token, za pomocą którego można uzyskać nowy token dostępu. Tokeny odświeżania są ważne do momentu unieważnienia dostępu przez użytkownika. Pamiętaj, że w przypadku zainstalowanych aplikacji zawsze są zwracane tokeny odświeżania.
scope Zakresy dostępu przyznane przez funkcję access_token, wyrażone w postaci listy ciągów rozdzielanych spacjami z uwzględnieniem wielkości liter.
token_type Typ zwracanego 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/youtube.force-ssl",
  "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 API Google w imieniu danego konta użytkownika, o ile został przyznany zakres dostępu wymagany przez interfejs API. Aby to zrobić, umieść 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ą zazwyczaj widoczne w logach serwera. W większości przypadków możesz użyć biblioteki klienta, aby skonfigurować wywołania interfejsów API Google (np. podczas wywoływania interfejsu YouTube Data API).

Pamiętaj, że interfejs YouTube Data API obsługuje konta usługi tylko dla właścicieli treści YouTube, którzy są właścicielami wielu kanałów YouTube i zarządzają nimi, np. wytwórniami płytowymi i studiami filmowymi.

Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w narzędziu OAuth 2.0 Playground.

Przykłady HTTP GET

Wywołanie punktu końcowego youtube.channels (YouTube Data API) przy użyciu nagłówka HTTP Authorization: Bearer może wyglądać tak. Pamiętaj, że musisz określić własny token dostępu:

GET /youtube/v3/channels?part=snippet&mine=true 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/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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 (preferowana):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Możesz też użyć opcji parametrów ciągu zapytania:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Odświeżanie tokena dostępu

Tokeny dostępu okresowo tracą ważność i stają się nieprawidłowymi danymi uwierzytelniającymi w przypadku powiązanego żądania do interfejsu API. Możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (również 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 Tajny klucz klienta uzyskany z API Console. (Pole client_secret nie ma zastosowania w przypadku żądań pochodzących od klientów zarejestrowanych jako aplikacje na Androida, iOS lub 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 pokazuje przykładowe żądanie:

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

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

Dopóki użytkownik nie anuluje dostępu przyznanego aplikacji, serwer tokenów zwraca 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 wystawionych tokenów odświeżania: 1 limit na kombinację klienta/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 pozostają ważne. Jeśli aplikacja żąda zbyt wielu tokenów odświeżania, może przekroczyć te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.

Unieważnianie tokena

W niektórych przypadkach użytkownik może zechcieć anulować dostęp przyznany aplikacji. Użytkownik może anulować dostęp w Ustawieniach konta. Więcej informacji znajdziesz w sekcji dotyczącej usuwania dostępu witryny lub aplikacji w dokumencie „Witryny i aplikacje innych firm, które mają dostęp do Twojego konta”.

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

Aby programowo unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i uwzględnia ten token jako parametr:

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

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

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

Dalsza lektura

Wiele opisanych tutaj sprawdzonych metod jest oparty na sprawdzonych metodach IETF protokołu OAuth 2.0 dla aplikacji natywnych.