Ten dokument wyjaśnia, 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.
OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy jednoczesnym zachowaniu poufności nazw, haseł i innych informacji. Aplikacja może na przykład używać protokołu OAuth 2.0, aby uzyskać uprawnienia do pobierania danych z YouTube dotyczących kanału.
Zainstalowane aplikacje są rozpowszechniane na poszczególnych urządzeniach i zakłada się, że nie mogą one przechowywać informacji poufnych. Mogą one uzyskiwać dostęp do interfejsów API Google, gdy użytkownik korzysta z aplikacji lub gdy działa ona w tle.
Ten przepływ autoryzacji jest podobny do tego, który jest używany w przypadku aplikacji serwera internetowego. Główna różnica polega na tym, że zainstalowane aplikacje muszą otwierać przeglądarkę systemową i podawać lokalny identyfikator URI przekierowania, aby obsługiwać odpowiedzi z serwera autoryzacji Google.
Biblioteki i przykłady
W przypadku aplikacji na iOS zalecamy korzystanie z najnowszej wersji pakietu SDK do logowania się za pomocą Google na iOS. Pakiet SDK obsługuje autoryzację użytkownika i jest prostszy we wdrożeniu 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 wpisywania, takich jak telewizory, konsole do gier, aparaty czy drukarki, zapoznaj się z artykułami OAuth 2.0 na telewizory i urządzenia i Logowanie na telewizorach i urządzeniach z ograniczoną możliwością wpisywania.
Wymagania wstępne
Włączanie interfejsów API w projekcie
Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć te interfejsy 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 znajdź i włącz interfejs YouTube Data API. Znajdź inne interfejsy API, z których będzie korzystać Twoja aplikacja, i też je włącz.
Tworzenie danych uwierzytelniających
Każda aplikacja, która używa OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google, musi mieć dane logowania autoryzacji, które identyfikują aplikację na serwerze OAuth 2.0 Google. Poniżej znajdziesz instrukcje tworzenia danych logowania do projektu. Aplikacje mogą następnie używać tych danych logowania do uzyskiwania dostępu do interfejsów API włączonych w tym projekcie.
- Go to the Clients page.
- Kliknij Utwórz klienta.
- W sekcjach poniżej opisujemy typy klientów obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany w przypadku Twojej aplikacji, nadaj nazwę klientowi OAuth i ustaw odpowiednie wartości w pozostałych polach formularza.
iOS
- Wybierz typ aplikacji iOS.
- Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w projekcie Clients page , aby umożliwić identyfikację klienta.
- Wpisz identyfikator pakietu aplikacji. Jest to wartość klucza CFBundleIdentifier w pliku zasobu listy właściwości informacji o aplikacji (info.plist). Wartość jest najczęściej wyświetlana w panelu Ogólne lub Podpisywanie i możliwości w edytorze projektu Xcode. Identyfikator pakietu jest też wyświetlany w sekcji Informacje ogólne na stronie Informacje o aplikacji w witrynie App Store Connect firmy Apple.
Sprawdź, czy używasz prawidłowego identyfikatora pakietu aplikacji, ponieważ jeśli korzystasz z funkcji Sprawdzanie aplikacji, nie będzie można go zmienić.
- (Opcjonalnie)
Jeśli aplikacja jest opublikowana w sklepie App Store firmy Apple, wpisz jej identyfikator w tym sklepie. Identyfikator sklepu to ciąg cyfr zawarty w każdym adresie URL Apple App Store.
- Otwórz aplikację Apple App Store na urządzeniu z iOS lub iPadOS.
- Wyszukaj swoją aplikację.
- Kliknij przycisk Udostępnij (kwadrat ze strzałką w górę).
- Kliknij Skopiuj link.
- Wklej link w edytorze tekstu. Identyfikator App Store to ostatnia część adresu URL.
Przykład:
https://apps.apple.com/app/google/id284815942
- (Opcjonalnie)
Wpisz identyfikator zespołu. Więcej informacji znajdziesz w artykule Znajdowanie identyfikatora zespołu w dokumentacji konta dewelopera Apple.
Uwaga: pole Identyfikator zespołu jest wymagane, jeśli włączasz Sprawdzanie aplikacji dla klienta. - (Opcjonalnie)
Włącz Sprawdzanie aplikacji w aplikacji na iOS. Gdy to zrobisz, usługa App Attest firmy Apple będzie weryfikować, czy żądania OAuth 2.0 pochodzące od klienta OAuth są autentyczne i czy pochodzą z Twojej aplikacji. Pomoże to zmniejszyć ryzyko podszywania się pod aplikację. Więcej informacji o włączaniu Sprawdzania aplikacji w aplikacji na iOS
- Kliknij Utwórz.
UWP
- Wybierz typ aplikacji Platforma uniwersalna systemu Windows.
- Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w projekcie Clients page , aby umożliwić identyfikację klienta.
- Wpisz 12-znakowy identyfikator Microsoft Store Twojej aplikacji. Tę wartość znajdziesz w Centrum Partnerów Microsoft na stronie Tożsamość aplikacji w sekcji Zarządzanie aplikacjami.
- Kliknij Utwórz.
W przypadku aplikacji UWP identyfikator URI przekierowania jest tworzony przy użyciu unikalnego identyfikatora zabezpieczeń pakietu aplikacji. Package SID aplikacji znajdziesz w pliku Package.appxmanifest w projekcie Visual Studio.
Podczas tworzenia identyfikatora klienta w konsoli Google Cloud musisz podać identyfikator URI przekierowania w tym formacie, używając wartości SID pakietu pisanej małymi literami:
ms-app://YOUR_APP_PACKAGE_SID
W przypadku aplikacji UWP niestandardowy schemat URI nie może mieć więcej niż 39 znaków, zgodnie z dokumentacją Microsoftu.
Określanie zakresów dostępu
Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych jej zasobów, a użytkownikom – kontrolowanie zakresu dostępu przyznawanego aplikacji. Dlatego może istnieć odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.
Zanim zaczniesz wdrażać autoryzację OAuth 2.0, określ zakresy, do których Twoja aplikacja będzie potrzebować dostępu.
Interfejs YouTube Data API v3 używa tych zakresów:
| Zakres | Opis |
|---|---|
https://www. |
Zarządzanie kontem YouTube |
https://www. |
Wyświetlanie listy aktualnie aktywnych użytkowników wspierających kanał, ich obecnych poziomów i dat rozpoczęcia wsparcia |
https://www. |
Przeglądanie, edytowanie i trwałe usuwanie Twoich filmów, ocen, komentarzy i napisów z YouTube |
https://www. |
Wyświetlanie konta YouTube |
https://www. |
Zarządzanie filmami w YouTube |
https://www. |
Przeglądaj zasoby oraz powiązane treści i zarządzaj nimi w serwisie YouTube |
https://www. |
Przeglądanie prywatnych danych kanału YouTube istotnych podczas rozmowy z partnerem 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
Poniższe kroki pokazują, jak aplikacja wchodzi w interakcję z serwerem OAuth 2.0 Google, aby uzyskać zgodę użytkownika na wykonanie żądania interfejsu API w jego imieniu. Zanim aplikacja będzie mogła wykonać żądanie interfejsu API Google, które wymaga autoryzacji użytkownika, musi uzyskać jego zgodę.
Krok 1. Wygeneruj weryfikator kodu i wyzwanie
Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo procesu instalacji aplikacji. W przypadku 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 ciąg znaków losowych o wysokiej entropii, który zawiera nieograniczone znaki [A-Z] / [a-z] / [0-9] / „-” / „.” / „_” / „~”, ma długość co najmniej 43 znaków i nie więcej niż 128 znaków.
Weryfikator kodu powinien mieć wystarczającą entropię, aby odgadnięcie jego wartości było praktycznie niemożliwe.
Tworzenie wyzwania z kodem
Obsługiwane są 2 metody tworzenia wyzwania związanego z kodem.
| Metody generowania testów z kodem | |
|---|---|
| S256 (zalecane) | Test zabezpieczający to skrót SHA256 w formacie Base64URL (bez dopełnienia) weryfikatora kodu.
|
| plain | Wyzwanie związane z kodem ma taką samą wartość jak wygenerowany powyżej weryfikator kodu.
|
Krok 2. Wyślij żądanie do serwera 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, uwierzytelnianie użytkownika i uzyskiwanie jego zgody. 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 |
Wymagany
Identyfikator klienta aplikacji. Tę wartość znajdziesz w Cloud Console Clients page. |
||||||||||||||||
redirect_uri |
Wymagany
Określa, w jaki sposób serwer autoryzacji Google wysyła odpowiedź do aplikacji. Aplikacje zainstalowane mają do dyspozycji kilka opcji przekierowania. Podczas konfigurowania danych logowania autoryzacji musisz wybrać 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 pasuje do autoryzowanego identyfikatora 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 oddzielonych spacjami, które identyfikują zasoby, do których aplikacja może uzyskać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi. Zakresy umożliwiają aplikacji żądanie dostępu tylko do potrzebnych zasobów, a użytkownikom – kontrolowanie zakresu dostępu przyznawanego aplikacji. Dlatego istnieje odwrotna zależność między liczbą zakresów, o które prosisz, a prawdopodobieństwem uzyskania zgody użytkownika. Interfejs YouTube Data API v3 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 parametr |
||||||||||||||||
code_challenge_method |
Zalecane
Określa metodę kodowania parametru |
||||||||||||||||
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 przekazać podpowiedź serwerowi 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 prosi o dostęp do zakresu, który umożliwia pobieranie danych użytkownika z YouTube.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 znaki podziału wiersza i spacje, aby był bardziej czytelny.
Niestandardowy schemat identyfikatora URI
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& 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%2Fyoutube.force-ssl& 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 podaje nazwę aplikacji i usługi interfejsu API Google, do których aplikacja chce uzyskać dostęp za pomocą danych logowania użytkownika, oraz podsumowanie zakresów dostępu, które mają zostać przyznane. Użytkownik może wtedy wyrazić zgodę na przyznanie dostępu do co najmniej jednego zakresu, o który prosi aplikacja, lub odrzucić prośbę.
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ź jest wyjaś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ż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ć co najmniej jednego z zakresów, o które prosisz, 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 wrażliwych i ograniczonych, dopóki dostęp nie zostanie wyraźnie przyznany identyfikatorowi klienta OAuth, znajdziesz w artykule pomocy dla administratorów Google Workspace Określanie, 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 osadzonym agencie użytkownika, który jest niedozwolony zgodnie z zasadami Google dotyczącymi protokołu OAuth 2.0.
Deweloperzy aplikacji na iOS i macOS mogą napotkać ten błąd podczas otwierania próśb o autoryzację w WKWebView.
Deweloperzy powinni zamiast tego używać bibliotek iOS, takich jak Logowanie przez Google na iOS lub AppAuth na iOS od OpenID Foundation.
Deweloperzy stron internetowych mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otworzy ogólny link internetowy w osadzonym agencie użytkownika, a użytkownik przejdzie do punktu końcowego autoryzacji OAuth 2.0 w Google z Twojej witryny. Deweloperzy powinni zezwalać na otwieranie ogólnych linków w domyślnym programie obsługi linków w systemie operacyjnym, który obejmuje programy obsługi linków uniwersalnych lub domyślną aplikację przeglądarki. Obsługiwana jest też biblioteka SFSafariViewController.
org_internal
Identyfikator klienta OAuth w żądaniu jest częścią projektu, który ogranicza dostęp do kont Google w określonej organizacji Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w sekcji Typ użytkownika w artykule 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 usunięcia. Więcej informacji
invalid_grant
Jeśli używasz weryfikatora kodu i wyzwania, parametr code_callenge jest nieprawidłowy lub go brakuje. Sprawdź, czy parametr code_challenge jest prawidłowo ustawiony.
Podczas odświeżania tokena dostępu token mógł wygasnąć lub zostać unieważniony. Ponownie uwierzytelnij użytkownika i poproś go o zgodę na uzyskanie nowych tokenów. Jeśli ten błąd nadal występuje, 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
Parametr redirect_uri przekazany w żądaniu autoryzacji nie pasuje do autoryzowanego identyfikatora URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania w sekcji Google Cloud Console
Clients page.
Przekazana wartość redirect_uri może być nieprawidłowa 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
W wysłanym przez Ciebie żądaniu wystąpił błąd. Może to wynikać z kilku przyczyn:
- Żądanie nie zostało prawidłowo sformatowane
- W prośbie 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.
- 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ł żą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. 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 |
Tajny klucz klienta uzyskany z Cloud Console Clients page. |
code |
Kod autoryzacji zwrócony w odpowiedzi na pierwsze żą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& 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 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 czas 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 oddzielonych spacjami, w których rozróżniana jest wielkość liter. |
token_type |
Typ zwracanego tokena. Obecnie wartość tego pola jest zawsze ustawiona na Bearer. |
Poniższy fragment kodu pokazuje przykładową odpowiedź:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Krok 6. Sprawdź, które zakresy użytkownicy przyznali aplikacji
Gdy prosisz o wiele uprawnień (zakresów), użytkownicy mogą nie przyznać 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.
Są jednak wyjątki. Aplikacje Google Workspace Enterprise z delegowaniem uprawnień w całej domenie lub aplikacje oznaczone jako Zaufane pomijają ekran zgody na szczegółowe uprawnienia. W przypadku tych aplikacji użytkownicy nie zobaczą ekranu z prośbą o zgodę na poszczególne uprawnienia. Zamiast tego aplikacja otrzyma wszystkie żądane zakresy lub żadne z nich.
Więcej informacji znajdziesz w artykule Jak zarządzać szczegółowymi uprawnieniami.
Aby sprawdzić, czy użytkownik przyznał Twojej aplikacji dostęp do określonego zakresu, sprawdź pole scope w odpowiedzi tokena 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ź z tokenem dostępu wskazuje, że użytkownik przyznał Twojej aplikacji dostęp do uprawnień do odczytu aktywności na Dysku i wydarzeń w Kalendarzu:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Wywoływanie interfejsów API Google
Gdy aplikacja uzyska token dostępu, może go używać do wywoływania interfejsu Google API w imieniu danego konta użytkownika, jeśli przyznano zakresy dostępu wymagane przez interfejs API. Aby to zrobić, dołącz token dostępu do żądania wysyłanego do interfejsu API, uwzględniając parametr zapytania access_token lub wartość nagłówka HTTP AuthorizationBearer. 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. podczas wywoływania interfejsu YouTube Live Streaming API).
Pamiętaj, że interfejs YouTube Live Streaming API nie obsługuje przepływu konta usługi. Konta usługi nie można połączyć z kontem YouTube, więc próby autoryzacji żądań za pomocą tego procesu będą generować błąd NoLinkedYouTubeAccount.
Wszystkie interfejsy API Google i ich zakresy możesz wypróbować w OAuth 2.0 Playground.
Przykłady żądań HTTP GET
Wywołanie punktu końcowego
liveBroadcasts.list (interfejs YouTube Live Streaming API) z nagłówkiem HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz podać własny token dostępu:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&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/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
curl przykładu
Możesz przetestować te polecenia za pomocą aplikacji wiersza poleceń curl. Oto przykład, w którym użyto opcji nagłówka HTTP (preferowanej):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
Możesz też wybrać opcję parametru ciągu zapytania:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
Odświeżanie tokena dostępu
Tokeny dostępu okresowo wygasają i stają się nieprawidłowymi danymi uwierzytelniającymi dla powiązanego żądania API. Token dostępu możesz odświeżyć 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 |
Tajny klucz klienta uzyskany z API Console.
(Symbol client_secret nie dotyczy żądań od klientów zarejestrowanych jako aplikacje na Androida, iOS lub Chrome).
|
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 z wymiany 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& client_secret=your_client_secret& 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 na kombinację klient/użytkownik i limit na 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 zażą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ż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 witryny 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 w aplikacji
Niestandardowy schemat identyfikatora URI
Niestandardowe schematy URI to forma precyzyjnego linkowania, która wykorzystuje zdefiniowany przez Ciebie schemat do otwierania aplikacji.
Alternatywa dla używania niestandardowych schematów URI w aplikacjach Chrome
Używaj interfejsu Chrome Identity API, który dostarcza odpowiedź OAuth 2.0 bezpośrednio do aplikacji, eliminując potrzebę używania identyfikatora URI przekierowania.
Adres IP typu loopback (macOS, Linux, Windows na komputerze)
Aby otrzymać kod autoryzacji za pomocą tego adresu URL, aplikacja musi nasłuchiwać na lokalnym serwerze WWW. Jest to możliwe na wielu platformach, ale nie na wszystkich. Jeśli jednak Twoja platforma to obsługuje, jest to zalecany mechanizm uzyskiwania kodu autoryzacji.
Gdy aplikacja otrzyma odpowiedź autoryzacyjną, powinna w celu zapewnienia jak największej wygody użytkownikowi wyświetlić stronę HTML z instrukcją zamknięcia przeglądarki i powrotu do aplikacji.
| Zalecane użycie | aplikacje na komputery z systemem macOS, Linux i Windows (ale nie aplikacje platformy uniwersalnej systemu Windows); |
| Wartości formularza | Ustaw typ aplikacji na Aplikacja na komputery. |
Ręczne kopiowanie i wklejanie (wycofane)
Ochrona aplikacji
Potwierdzanie własności aplikacji w Chrome
Możesz potwierdzić własność aplikacji, aby zmniejszyć ryzyko podszywania się pod nią.
Aby ukończyć proces weryfikacji, musisz użyć konta dewelopera w Chrome Web Store. Aby weryfikacja przebiegła pomyślnie, musisz spełnić te wymagania:
- Musisz mieć zarejestrowany element w panelu dewelopera Chrome Web Store z tym samym identyfikatorem co klient OAuth rozszerzenia Chrome, dla którego przeprowadzasz weryfikację.
- Musisz być wydawcą produktu w Chrome Web Store. Więcej informacji o zarządzaniu dostępem w Panelu dewelopera 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 przyznaniu dostępu do konta odczekaj kilka minut, zanim dokończysz proces weryfikacji.
Jeśli weryfikacja się powiedzie, wyświetli się powiadomienie z potwierdzeniem. W przeciwnym razie pojawi się komunikat o błędzie.
Aby naprawić nieudaną weryfikację:
- Sprawdź, czy w panelu dewelopera Chrome Web Store jest zarejestrowany produkt o tym samym identyfikatorze co klient OAuth rozszerzenia Chrome, dla którego przeprowadzasz weryfikację.
- Musisz być wydawcą aplikacji, czyli osobą fizyczną lub członkiem grupy wydawców aplikacji. Więcej informacji o zarządzaniu dostępem w panelu dewelopera Chrome Web Store
- Jeśli lista wydawców w grupie została właśnie zaktualizowana, sprawdź, czy lista członków grupy wydawców została zsynchronizowana w panelu dewelopera Chrome Web Store. Więcej informacji o synchronizowaniu listy uczestników programu wydawców
App Check (tylko iOS)
Funkcja Sprawdzanie aplikacji pomaga chronić aplikacje na iOS przed nieautoryzowanym użyciem. W tym celu korzysta z usługi App Attest firmy Apple, aby sprawdzać, czy żądania wysyłane do punktów końcowych Google OAuth 2.0 pochodzą z Twoich autentycznych aplikacji. Pomaga to zmniejszyć ryzyko podszywania się pod aplikację.
Włączanie Sprawdzania aplikacji na urządzeniu z iOS
Aby włączyć Sprawdzanie aplikacji na potrzeby klienta iOS, musisz spełnić te wymagania:- Musisz określić identyfikator zespołu dla klienta iOS.
- W identyfikatorze pakietu nie można używać symbolu wieloznacznego, ponieważ może on odnosić się do więcej niż 1 aplikacji. Oznacza to, że identyfikator pakietu nie może zawierać symbolu gwiazdki (*).
Po włączeniu Sprawdzania aplikacji w widoku edycji klienta OAuth zaczniesz widzieć dane dotyczące żądań OAuth pochodzących z Twojego klienta. Żądania z niezweryfikowanych źródeł nie będą blokowane, dopóki nie wymusisz weryfikacji aplikacji. Informacje na stronie monitorowania wskaźników mogą pomóc Ci określić, kiedy rozpocząć egzekwowanie.
Podczas włączania funkcji Sprawdzanie aplikacji w aplikacji na iOS mogą pojawić się błędy związane z tą funkcją. Aby je naprawić, wykonaj te czynności:
- Sprawdź, czy podane identyfikator pakietu i identyfikator zespołu są prawidłowe.
- Sprawdź, czy w identyfikatorze pakietu nie używasz symbolu wieloznacznego.
Wymuszanie sprawdzania aplikacji w przypadku klienta iOS
Włączenie Sprawdzania aplikacji nie powoduje automatycznego blokowania nierozpoznanych żądań. Aby włączyć 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 pochodzące od 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 wymuszania 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. W takich przypadkach pole refresh_token_expires_in zwrócone w odpowiedzi wymiany kodu autoryzacji reprezentuje czas pozostały do wygaśnięcia tokena odświeżania.
Więcej informacji
Wiele sprawdzonych metod opisanych w tym dokumencie zostało określonych w dokumencie 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 kilka przykładów typów zdarzeń wysyłanych do 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 dotyczącej ochrony kont użytkowników za pomocą ochrony wszystkich kont .