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 YouTube Analytics API lub YouTube Reporting API.
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. Na przykład aplikacja może korzystać z OAuth 2.0, aby uzyskać pozwolenie na pobieranie danych kanału ze Statystyk YouTube.
Zainstalowane aplikacje są rozpowszechniane na poszczególnych urządzeniach. Zakładamy, że nie mogą zachowywać tajemnic. Mogą uzyskiwać dostęp do interfejsów API Google, gdy użytkownik jest w aplikacji lub gdy aplikacja działa w tle.
Ten proces autoryzacji jest podobny do procesu używanego w przypadku aplikacji serwerów WWW. Główna różnica polega na tym, że zainstalowane aplikacje muszą otwierać przeglądarkę systemową i podać identyfikator URI przekierowania lokalnego, aby obsługiwać odpowiedzi z serwera autoryzacji Google.
Alternatywy
W przypadku aplikacji mobilnych wolisz używać Logowania przez Google na Androidzie lub iOS. Biblioteki klienta logowania przez Google obsługują uwierzytelnianie i autoryzację użytkowników, a ich wdrożenie może być łatwiejsze niż opisany tutaj protokół niższego poziomu.
Informacje o aplikacjach działających na urządzeniach, które nie obsługują przeglądarki systemowej lub które mają ograniczone możliwości wprowadzania (np. telewizory, konsole do gier, kamery czy drukarki), znajdziesz w artykule o protokole OAuth 2.0 na telewizory i urządzenia lub Logowanie się na telewizorach i ograniczonych urządzeniach wejściowych.
Biblioteki i przykłady
Zalecamy skorzystanie z tych bibliotek i przykładów, które ułatwiają wdrożenie przepływu OAuth 2.0 opisanego w tym dokumencie:
- Biblioteka AppAuth na Androida
- Biblioteka AppAuth na iOS
- Protokół OAuth w aplikacjach: przykłady w systemie Windows
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 API Console.
Aby włączyć interfejs API w projekcie:
- Open the API Library w Google API Console.
- If prompted, select a project, or create a new one.
- Na stronie Biblioteka możesz znaleźć i włączyć interfejsy YouTube Analytics API oraz YouTube Reporting API. Wiele aplikacji pobierających dane ze Statystyk YouTube łączy się też z interfejsem YouTube Data API. Znajdź i włącz wszystkie inne interfejsy API, których będzie używać Twoja aplikacja.
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 znajdziesz instrukcje tworzenia danych logowania dla projektu. Aplikacje będą mogły używać tych danych logowania do uzyskiwania dostępu do interfejsów API włączonych w tym projekcie.
- Go to the Credentials page.
- Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
- W poniższych sekcjach opisano typy klientów i metody przekierowania obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nadaj mu nazwę i odpowiednio ustaw pozostałe pola w formularzu.
Android
- Wybierz typ aplikacji Android.
- Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projektu w celu identyfikacji klienta.
- Wpisz nazwę pakietu aplikacji na Androida. Ta wartość jest zdefiniowana w
atrybucie
package
elementu<manifest>
w pliku manifestu aplikacji. - Wpisz odcisk cyfrowy certyfikatu podpisywania 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 dostępnego w Javie narzędzia keytool, aby wydrukować informacje o certyfikatach w formacie zrozumiałym dla człowieka. Skopiuj wartość
SHA1
z sekcjiCertificate fingerprints
wyniku działania narzędzia keytool. Więcej informacji znajdziesz w sekcji Uwierzytelnianie klienta w dokumentacji interfejsów API Google na Androida.
- (Opcjonalnie) Potwierdź własność aplikacji na Androida.
- Kliknij Utwórz.
iOS
- Wybierz typ aplikacji iOS.
- Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projektu w celu identyfikacji klienta.
- Wpisz identyfikator pakietu aplikacji. Identyfikator pakietu to wartość klucza CFBundleIdentifier w pliku zasobów z listą właściwości informacji o aplikacji (info.plist). Wartość jest najczęściej wyświetlana w panelu Ogólne lub w panelu Signing & Capabilities w edytorze projektu Xcode. Identyfikator pakietu jest też wyświetlany w sekcji Informacje ogólne na stronie Informacje o aplikacji w witrynie App Store Connect firmy Apple.
- (Opcjonalne)
Wpisz identyfikator App Store swojej aplikacji, jeśli została ona opublikowana w sklepie App Store firmy Apple. Identyfikator sklepu to ciąg liczbowy dołączany do każdego adresu URL w Apple App Store.
- Otwórz aplikację Apple App Store na urządzeniu z iOS lub iPadOS.
- Wyszukaj swoją aplikację.
- Kliknij przycisk Udostępnij (kwadrat i strzałka w górę).
- Wybierz Kopiuj link.
- Wklej link do edytora tekstu. Identyfikator App Store to końcowa część adresu URL.
Przykład:
https://apps.apple.com/app/google/id284815942
- (Opcjonalne)
Wpisz identyfikator zespołu. Więcej informacji znajdziesz w sekcji Znajdowanie identyfikatora zespołu w dokumentacji konta Apple dla deweloperów.
- Kliknij Utwórz.
platforma UWP
- Wybierz typ aplikacji Platforma uniwersalna Windows.
- Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projektu w celu identyfikacji klienta.
- 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.
- 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ę.
Alternatywa dla używania niestandardowych schematów URI na AndroidzieUżyj pakietu SDK Zaloguj się przez Google na Androida, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do Twojej aplikacji, eliminując konieczność stosowania identyfikatora URI przekierowania.
Jak przejść na pakiet SDK funkcji Google Sign-In na Androida
Jeśli obecnie do integracji protokołu OAuth na Androidzie używasz schematu niestandardowego, musisz wykonać poniższe działania, aby w pełni przejść na zalecany pakiet SDK Logowania przez Google:
- Zaktualizuj kod, aby używać pakietu SDK logowania przez Google.
- Wyłącz obsługę schematu niestandardowego w konsoli interfejsów API Google.
Wykonaj te czynności, aby przejść na pakiet SDK funkcji Google Sign-In na Androida:
-
Zaktualizuj kod, aby używać pakietu SDK funkcji Google Sign-In na Androida:
-
Sprawdź swój kod, aby określić, gdzie wysyłasz żądanie na serwer OAuth 2.0 Google. Jeśli korzystasz 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 w powyższym przykładzie identyfikator URI przekierowania schematu niestandardowego. Więcej informacji o formacie wartości niestandardowego schematu URI znajdziesz w definicji parametruredirect_uri
. -
Zwróć uwagę na parametry żądań
scope
iclient_id
, które są niezbędne do skonfigurowania pakietu SDK logowania przez Google. -
Postępuj zgodnie z instrukcjami
rozpoczynania integracji logowania przez Google z aplikacją na Androida,
aby skonfigurować pakiet SDK. Możesz pominąć krok Pobieranie identyfikatora klienta OAuth 2.0 serwera backendu, ponieważ używasz zwykle
client_id
pobranego w poprzednim kroku. -
Postępuj zgodnie z instrukcjami
włączania dostępu do interfejsu API po stronie serwera. Obejmuje to te czynności:
-
Aby pobrać kod autoryzacji dla zakresów, do których prosisz o uprawnienia, użyj metody
getServerAuthCode
. - Wyślij kod autoryzacji do backendu aplikacji, aby wymienić go na token dostępu i odświeżyć.
- Używanie pobranego tokena dostępu do wywoływania interfejsów API Google w imieniu użytkownika.
-
Aby pobrać kod autoryzacji dla zakresów, do których prosisz o uprawnienia, użyj metody
-
Sprawdź swój kod, aby określić, gdzie wysyłasz żądanie na serwer OAuth 2.0 Google. Jeśli korzystasz ze schematu niestandardowego, żądanie będzie wyglądać tak:
-
Wyłącz obsługę schematu niestandardowego w konsoli interfejsów API Google:
- Otwórz listę Dane logowania OAuth 2.0 i wybierz klienta na Androida.
- 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 nie działa zalecana alternatywa, możesz włączyć niestandardowe schematy URI w kliencie na Androida, wykonując te instrukcje:- Otwórz listę Dane logowania OAuth 2.0 i wybierz klienta na Androida.
- Przejdź do sekcji Ustawienia zaawansowane, zaznacz pole wyboru Włącz niestandardowy schemat URI i kliknij Zapisz, aby włączyć obsługę niestandardowego schematu URI.
Użyj interfejsu Chrome Identity API, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując potrzebę użycia identyfikatora URI przekierowania.
Weryfikowanie własności aplikacji (Android, Chrome)
Aby zmniejszyć ryzyko podszywania się pod inne osoby, możesz potwierdzić własność aplikacji.
Android
Aby dokończyć proces weryfikacji, możesz użyć konta dewelopera w Google Play, jeśli je masz, a Twoja aplikacja jest zarejestrowana w Konsoli Google Play. Aby weryfikacja przebiegła pomyślnie, muszą być spełnione te wymagania:
- W Konsoli Google Play musisz mieć zarejestrowaną aplikację z tą samą nazwą pakietu i odciskiem cyfrowym certyfikatu podpisywania SHA-1 co klient OAuth na Androida, dla którego przeprowadzasz weryfikację.
- Musisz mieć uprawnienia administratora w przypadku aplikacji w Konsoli Google Play. Dowiedz się więcej o zarządzaniu dostępem w Konsoli Google Play.
W sekcji Weryfikacja własności aplikacji klienta na Androida kliknij przycisk Zweryfikuj własność, aby zakończyć proces weryfikacji.
Jeśli weryfikacja się uda, pojawi się powiadomienie z potwierdzeniem jej powodzenia. 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 przypadku aplikacji w Konsoli 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:
- W panelu dewelopera Chrome Web Store musisz mieć zarejestrowany produkt o tym samym identyfikatorze co klient OAuth rozszerzenia do Chrome, na potrzeby którego przechodzisz weryfikację.
- Musisz być wydawcą elementu w Chrome Web Store. Dowiedz się więcej o zarządzaniu dostępem w panelu dewelopera Chrome Web Store.
W sekcji Zweryfikuj własność aplikacji klienta rozszerzenia do Chrome kliknij przycisk Zweryfikuj własność, aby ukończyć proces weryfikacji.
Uwaga: po przyznaniu dostępu do konta poczekaj kilka minut, zanim ukończysz proces weryfikacji.
Jeśli weryfikacja się uda, pojawi się powiadomienie z potwierdzeniem jej powodzenia. 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:
- Sprawdź, czy w panelu dewelopera Chrome Web Store znajduje się zarejestrowany produkt o tym samym identyfikatorze co klient OAuth rozszerzenia do Chrome, na potrzeby którego przechodzisz weryfikację.
- Upewnij się, że jesteś wydawcą aplikacji, tzn. musisz być jej wydawcą lub wydawcą grupowym. Dowiedz się więcej o zarządzaniu dostępem w panelu dewelopera Chrome Web Store.
- Jeśli lista wydawców grupowych została niedawno zaktualizowana, sprawdź, czy lista członków wydawcy grupowego jest zsynchronizowana w panelu dewelopera w Chrome Web Store. Dowiedz się więcej o synchronizowaniu listy członkostwa wydawcy.
Adres IP sprzężenia zwrotnego (macOS, Linux, komputer z systemem Windows)
Aby odebrać kod autoryzacji przy użyciu tego adresu URL, aplikacja musi nasłuchiwać na lokalnym serwerze WWW. Jest to możliwe na wielu platformach, ale nie na wszystkich. Jeśli jednak Twoja platforma go obsługuje, jest to zalecany mechanizm uzyskiwania kodu autoryzacji.
Gdy aplikacja otrzyma odpowiedź autoryzacyjną, dla wygody użytkowników powinna w niej wyświetlić stronę HTML z instrukcjami, jak zamknąć przeglądarkę i powró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. |
Ręczne kopiowanie i wklejanie
Określanie zakresów dostępu
Zakresy pozwalają aplikacji prosić o dostęp tylko do 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 określenie zakresów, do których aplikacja będzie potrzebować uprawnień dostępu.
Interfejs YouTube Analytics API używa tych zakresów:
Zakresy | |
---|---|
https://www.googleapis.com/auth/youtube | Zarządzaj swoim kontem YouTube |
https://www.googleapis.com/auth/youtube.readonly | Wyświetl swoje konto YouTube |
https://www.googleapis.com/auth/youtubepartner | Wyświetlaj swoje zasoby i powiązane treści w YouTube oraz zarządzaj nimi |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Wyświetlaj finansowe i niepieniężne raporty YouTube Analytics dotyczące treści w YouTube |
https://www.googleapis.com/auth/yt-analytics.readonly | Wyświetlaj raporty YouTube Analytics dotyczące swoich treści w YouTube |
Interfejs YouTube Reporting API używa tych zakresów:
Zakresy | |
---|---|
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Wyświetlaj finansowe i niepieniężne raporty YouTube Analytics dotyczące treści w YouTube |
https://www.googleapis.com/auth/yt-analytics.readonly | Wyświetlaj raporty YouTube Analytics dotyczące swoich treści w YouTube |
Dokument Zakresy interfejsu API OAuth 2.0 zawiera pełną listę zakresów, których możesz używać do uzyskiwania dostępu do interfejsów API Google.
Uzyskiwanie tokenów dostępu OAuth 2.0
Z podanych niżej instrukcji dowiesz się, jak Twoja aplikacja wchodzi w interakcję z serwerem Google OAuth 2.0, aby uzyskać zgodę użytkownika na wykonanie żądania do interfejsu API w jego imieniu. Twoja aplikacja musi uzyskać tę zgodę, zanim będzie mogła wykonać żądanie do interfejsu API Google wymagające autoryzacji użytkownika.
Krok 1. Wygeneruj weryfikator kodu i test zabezpieczający
Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo przepływu instalowanej 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, w którym niezastrzeżone znaki to [A–Z] / [a–z] / [0–9] / „-” / „.” / „_” / „~”. Jego minimalna długość to 43 znaki i maksymalna długość 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 hasz weryfikatora kodu zakodowany w Base64URL (bez dopełnienia) za pomocą algorytmu SHA256.
|
zwykła | Wyzwanie kodu ma taką samą wartość jak wygenerowany powyżej weryfikator kodu.
|
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 te parametry ciągu zapytania w przypadku 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 mogą korzystać z kilku opcji przekierowania. Musisz skonfigurować dane logowania z uwzględnieniem konkretnej metody przekierowania. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanych w: API Console
Credentials pageklienta. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI, wystąpi błąd W tabeli poniżej znajdziesz odpowiednią wartość parametru
|
||||||||||||||||||
response_type |
Wymagane
Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji. W przypadku zainstalowanych aplikacji ustaw wartość parametru na |
||||||||||||||||||
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, który Google wyświetla użytkownikowi. Zakresy pozwalają aplikacji prosić o dostęp tylko do zasobów, których potrzebuje, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu, jaki przyznają aplikacji. Dlatego występuje odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika. Interfejs YouTube Analytics API używa tych zakresów:
Interfejs YouTube Reporting API używa tych zakresów:
Dokument Zakresy interfejsu API OAuth 2.0 zawiera pełną listę zakresów, których możesz używać do uzyskiwania dostępu do interfejsów API Google. |
||||||||||||||||||
code_challenge |
Zalecane
Określa zakodowany |
||||||||||||||||||
code_challenge_method |
Zalecane
Określa metodę używaną do kodowania obiektu |
||||||||||||||||||
state |
Zalecane
Określa dowolną wartość ciągu, której aplikacja używa do utrzymania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji.
Gdy użytkownik wyrazi zgodę na dostęp aplikacji lub odmówi jej dostępu, serwer zwraca dokładną wartość, którą wysyłasz w postaci pary Tego parametru możesz używać do różnych celów, na przykład do kierowania użytkowników do odpowiedniego zasobu w aplikacji, wysyłania liczby jednorazowych i zapobiegania fałszowaniu żądań z innych witryn. Ponieważ |
||||||||||||||||||
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 korzysta ze wskazówek, aby uprościć proces logowania. Aby to zrobić, wstępnie wypełnij pole adresu e-mail w formularzu logowania lub wybierz odpowiednią sesję wielokrotnego logowania. Ustaw wartość parametru na adres e-mail lub identyfikator |
Przykładowe autoryzacyjne adresy URL
Poniższe karty zawierają przykładowe adresy URL autoryzacji dla różnych opcji identyfikatora URI przekierowania.
Każdy adres URL prosi o dostęp do zakresu, który umożliwia pobieranie raportów Statystyk 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
, a także opcjonalny parametr state
. Każdy adres URL zawiera podziały wierszy i spacje, aby zapewnić czytelność.
Niestandardowy schemat identyfikatora URI
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.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%2Fyt-analytics.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ę
Na tym etapie użytkownik decyduje, czy przyznać aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody, w którym widoczna jest nazwa Twojej aplikacji i usług interfejsów API Google, do których aplikacja prosi o dostęp (wraz z danymi uwierzytelniającymi użytkownika) oraz podsumowanie zakresów dostępu. Użytkownik może wtedy wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu żądanego przez aplikację lub odrzucić żądanie.
Na tym etapie Twoja aplikacja nie musi nic robić, ponieważ czeka na odpowiedź z serwera OAuth 2.0 Google wskazującą, czy przyznano dostęp. Odpowiedź na to pytanie zostanie objaśniona w kolejnym kroku.
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 przepływów uwierzytelniania i autoryzacji. Poniżej znajdziesz typowe kody błędów i sugerowane rozwiązania.
admin_policy_enforced
Konto Google nie może autoryzować co najmniej jednego żądanego zakresu ze względu na zasady administratora Google Workspace. Aby dowiedzieć się więcej o tym, jak administrator może ograniczać dostęp do wszystkich zakresów lub zakresów wrażliwych i zakresów z ograniczeniami, przeczytaj artykuł pomocy dla administratorów Google Workspace na temat określania, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace.
disallowed_useragent
Punkt końcowy autoryzacji jest wyświetlany w umieszczonym kliencie użytkownika niedozwolonym przez zasady Google 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 Google Sign-In for Android czy AppAuth for Android organizacji OpenID Foundation.
Programiści stron internetowych mogą napotkać ten błąd, gdy aplikacja na Androida 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 zawiera zarówno linki aplikacji na Androida, jak i domyślną przeglądarkę. Obsługiwana jest też biblioteka kart niestandardowych 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 Google Sign-In for iOS lub OpenID Foundation AppAuth for iOS.
Deweloperzy aplikacji internetowej 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 w systemie operacyjnym, który zawiera zarówno uniwersalne linki, 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 używasz weryfikatora kodu i testu zabezpieczającego, parametr code_callenge
jest nieprawidłowy lub go brakuje. Upewnij się, że parametr code_challenge
jest prawidłowo skonfigurowany.
Podczas odświeżania tokena dostępu token mógł wygasnąć lub został unieważniony. Uwierzytelnij użytkownika ponownie i poproś o zgodę na uzyskanie nowych tokenów. Jeśli ten błąd będzie się powtarzał, sprawdź, czy aplikacja została prawidłowo skonfigurowana i 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
redirect_uri
przekazany w żądaniu autoryzacji nie pasuje do autoryzowanego identyfikatora 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 procesu 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 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. Sprawdź, czy integracja OAuth korzysta z zalecanej metody integracji
- Do przekierowania identyfikatora URI jest używany 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 na Androidzie. Dowiedz się więcej o alternatywach niestandardowego schematu URI
Krok 4. Przetwórz odpowiedź serwera OAuth 2.0
Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacyjną, zależy od używanego w niej schematu identyfikatora 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ł żą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. Kod autoryzacji Exchange 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 pierwszego żądania. |
code_verifier |
weryfikator kodu utworzony w kroku 1. |
grant_type |
Zgodnie z definicją w specyfikacji protokołu OAuth 2.0 wartość tego pola musi być ustawiona na authorization_code . |
redirect_uri |
Jeden z identyfikatorów URI przekierowania Twojego projektu w 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
W odpowiedzi na to żądanie Google zwraca 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ę 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, taki jak openid , profile lub email . Wartością jest token sieciowy JSON (JWT), który zawiera podpisane cyfrowo informacje o tożsamości użytkownika. |
refresh_token |
Token, którego możesz użyć do uzyskania nowego tokena dostępu. Tokeny odświeżania są ważne, dopóki użytkownik nie anuluje dostępu. Pamiętaj, że tokeny odświeżania są zawsze zwracane w przypadku zainstalowanych aplikacji. |
scope |
Zakresy dostępu przyznane przez funkcję access_token wyrażone jako lista ciągów tekstowych rozdzielonych 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/yt-analytics.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 API Google w imieniu danego konta użytkownika, jeśli 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, podając parametr zapytania access_token
lub wartość nagłówka HTTP Bearer
Authorization
. 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, aby skonfigurować wywołania interfejsów API Google (np. wywołując YouTube Analytics API).
Pamiętaj, że interfejs YouTube Analytics API nie obsługuje procesu konta usługi. Interfejs YouTube Reporting API obsługuje konta usługi tylko w przypadku właścicieli treści YouTube, którzy są właścicielami wielu kanałów w YouTube i zarządzają nimi, takich jak wytwórnie i studia filmowe.
Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w interfejsie OAuth 2.0 Playground.
Przykłady żądań HTTP GET
Wywołanie punktu końcowego
reports.query
(YouTube Analytics API) przy użyciu nagłówka HTTP Authorization: Bearer
może wyglądać tak. Pamiętaj, że musisz podać własny token dostępu:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views 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/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
curl
przykładu
Możesz je przetestować za pomocą aplikacji wiersza poleceń curl
. Oto przykład z wykorzystaniem opcji nagłówka HTTP (preferowana):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Możesz też użyć opcji parametru ciągu zapytania:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
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. Możesz odświeżyć token dostępu bez pytania użytkownika o uprawnienia (także wtedy, gdy użytkownik nie jest obecny), jeśli poprosisz o dostęp offline do zakresów powiązanych z tokenem.
Aby odświeżyć token dostępu, aplikacja wysyła do serwera autoryzacji Google (https://oauth2.googleapis.com/token
) żądanie HTTPS POST
, które zawiera te parametry:
Pola | |
---|---|
client_id |
Identyfikator klienta uzyskany z API Console. |
client_secret |
Tajny klucz klienta uzyskany z API Console.
client_secret nie ma zastosowania do żądań pochodzących z klientów zarejestrowanych jako aplikacje na Androida lub iOS albo aplikacje Chrome.
|
grant_type |
Zgodnie z definicją w specyfikacji 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
Jeśli użytkownik nie unieważnił 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" }
Pamiętaj, że w przypadku wszystkich klientów obowiązują limity liczby tokenów odświeżania: jeden limit na kombinację klienta/użytkownika, a drugi na użytkownika w przypadku wszystkich klientów. Tokeny odświeżania należy zapisać w pamięci długoterminowej i używać ich, dopóki są 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 cofnąć dostęp przyznany aplikacji. Użytkownik może anulować dostęp w Ustawieniach konta. Więcej informacji znajdziesz w artykule pomocy Usuwanie dostępu witryny lub aplikacji do Twojego konta.
Aplikacja może też automatycznie anulować przyznany dostęp. Automatyczne anulowanie jest ważne w sytuacjach, gdy użytkownik anuluje subskrypcję, usuwa aplikację lub znacznie zmieniły się zasoby interfejsu API wymagane przez aplikację. Inaczej mówiąc, część procesu usuwania może obejmować żądanie do interfejsu API dające pewność, że uprawnienia przyznane wcześniej aplikacji zostaną usunięte.
Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke
i uwzględnia 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 odpowiedni 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
wraz z kodem błędu.
Dalsza lektura
Sprawdzone metody IETF dotyczące protokołu OAuth 2.0 dla aplikacji natywnych obejmują wiele opisanych tu sprawdzonych metod.