W tym dokumencie wyjaśniono, w jaki sposób aplikacje zainstalowane na urządzeniach takich jak telefony, tablety i komputery wykorzystują punkty końcowe OAuth 2.0 firmy Google do autoryzacji dostępu do interfejsu API YouTube Analytics lub interfejsu API YouTube Reporting.
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. Na przykład aplikacja może użyć protokołu OAuth 2.0, aby uzyskać pozwolenie na pobranie danych YouTube Analytics dotyczących kanału.
Zainstalowane aplikacje są rozsyłane do poszczególnych urządzeń i zakłada się, że aplikacje te nie mogą zachowywać tajemnic. Mogą uzyskiwać dostęp do interfejsów API Google, gdy użytkownik korzysta z aplikacji lub gdy aplikacja działa w tle.
Ten przepływ autoryzacji jest podobny do tego używanego w aplikacjach serwera WWW. Główną różnicą jest to, że zainstalowane aplikacje muszą otworzyć przeglądarkę systemową i podać lokalny adres URI przekierowania, aby obsłużyć odpowiedzi z serwera autoryzacji Google.
Biblioteki i przykłady
W przypadku aplikacji na iOS zalecamy korzystanie z najnowszej wersji Sign In With Google iOS SDK. Zestaw SDK odpowiada za autoryzację użytkownika i jest łatwiejszy do wdrożenia niż protokół niższego poziomu opisany w tym przewodniku.
W przypadku aplikacji działających na urządzeniach, które nie obsługują przeglądarki systemowej lub mają ograniczone możliwości wprowadzania danych, takich jak telewizory, konsole do gier, aparaty fotograficzne i drukarki, zapoznaj się z artykułami OAuth 2.0 dla telewizorów i urządzeń lub Logowanie na telewizorach i urządzeniach o ograniczonych możliwościach wprowadzania danych.
Wymagania wstępne
Włącz interfejsy API dla swojego projektu
Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć te interfejsy w API Console.
Aby włączyć API dla swojego projektu:
- Open the API Library w Google API Console.
- If prompted, select a project, or create a new one.
- Na stronie Biblioteka znajdziesz i włączysz interfejs API YouTube Analytics i API YouTube Reporting. Wiele aplikacji pobierających dane YouTube Analytics współpracuje także z interfejsem YouTube Data API. Znajdź inne interfejsy API, z których będzie korzystać Twoja aplikacja i włącz je również.
Tworzenie danych uwierzytelniających
Każda aplikacja korzystająca z protokołu OAuth 2.0 w celu uzyskania dostępu do interfejsów API Google musi mieć dane uwierzytelniające, które identyfikują aplikację na serwerze OAuth 2.0 firmy Google. Poniższe kroki wyjaśniają, jak utworzyć dane uwierzytelniające dla swojego projektu. Następnie Twoje aplikacje będą mogły używać tych danych uwierzytelniających w celu uzyskania dostępu do interfejsów API włączonych dla danego projektu.
- Go to the Clients page.
- Kliknij Utwórz klienta.
- W poniższych sekcjach opisano typy klientów obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nadaj nazwę klientowi OAuth i odpowiednio ustaw pozostałe pola formularza.
iOS
- Wybierz typ aplikacji iOS.
- Wprowadź nazwę klienta OAuth. Ta nazwa jest wyświetlana w Clients page Twojego projektu w celu identyfikacji klienta.
- Wprowadź identyfikator pakietu dla swojej aplikacji. Identyfikator pakietu to wartość klucza CFBundleIdentifier w pliku zasobów listy właściwości informacji Twojej aplikacji (info.plist). Wartość jest najczęściej wyświetlana w panelu Ogólne lub panelu Podpisywanie i możliwości edytora projektu Xcode. Identyfikator pakietu jest również wyświetlany w sekcji Informacje ogólne na stronie Informacje o aplikacji w witrynie App Store Connect firmy Apple.
Sprawdź, czy używasz prawidłowego identyfikatora pakietu dla swojej aplikacji, ponieważ nie będziesz mógł go zmienić, jeśli korzystasz z funkcji Sprawdzania aplikacji.
- (Opcjonalnie)
Jeśli aplikacja jest opublikowana w sklepie App Store firmy Apple, wprowadź jej identyfikator App Store. Identyfikator sklepu to ciąg liczbowy zawarty w każdym adresie URL sklepu Apple App Store.
- Otwórz aplikację Apple App Store na urządzeniu z systemem iOS lub iPadOS.
- Wyszukaj swoją aplikację.
- Wybierz przycisk Udostępnij (symbol kwadratu i strzałki w górę).
- Wybierz Kopiuj link.
- Wklej link do edytora tekstu. Identyfikator App Store jest ostatnią częścią adresu URL.
Przykład:
https://apps.apple.com/app/google/id284815942
- (Opcjonalnie)
Wprowadź identyfikator swojego zespołu. Więcej informacji znajdziesz w sekcji Znajdź swój identyfikator zespołu w dokumentacji konta dewelopera Apple.
Uwaga: pole Identyfikator zespołu jest wymagane, jeśli włączasz usługę App Check dla swojego klienta. - (Opcjonalnie)
Włącz funkcję App Check dla swojej aplikacji na iOS. Po włączeniu funkcji App Check, usługa App Attest firmy Apple weryfikuje, czy żądania OAuth 2.0 pochodzące z klienta OAuth są oryginalne i pochodzą z Twojej aplikacji. Pomaga to zmniejszyć ryzyko podszywania się pod aplikację. Dowiedz się więcej o włączaniu funkcji Sprawdzanie aplikacji dla aplikacji na iOS.
- Kliknij Utwórz.
UWP
- Wybierz typ aplikacji Uniwersalna platforma Windows.
- Wprowadź nazwę klienta OAuth. Ta nazwa jest wyświetlana w Clients page Twojego projektu w celu identyfikacji klienta.
- Wprowadź 12-znakowy identyfikator aplikacji w sklepie Microsoft Store. Wartość tę znajdziesz w Centrum Partnerskim Microsoft na stronie Tożsamość aplikacji w sekcji Zarządzanie aplikacjami.
- Kliknij Utwórz.
W przypadku aplikacji UWP adres URI przekierowania jest tworzony przy użyciu unikatowego identyfikatora zabezpieczeń pakietu (SID) aplikacji. Package SID swojej aplikacji znajdziesz w pliku Package.appxmanifest w projekcie programu Visual Studio.
Podczas tworzenia identyfikatora klienta w konsoli Google Cloud należy określić identyfikator URI przekierowania w następującym formacie, używając wartości identyfikatora SID pakietu (małymi literami):
ms-app://YOUR_APP_PACKAGE_SID
W przypadku aplikacji platformy uniwersalnej systemu Windows (UWP) niestandardowy schemat URI nie może przekraczać 39 znaków, zgodnie ze specyfikacją w dokumentacji firmy Microsoft.
Zidentyfikuj zakresy dostępu
Zakresy umożliwiają aplikacji żądanie dostępu wyłącznie do zasobów, których potrzebuje, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu udzielanego aplikacji. Może zatem istnieć odwrotna zależność pomiędzy liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.
Zanim rozpoczniesz wdrażanie autoryzacji OAuth 2.0, zalecamy określenie zakresów, do których Twoja aplikacja będzie potrzebowała uprawnień dostępu.
Interfejs API YouTube Analytics wykorzystuje następujące zakresy:
| Zakres | Opis |
|---|---|
https://www. |
Zarządzanie kontem YouTube |
https://www. |
Wyświetlanie konta YouTube |
https://www. |
Przeglądaj zasoby oraz powiązane treści i zarządzaj nimi w serwisie YouTube |
https://www. |
Wyświetlanie finansowych i niefinansowych raportów Statystyk YouTube dotyczących treści w YouTube |
https://www. |
Wyświetlanie raportów Statystyk YouTube dotyczących treści w YouTube |
Interfejs API raportowania YouTube używa następujących zakresów:
| Zakres | Opis |
|---|---|
https://www. |
Wyświetlanie finansowych i niefinansowych raportów Statystyk YouTube dotyczących treści w YouTube |
https://www. |
Wyświetlanie raportów Statystyk YouTube dotyczących treści w YouTube |
Pełną listę zakresów, których można używać w celu uzyskania dostępu do interfejsów API Google, można znaleźć w dokumencie Zakresy interfejsu API OAuth 2.0.
Uzyskiwanie tokenów dostępu OAuth 2.0
Poniższe kroki pokazują, w jaki sposób Twoja aplikacja współpracuje z serwerem OAuth 2.0 firmy Google, aby uzyskać zgodę użytkownika na wykonanie żądania API w jego imieniu. Twoja aplikacja musi uzyskać tę zgodę, zanim będzie mogła wykonać żądanie interfejsu API Google wymagające autoryzacji użytkownika.
Krok 1. Wygeneruj weryfikator kodu i wyzwanie
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ść, zwana „code_challenge”, jest wysyłana do serwera autoryzacji w celu uzyskania kodu autoryzacji.
Utwórz weryfikator kodu
code_verifier to losowy ciąg kryptograficzny o wysokiej entropii, wykorzystujący niezarezerwowane znaki [AZ] / [az] / [0-9] / "-" / "." / "_" / "~" o minimalnej długości 43 znaków i maksymalnej długości 128 znaków.
Weryfikator kodu powinien mieć wystarczającą entropię, aby odgadnięcie wartości było niepraktyczne.
Stwórz wyzwanie kodowe
Obsługiwane są dwie metody tworzenia wyzwania związanego z kodem.
| Metody generowania wyzwań kodowych | |
|---|---|
| S256 (zalecane) | Test zabezpieczający to zakodowany w formacie Base64URL (bez dopełnienia) skrót SHA256 weryfikatora kodu.
|
| zwykły | Wartość wyzwania kodu jest taka sama jak wartość weryfikatora kodu wygenerowanego powyżej.
|
Krok 2: Wyślij żądanie do serwera OAuth 2.0 firmy 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, uwierzytelnianie użytkownika i uzyskiwanie jego zgody. Dostęp do punktu końcowego jest możliwy wyłącznie za pośrednictwem protokołu SSL. Połączenia HTTP (bez protokołu SSL) są odrzucane.
Serwer autoryzacji obsługuje następujące parametry ciągu zapytania dla zainstalowanych aplikacji:
| Parametry | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Wymagany
Identyfikator klienta aplikacji. Tę wartość znajdziesz w Cloud Console Clients page. |
||||||||||||||||||
redirect_uri |
Wymagany
Określa sposób, w jaki serwer autoryzacji Google wysyła odpowiedź do Twojej aplikacji. Dostępnych jest kilka opcji przekierowania dla zainstalowanych aplikacji, a Ty musisz skonfigurować swoje dane uwierzytelniające autoryzacji, mając na uwadze konkretną metodę przekierowania. Wartość musi być dokładnie taka sama jak jeden z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0, który został skonfigurowany w Cloud Console
Clients page. Jeśli ta wartość nie jest zgodna z autoryzowanym URI, pojawi się błąd Tabela zawiera odpowiednią wartość parametru
|
||||||||||||||||||
response_type |
Wymagany
Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji. Ustaw wartość parametru na |
||||||||||||||||||
scope |
Wymagany
Lista zakresów rozdzielona spacjami, która identyfikuje zasoby, do których Twoja aplikacja może uzyskać dostęp w imieniu użytkownika. Wartości te określają ekran zgody, który Google wyświetla użytkownikowi. Zakresy umożliwiają aplikacji żądanie dostępu wyłącznie do zasobów, których potrzebuje, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu udzielanego aplikacji. Istnieje zatem odwrotna zależność pomiędzy liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika. Interfejs API YouTube Analytics wykorzystuje następujące zakresy:
Interfejs API raportowania YouTube używa następujących zakresów:
Dokument Zakresy interfejsu API protokołu OAuth 2.0 zawiera pełną listę zakresów, których można używać w celu uzyskiwania dostępu do interfejsów API Google. |
||||||||||||||||||
code_challenge |
Zalecane
Określa zakodowany kod |
||||||||||||||||||
code_challenge_method |
Zalecane
Określa metodę użytą do zakodowania |
||||||||||||||||||
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ę Możesz używać tego parametru do różnych celów, np. do kierowania użytkownika do odpowiedniego zasobu w aplikacji, wysyłania wartości nonce i ograniczania ryzyka związanego z fałszowaniem żądań z innych witryn. Ponieważ wartość |
||||||||||||||||||
login_hint |
Opcjonalny
Jeśli Twoja aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby przesłać wskazówkę do serwera uwierzytelniania Google. Serwer używa podpowiedzi, aby uprościć proces logowania, wstępnie wypełniając pole z adresem e-mail w formularzu logowania lub wybierając odpowiednią sesję logowania wielokrotnego. Ustaw wartość parametru na adres e-mail lub identyfikator |
||||||||||||||||||
Przykładowe adresy URL autoryzacji
Na kartach poniżej znajdziesz przykładowe adresy URL autoryzacji dla różnych opcji identyfikatora URI przekierowania.
Każdy adres URL żąda dostępu do zakresu, który umożliwia dostęp do raportów YouTube Analytics użytkownika.Adresy URL są identyczne, różni je jedynie wartość 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 ułatwić czytanie.
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 pętli zwrotnej
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 znajduje się nazwa aplikacji i usługi interfejsu API Google, do których żąda uprawnień dostępu wraz z danymi uwierzytelniającymi użytkownika, a także podsumowanie zakresów dostępu, który ma zostać przyznany. Użytkownik może następnie wyrazić zgodę na udzielenie dostępu do jednego lub większej liczby zakresów żądanych przez aplikację lub odrzucić żądanie.
Na tym etapie aplikacja nie musi nic robić, ponieważ czeka na odpowiedź z serwera Google OAuth 2.0, która będzie wskazywać, czy przyznano dostęp. Odpowiedź ta zostanie wyjaśniona 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 widoczne dla użytkownika zamiast oczekiwanych procesów uwierzytelniania i autoryzacji. Typowe kody błędów i sugerowane rozwiązania:
admin_policy_enforced
Konto Google nie może autoryzować jednego lub większej liczby żądanych zakresów ze względu na zasady administratora Google Workspace. Więcej informacji o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów poufnych i zastrzeżonych, znajdziesz w artykule pomocy administratora Google Workspace zatytułowanym Kontrolowanie dostępu aplikacji zewnętrznych i wewnętrznych do danych Google Workspace, dopóki dostęp nie zostanie wyraźnie przyznany Twojemu identyfikatorowi klienta OAuth.
disallowed_useragent
Punkt końcowy autoryzacji jest wyświetlany w osadzonym agencie użytkownika, który jest niedozwolony w zasadach OAuth 2.0 firmy Google.
Deweloperzy systemów iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView.
Zamiast tego programiści powinni korzystać z bibliotek iOS, takich jak Google Sign-In dla iOS lub AppAuth dla iOS firmy OpenID Foundation.
Twórcy stron internetowych mogą spotkać się z tym błędem, gdy aplikacja na system iOS lub macOS otworzy ogólny link internetowy w osadzonym agencie użytkownika, a użytkownik przejdzie z witryny do punktu końcowego autoryzacji OAuth 2.0 firmy Google. Programiści powinni zezwolić na otwieranie ogólnych linków w domyślnym programie obsługi linków systemu operacyjnego, który obejmuje zarówno programy obsługi Universal Links, jak i domyślną aplikację przeglądarki. Biblioteka SFSafariViewController jest również obsługiwaną opcją.
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 na temat tej opcji konfiguracji znajdziesz w sekcji Typ użytkownika w artykule pomocy Konfigurowanie ekranu zgody OAuth.
deleted_client
Klient OAuth używany do wysyłania żądania został usunięty. Usuwanie może odbywać się ręcznie lub automatycznie w przypadku nieużywanych klientów . Usuniętych klientów można przywrócić w ciągu 30 dni od daty usunięcia. Dowiedz się więcej .
invalid_grant
Jeśli używasz weryfikatora kodu i narzędzia do sprawdzania poprawności kodu, parametr code_callenge jest nieprawidłowy lub go brakuje. Sprawdź, czy parametr code_challenge jest ustawiony poprawnie.
Podczas odświeżania tokena dostępu może się okazać, że token wygasł lub został unieważniony. Ponownie uwierzytelnij użytkownika i poproś o jego zgodę na uzyskanie nowych tokenów. Jeśli nadal widzisz ten błąd, sprawdź, czy Twoja aplikacja została poprawnie skonfigurowana i czy używasz właściwych tokenów i parametrów w swoim żądaniu. W przeciwnym razie konto użytkownika mogło zostać usunięte lub wyłączone.
redirect_uri_mismatch
Przekazany w żądaniu autoryzacji parametr redirect_uri nie pasuje do autoryzowanego adresu URI przekierowania dla identyfikatora klienta OAuth. Przejrzyj autoryzowane adresy URI przekierowań w Google Cloud Console
Clients page.
Przesłany parametr redirect_uri może być nieprawidłowy dla danego typu klienta.
Parametr redirect_uri może odnosić się do przepływu OAuth poza pasmem (OOB), który został wycofany i nie jest już obsługiwany. Aby zaktualizować integrację, zapoznaj się z przewodnikiem po migracji.
invalid_request
Wystąpił błąd w Twoim żądaniu. Może to mieć kilka przyczyn:
- Żądanie nie zostało poprawnie sformatowane
- W żądaniu brakowało wymaganych parametrów
- Żądanie korzysta z metody autoryzacji, której Google nie obsługuje. Sprawdź, czy Twoja integracja OAuth korzysta z zalecanej metody integracji
- W przypadku adresu URI przekierowania użyto nieobsługiwanego schematu niestandardowego. Jeśli zobaczysz komunikat o błędzie Niestandardowy schemat URI nie jest obsługiwany w aplikacjach na Androida ani w aplikacjach Chrome, dowiedz się więcej o alternatywach dla 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 przez nią 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ł prośbę.
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. Wymień kod autoryzacji na tokeny 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 Cloud Console Clients page. |
client_secret |
Opcjonalny
Tajny klucz klienta uzyskany z Cloud Console Clients page. |
code |
Kod autoryzacji zwrócony w odpowiedzi na wstępne żądanie. |
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 wymienionych w projekcie w Cloud Console
Clients page dla danego client_id. |
Poniższy 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& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
W odpowiedzi na to żądanie Google zwraca obiekt JSON zawierający krótkotrwały token dostępu 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 okres ważności tokena dostępu w sekundach. |
id_token |
Uwaga: ta właściwość jest zwracana tylko wtedy, gdy żądanie zawierało zakres tożsamości, np. openid, profile lub email. Wartość to 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 do momentu, gdy użytkownik cofnie dostęp lub token odświeżania wygaśnie. Pamiętaj, że w przypadku zainstalowanych aplikacji zawsze zwracane są tokeny odświeżania. |
refresh_token_expires_in |
Pozostały czas ważności tokena odświeżania w sekundach. Ta wartość jest ustawiana tylko wtedy, gdy użytkownik przyzna dostęp czasowy. |
scope |
Zakresy dostępu przyznane przez access_token w postaci listy ciągów znaków rozdzielonych spacjami, w których wielkość liter jest rozróżniana. |
token_type |
Typ zwracanego tokena. Obecnie wartość tego pola jest zawsze ustawiona na Bearer. |
Poniższy fragment przedstawia przykładową odpowiedź:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Krok 6. Sprawdź, które zakresy użytkownicy przyznali aplikacji
Żądając wielu uprawnień (zakresów), użytkownicy nie mogą przyznać Twojej aplikacji dostępu do wszystkich z nich. Aplikacja musi sprawdzać, które zakresy zostały faktycznie przyznane, i prawidłowo obsługiwać sytuacje, w których niektóre uprawnienia są odrzucane. Zazwyczaj polega to na wyłączaniu funkcji, które korzystają z tych odrzuconych zakresów.
Istnieją jednak wyjątki. Aplikacje Google Workspace Enterprise z delegacją uprawnień w całej domenie lub aplikacje oznaczone jako Zaufane omijają szczegółowy ekran zgody na uprawnienia. W przypadku tych aplikacji użytkownicy nie zobaczą szczegółowego ekranu z prośbą o wyrażenie zgody na uprawnienia. Zamiast tego Twoja aplikacja albo otrzyma wszystkie żądane zakresy, albo żadnego.
Aby uzyskać bardziej szczegółowe informacje, zobacz Jak obsługiwać uprawnienia szczegółowe.
Aby sprawdzić, czy użytkownik przyznał aplikacji dostęp do określonego zakresu, sprawdź pole scope w odpowiedzi tokenu dostępu. Zakresy dostępu przyznane przez token dostępu wyrażone jako lista ciągów znaków oddzielonych spacjami, w których wielkość liter ma znaczenie.
Na przykład poniższa przykładowa odpowiedź tokena dostępu wskazuje, że użytkownik przyznał Twojej aplikacji dostęp tylko do odczytu uprawnień dotyczących aktywności na Dysku i zdarzeń w Kalendarzu:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Zadzwoń do interfejsów API Google
Po uzyskaniu przez aplikację tokena dostępu możesz używać go do wykonywania połączeń z interfejsem API Google w imieniu określonego konta użytkownika, jeśli przyznano zakres(y) dostępu wymagane przez interfejs API. Aby to zrobić, należy uwzględnić token dostępu w żądaniu do interfejsu API, dodając parametr zapytania access_token lub wartość nagłówka HTTP Authorization Bearer. Jeśli to możliwe, zaleca się stosowanie nagłówka HTTP, ponieważ ciągi zapytań są zazwyczaj widoczne w logach serwera. W większości przypadków możesz użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (na przykład podczas wywoływania interfejsu API YouTube Analytics).
Należy pamiętać, że interfejs API YouTube Analytics nie obsługuje przepływu kont usługowych. Interfejs API raportowania YouTube obsługuje wyłącznie konta usługowe właścicieli treści YouTube, którzy posiadają i zarządzają wieloma kanałami YouTube, np. wytwórnie płytowe i studia filmowe.
Możesz wypróbować wszystkie interfejsy API Google i zapoznać się z ich zakresami na stronie OAuth 2.0 Playground.
Przykłady HTTP GET
Wywołanie punktu końcowego
reports.query (interfejs API YouTube Analytics) przy użyciu nagłówka HTTP Authorization: Bearer może wyglądać następująco. Należy pamiętać o podaniu własnego tokena 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 przy użyciu 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 przetestować te polecenia za pomocą aplikacji wiersza poleceń curl. Oto przykład wykorzystujący opcję nagłówka HTTP (preferowaną):
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ż wybrać opcję 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 wygasają i stają się nieprawidłowymi danymi uwierzytelniającymi dla powiązanego żądania API. Możesz odświeżyć token dostępu bez proszenia użytkownika o uprawnienia (nawet gdy użytkownik jest nieobecny), 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), które zawiera te parametry:
| Pola | |
|---|---|
client_id |
Identyfikator klienta uzyskany z API Console. |
client_secret |
Opcjonalny
Tajny klucz klienta uzyskany z API Console.
(Symbol |
grant_type |
Zgodnie ze specyfikacją OAuth 2.0 wartość tego pola musi być ustawiona na refresh_token. |
refresh_token |
Token odświeżania zwrócony po wymianie kodu autoryzacji. |
Poniższy 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& refresh_token=refresh_token& grant_type=refresh_token
Dopóki użytkownik nie cofnie dostępu przyznanego aplikacji, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Poniższy fragment kodu pokazuje przykładową odpowiedź:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "token_type": "Bearer" }
Pamiętaj, że liczba tokenów odświeżania, które zostaną wydane, jest ograniczona. Obowiązuje limit dla każdej kombinacji klient/użytkownik i inny limit dla każdego użytkownika we wszystkich klientach. Tokeny odświeżania należy zapisywać w pamięci długoterminowej i używać ich tak długo, jak są ważne. Jeśli aplikacja wyśle zbyt wiele żądań tokenów odświeżania, może przekroczyć te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.
Unieważnienie tokena
W niektórych przypadkach użytkownik może chcieć cofnąć dostęp przyznany aplikacji. Użytkownik może cofnąć dostęp, otwierając Ustawienia konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu strony lub aplikacji w artykule pomocy Strony internetowe i aplikacje innych firm z dostępem do Twojego konta.
Aplikacja może też programowo unieważnić przyznany jej dostęp. Programowe wycofywanie jest ważne w przypadkach, gdy użytkownik rezygnuje z subskrypcji, usuwa aplikację lub zasoby interfejsu API wymagane przez aplikację uległy znacznym zmianom. Innymi słowy, część procesu usuwania może obejmować żądanie interfejsu API, aby upewnić się, ż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 dołącza token jako parametr:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}Może to 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 wycofanie zostanie przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędów zwracany jest kod stanu HTTP 400 wraz z kodem błędu.
Metody przekierowywania aplikacji
Niestandardowy schemat identyfikatora URI
Niestandardowe schematy URI to forma głębokiego linkowania, która wykorzystuje niestandardowy schemat do otwierania aplikacji.
Alternatywa dla używania niestandardowych schematów URI w aplikacjach Chrome
Użyj interfejsu Chrome Identity API, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do Twojej aplikacji, eliminując potrzebę stosowania przekierowania URI.
Adres IP pętli zwrotnej (macOS, Linux, komputery stacjonarne Windows)
Aby otrzymać kod autoryzacyjny za pomocą tego adresu URL, Twoja aplikacja musi nasłuchiwać na lokalnym serwerze WWW. Jest to możliwe na wielu platformach, ale nie na wszystkich. Jeśli jednak Twoja platforma obsługuje tę funkcję, jest to zalecany mechanizm uzyskiwania kodu autoryzacyjnego.
Aby zapewnić najlepszą użyteczność, po otrzymaniu odpowiedzi autoryzacyjnej Twoja aplikacja powinna wyświetlić stronę HTML z prośbą o zamknięcie przeglądarki i powrót do aplikacji.
| Zalecane użycie | Aplikacje na systemy macOS, Linux i Windows (ale nie na uniwersalną platformę Windows) |
| Wartości formularza | Ustaw typ aplikacji na Aplikacja komputerowa. |
Ręczne kopiowanie/wklejanie (przestarzałe)
Chroń swoje aplikacje
Zweryfikuj własność aplikacji dla przeglądarki Chrome
Aby zmniejszyć ryzyko podszywania się pod inną osobę, możesz zweryfikować, kto jest właścicielem Twojej aplikacji.
Aby dokończyć proces weryfikacji, należy skorzystać z konta programisty Chrome Web Store. Aby weryfikacja przebiegła pomyślnie, muszą zostać spełnione następujące wymagania:
- Musisz mieć zarejestrowany element w Pulpicie programisty Chrome Web Store o tym samym identyfikatorze elementu, co klient OAuth rozszerzenia Chrome, dla którego przeprowadzasz weryfikację.
- Musisz być wydawcą elementu Chrome Web Store. Dowiedz się więcej o zarządzaniu dostępem w Panelu programisty Chrome Web Store.
W sekcji Zweryfikuj własność aplikacji w kliencie rozszerzenia Chrome kliknij przycisk Zweryfikuj własność, aby zakończyć proces weryfikacji.
Uwaga: Po udzieleniu dostępu do konta odczekaj kilka minut, zanim zakończysz proces weryfikacji.
Jeśli weryfikacja zakończy się powodzeniem, zostanie wyświetlone powiadomienie potwierdzające pomyślne zakończenie procesu weryfikacji. W przeciwnym wypadku zostanie wyświetlony komunikat o błędzie.
Aby naprawić nieudaną weryfikację, spróbuj wykonać następujące czynności:
- Upewnij się, że w Panelu programisty Chrome Web Store znajduje się zarejestrowany element o tym samym identyfikatorze elementu, co klient OAuth rozszerzenia Chrome, dla którego przeprowadzasz weryfikację.
- Upewnij się, że jesteś wydawcą aplikacji, czyli musisz być indywidualnym wydawcą aplikacji lub członkiem grupy wydawców aplikacji. Dowiedz się więcej o zarządzaniu dostępem w Panelu programisty Chrome Web Store.
- Jeśli właśnie zaktualizowałeś listę wydawców grupowych, sprawdź, czy lista członków wydawców grupowych jest zsynchronizowana w Panelu programisty Chrome Web Store. Dowiedz się więcej o synchronizowaniu listy członków wydawcy.
Sprawdzanie aplikacji (tylko iOS)
Funkcja App Check pomaga chronić aplikacje iOS przed nieautoryzowanym użyciem, wykorzystując usługę App Attest firmy Apple do weryfikacji, czy żądania wysyłane do punktów końcowych Google OAuth 2.0 pochodzą z autentycznych aplikacji. Pomaga to zmniejszyć ryzyko podszywania się pod aplikację.
Włącz sprawdzanie aplikacji dla swojego klienta iOS
Aby pomyślnie włączyć funkcję App Check dla klienta iOS, muszą zostać spełnione następujące wymagania:- Musisz określić identyfikator zespołu dla swojego klienta iOS.
- Nie należy używać symbolu wieloznacznego w identyfikatorze pakietu, ponieważ może on odnosić się do więcej niż jednej aplikacji. Oznacza to, że identyfikator pakietu nie może zawierać symbolu gwiazdki (*).
Po włączeniu funkcji Sprawdzanie aplikacji w widoku edycji klienta OAuth zaczną być widoczne metryki dotyczące żądań OAuth od klienta. Żądania z niezweryfikowanych źródeł nie będą blokowane, dopóki nie wymusisz sprawdzania aplikacji. Informacje na stronie monitorowania metryk pomogą Ci określić, kiedy rozpocząć egzekwowanie zasad.
Podczas włączania funkcji Sprawdzania aplikacji dla aplikacji na iOS mogą pojawić się błędy związane z tą funkcją. Aby naprawić te błędy, wypróbuj następujące rozwiązania:
- Sprawdź, czy podane identyfikatory pakietu i zespołu są prawidłowe.
- Sprawdź, czy nie używasz symbolu wieloznacznego w identyfikatorze pakietu.
Wymuś sprawdzanie aplikacji dla swojego klienta iOS
Włączenie Sprawdzania aplikacji nie powoduje automatycznego blokowania nierozpoznanych żądań. Aby wymusić tę ochronę, otwórz widok edycji klienta iOS. Po prawej stronie strony w sekcji Tożsamość Google w systemie iOS zobaczysz dane Sprawdzania aplikacji. Wskaźniki obejmują te informacje:- Liczba zweryfikowanych żądań – żądania, które mają prawidłowy token Sprawdzania aplikacji. Po włączeniu egzekwowania Sprawdzania aplikacji tylko żądania z tej kategorii będą realizowane.
- Liczba niezweryfikowanych żądań: prawdopodobnie nieaktualne żądania klienta – żądania, w których brakuje tokena Sprawdzania aplikacji. Mogą one pochodzić ze starszej wersji aplikacji, która nie zawiera implementacji Sprawdzania aplikacji.
- Liczba niezweryfikowanych żądań: żądania nieznanego pochodzenia – żądania, w których brakuje tokena Sprawdzania aplikacji i które nie wyglądają na pochodzące z Twojej aplikacji.
- Liczba niezweryfikowanych żądań: nieprawidłowe żądania – żądania z nieprawidłowym tokenem Sprawdzania aplikacji, który może pochodzić od nieautentycznego klienta próbującego podszyć się pod Twoją aplikację lub ze środowisk emulowanych.
Aby wymusić weryfikację aplikacji, kliknij przycisk ENFORCE i potwierdź swój wybór. Po włączeniu wymuszania wszystkie niezweryfikowane żądania wysyłane przez klienta będą odrzucane.
Uwaga: po włączeniu egzekwowania zastosowanie zmian może potrwać do 15 minut.
Wyłącz wymuszanie Sprawdzania aplikacji w przypadku klienta iOS
Wyłączenie wymuszania Sprawdzania aplikacji w przypadku Twojej aplikacji spowoduje zatrzymanie wymuszania i umożliwi przesyłanie wszystkich żądań z klienta do punktów końcowych Google OAuth 2.0, w tym niezweryfikowanych żądań.
Aby wyłączyć wymuszanie App Check w przypadku klienta iOS, otwórz widok edycji klienta iOS, kliknij przycisk WYŁĄCZ WYMUSZANIE i potwierdź swój wybór.
Uwaga: po wyłączeniu weryfikacji aplikacji zastosowanie zmian może potrwać do 15 minut.
Wyłącz Sprawdzanie aplikacji w przypadku klienta iOS
Wyłączenie Sprawdzania aplikacji w przypadku Twojej aplikacji spowoduje zatrzymanie całego monitorowania i wymuszania Sprawdzania aplikacji. Zamiast tego rozważ wyłączenie Sprawdzania aplikacji, aby móc nadal monitorować dane klienta.
Aby wyłączyć Sprawdzanie aplikacji dla klienta iOS, otwórz widok edycji klienta iOS i wyłącz przycisk Chroń klienta OAuth przed nadużyciami przy pomocy funkcji Sprawdzanie aplikacji Firebase.
Uwaga: po wyłączeniu weryfikacji aplikacji zastosowanie zmian może potrwać do 15 minut.
Dostęp zależny od czasu
Dostęp czasowy umożliwia użytkownikowi przyznanie aplikacji dostępu do jego danych na ograniczony czas w celu wykonania działania. Dostęp czasowy jest dostępny w wybranych usługach Google podczas procesu uzyskiwania zgody. Użytkownicy mogą przyznać dostęp na ograniczony czas. Przykładem jest interfejs Data Portability API, który umożliwia jednorazowe przeniesienie danych.
Gdy użytkownik przyzna Twojej aplikacji dostęp czasowy, token odświeżania wygaśnie po upływie określonego czasu. Pamiętaj, że tokeny odświeżania mogą zostać unieważnione wcześniej w określonych okolicznościach. Szczegółowe informacje znajdziesz w tych przypadkach. Pole refresh_token_expires_in zwrócone w odpowiedzi wymiany kodu autoryzacji w takich przypadkach reprezentuje czas pozostały do wygaśnięcia tokena odświeżania.
Więcej informacji
Wiele sprawdzonych metod opisanych w tym dokumencie zostało opracowanych na podstawie dokumentu IETF Best Current Practice OAuth 2.0 for Native Apps.
Wdrażanie Ochrony wszystkich kont
Dodatkowym krokiem, który należy podjąć w celu ochrony kont użytkowników, jest wdrożenie ochrony międzykontowej za pomocą usługi ochrony międzykontowej Google. Ta usługa umożliwia subskrybowanie powiadomień o zdarzeniach związanych z bezpieczeństwem, które dostarczają aplikacji informacji o ważnych zmianach na koncie użytkownika. Na podstawie tych informacji możesz podejmować działania w zależności od tego, jak zdecydujesz reagować na zdarzenia.
Oto przykłady typów zdarzeń wysyłanych do Twojej aplikacji przez usługę ochrony kont Google:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Więcej informacji o wdrażaniu ochrony wszystkich kont i pełną listę dostępnych zdarzeń znajdziesz na stronie Ochrona kont użytkowników za pomocą ochrony wszystkich kont .