Z tego dokumentu dowiesz się, jak aplikacje zainstalowane na urządzeniach takich jak telefony, tablety i komputery używają punktów końcowych OAuth 2.0 Google do autoryzacji 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ć OAuth 2.0, aby uzyskać uprawnienia do przesyłania filmów na kanał użytkownika w YouTube.
Zainstalowane aplikacje są rozpowszechniane na poszczególne urządzenia i zakłada się, że te aplikacje nie są w stanie chronić tajemnic. Mogą one uzyskiwać dostęp do interfejsów API Google, gdy użytkownik korzysta z aplikacji lub gdy aplikacja działa w tle.
Ten proces autoryzacji jest podobny do tego, który jest używany w aplikacji serwera WWW. Główna różnica polega na tym, że zainstalowane aplikacje muszą otworzyć przeglądarkę systemową i podać lokalny identyfikator URI przekierowania, aby obsłużyć odpowiedzi z serwera autoryzacji Google.
Możliwości
W przypadku aplikacji mobilnych możesz użyć funkcji logowania w Google na Android lub iOS. Biblioteki klienta logowania w Google obsługują uwierzytelnianie i autoryzację użytkownika. Ich wdrożenie może być prostsze niż w przypadku opisanego tutaj protokołu niskiego poziomu.
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 (np. telewizory, konsole do gier, kamery czy drukarki), zapoznaj się z artykułami OAuth 2.0 na telewizorach i urządzeniach z ograniczoną możliwością wprowadzania danych lub Logowanie na telewizorach i urządzeniach z ograniczoną możliwością wprowadzania danych.
Biblioteki i próbki
Aby ułatwić Ci implementację opisanego w tym dokumencie procesu OAuth 2.0, zalecamy użycie tych bibliotek i próbek:
- Biblioteka AppAuth for Android
- Biblioteka AppAuth for iOS
- OAuth dla aplikacji: przykłady dla systemu Windows
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 też 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ć poświadczenia autoryzacyjne, które identyfikują ją na serwerze OAuth 2.0 Google. Z tych instrukcji dowiesz się, jak utworzyć poświadczenia tożsamości do projektu. Twoje aplikacje mogą wtedy używać tych danych logowania do uzyskiwania dostępu do interfejsów API, które zostały włączone w tym projekcie.
- Go to the Credentials page.
- Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
- W następnych sekcjach opisujemy typy klientów obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nadaj nazwę klientowi OAuth i właściwie skonfiguruj pozostałe pola formularza.
Android
- Wybierz typ aplikacji Android.
- Wpisz nazwę klienta OAuth. Ta nazwa jest widoczna na stronie projektu Credentials page , aby umożliwić identyfikację klienta.
- Wpisz nazwę pakietu aplikacji na Androida. Ta wartość jest zdefiniowana w
atrybutcie
packageelementu<manifest>w pliku manifestu aplikacji. - Wpisz odcisk cyfrowy certyfikatu podpisującego SHA-1 dystrybucji aplikacji.
- Jeśli Twoja aplikacja korzysta z podpisywania aplikacji przez Google Play, skopiuj odcisk cyfrowy SHA-1 ze strony podpisywania aplikacji w Konsoli Play.
- Jeśli zarządzasz własnym magazynem kluczy i kluczami podpisowymi, użyj narzędzia keytool dołączonego do Java, aby wydrukować informacje o certyfikacie w formatowalnym dla człowieka formacie. Skopiuj wartość
SHA1w sekcjiCertificate fingerprintsw danych wyjściowych narzędzia keytool. Więcej informacji znajdziesz w sekcji Uwierzytelnianie klienta w dokumentacji interfejsów API Google na Androida.
- (Opcjonalnie) Zweryfikuj własność aplikacji na Androida.
- Kliknij Utwórz.
iOS
- Wybierz typ aplikacji iOS.
- Wpisz nazwę klienta OAuth. Ta nazwa jest widoczna na stronie projektu Credentials page , aby umożliwić identyfikację klienta.
- Wpisz identyfikator pakietu aplikacji. Identyfikator pakietu to wartość klucza CFBundleIdentifier w pliku zasobu z informacjami o aplikacji (info.plist). Wartość ta jest najczęściej wyświetlana w panelu Ogólne lub w panelu Podpisywanie i możliwości edytora projektu Xcode. Identyfikator pakietu jest też widoczny w sekcji Informacje ogólne na stronie Informacje o aplikacji w usłudze App Store Connect firmy Apple.
Sprawdź, czy używasz prawidłowego identyfikatora pakietu aplikacji, ponieważ nie będzie można go zmienić, jeśli korzystasz z funkcji Sprawdzanie aplikacji.
- (Opcjonalnie)
Podaj identyfikator aplikacji w sklepie App Store, jeśli została ona opublikowana w sklepie App Store firmy Apple. Identyfikator sklepu to ciąg liczbowy zawarty w każdym adresie URL Apple App Store.
- Otwórz aplikację App Store na urządzeniu z iOS lub iPadOS.
- Wyszukaj swoją aplikację.
- Kliknij przycisk Udostępnij (symbol kwadratu z strzałką skierowaną w górę).
- Kliknij Kopiuj 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 dokumentacji dotyczącej konta dewelopera Apple w sekcji Znajdź identyfikator zespołu.
Uwaga: jeśli włączasz Sprawdzanie aplikacji dla klienta, pole Identyfikator zespołu jest wymagane. - (Opcjonalnie)
Włącz Sprawdzanie aplikacji w przypadku aplikacji na iOS. Gdy włączysz Sprawdzanie aplikacji, usługa App Attest firmy Apple będzie używana do sprawdzania, czy żądania OAuth 2.0 pochodzące z Twojego klienta OAuth są autentyczne i pochodzą z Twojej aplikacji. Pomaga to zmniejszyć ryzyko podszywania się pod aplikację. Więcej informacji o włączaniu Sprawdzania aplikacji w przypadku aplikacji na iOS
- Kliknij Utwórz.
UWP
- Wybierz typ aplikacji Universal Windows Platform.
- Wpisz nazwę klienta OAuth. Ta nazwa jest widoczna na stronie projektu Credentials page , aby umożliwić identyfikację klienta.
- Wpisz 12-znakowy identyfikator aplikacji w Microsoft Store. Znajdziesz ją 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.
Określanie zakresów dostępu
Zakresy umożliwiają aplikacji żądanie dostępu tylko do zasobów, których potrzebuje, a także kontrolowanie przez użytkowników zakresu dostępu przyznawanego aplikacji. Dlatego może istnieć odwrotna zależność między liczbą żądanych zakresów uprawnień a prawdopodobieństwom 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 Data API v3 korzysta z tych zakresów:
| Zakresy | |
|---|---|
| https://www.googleapis.com/auth/youtube | Zarządzanie kontem YouTube |
| https://www.googleapis.com/auth/youtube.channel-memberships.creator | Wyświetlanie listy aktualnie aktywnych użytkowników wspierających kanał, ich obecnych poziomów i dat rozpoczęcia wsparcia |
| https://www.googleapis.com/auth/youtube.force-ssl | Przeglądanie, edytowanie i trwałe usuwanie Twoich filmów, ocen, komentarzy i napisów z YouTube |
| https://www.googleapis.com/auth/youtube.readonly | Wyświetlanie konta YouTube |
| https://www.googleapis.com/auth/youtube.upload | Zarządzanie filmami w YouTube |
| https://www.googleapis.com/auth/youtubepartner | Przeglądaj zasoby oraz powiązane treści i zarządzaj nimi w serwisie YouTube |
| https://www.googleapis.com/auth/youtubepartner-channel-audit | 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.
Pobieranie tokenów dostępu OAuth 2.0
Te czynności pokazują, jak aplikacja wchodzi w interakcję z serwerem OAuth 2.0 Google, aby uzyskać zgodę użytkownika na wykonanie żądania interfejsu API w imieniu tego użytkownika. Aplikacja musi mieć tę zgodę, zanim będzie mogła wykonać żądanie interfejsu Google API, które wymaga 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 procesu instalowania aplikacji. W przypadku każdego żądania autoryzacji tworzony jest unikalny weryfikator kodu, a jego przekształcona wartość, zwana „code_challenge”, jest wysyłana na serwer autoryzacji w celu uzyskania kodu autoryzacji.
Tworzenie weryfikatora kodu
code_verifier to losowy ciąg znaków kryptograficznych o wysokiej entropii, który wykorzystuje niezarezerwowane znaki [A-Z] / [a-z] / [0-9] / „-” / „.” / „_” / „~”, o długości co najmniej 43 znaków i maksymalnie 128 znaków.
Weryfikator kodu powinien mieć wystarczającą ilość entropii, aby uniemożliwić odgadnięcie wartości.
Tworzenie zadania z programowania
Obsługiwane są 2 metody tworzenia kodu weryfikacyjnego.
| Metody generowania zadań testu zabezpieczającego | |
|---|---|
| S256 (zalecane) | Wyzwanie kodu to skrót SHA256 z kodowaniem Base64URL (bez dopełnienia) weryfikatora kodu.
|
| plain | Wyzwanie kodu ma taką samą wartość jak wygenerowany powyżej weryfikator kodu.
|
Krok 2. Wyślij żądanie do serwera Google OAuth 2.0
Aby uzyskać autoryzację użytkownika, wyślij żądanie do serwera autoryzacji Google pod adresem https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy obsługuje wyszukiwanie aktywnej sesji, uwierzytelnia użytkownika i uzyskiwanie jego zgody. Punkt końcowy jest dostępny tylko przez SSL i odrzuca połączenia HTTP (nie SSL).
Serwer autoryzacji obsługuje te parametry ciągu zapytania w przypadku zainstalowanych aplikacji:
| Parametry | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Wymagany
Identyfikator klienta Twojej aplikacji. Znajdziesz ją w sekcji API Console: Credentials 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 do zainstalowanych aplikacji. Musisz skonfigurować uprawnienia autoryzacji z uwzględnieniem konkretnej metody przekierowania. Wartość musi dokładnie pasować do jednego z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API Console
Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego adresu URI, pojawi się błąd Tabela poniżej zawiera odpowiednią wartość parametru |
||||||||||||||||
response_type |
Wymagany
Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji. W przypadku zainstalowanych aplikacji ustaw wartość parametru na |
||||||||||||||||
scope |
Wymagany
Oddzielona spacjami lista zakresów, które identyfikują zasoby, do których aplikacja może uzyskać dostęp w imieniu użytkownika. Te wartości informują o ekranie zgody, który Google wyświetla użytkownikowi. Zakresy umożliwiają aplikacji żądanie dostępu tylko do zasobów, których potrzebuje, a także kontrolowanie przez użytkowników zakresu dostępu przyznawanego aplikacji. W związku z tym istnieje odwrotna zależność między liczbą żądanych zakresów uprawnień a prawdopodobieństwom uzyskania zgody użytkownika. Interfejs YouTube Data API v3 korzysta z 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żytą do zakodowania |
||||||||||||||||
state |
Zalecane
Określa dowolną wartość ciągu znaków, której aplikacja używa do zachowania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji.
Serwer zwraca dokładną wartość, którą wysyłasz jako parę Parametru tego można używać do różnych celów, np. do kierowania użytkownika do odpowiedniego zasobu w aplikacji, wysyłania identyfikatorów jednorazowych i ograniczania fałszowania żądań między witrynami. Ponieważ wartość |
||||||||||||||||
login_hint |
Opcjonalny
Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby przekazać wskazówkę serwerowi uwierzytelniania Google. Serwer używa tego podpowiedzi do uproszczenia procesu logowania, wypełniając wstępnie pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję logowania wielokrotnego. Ustaw wartość parametru jako adres e-mail lub identyfikator |
||||||||||||||||
Przykładowe adresy URL autoryzacji
Na kartach poniżej znajdziesz przykładowe adresy URL autoryzacji dla różnych opcji przekierowania URI.
Każdy adres URL prosi o dostęp do zakresu, który umożliwia wyświetlanie konta YouTube użytkownika.Adresy URL są identyczne z wyjątkiem wartości parametru redirect_uri. Adresy URL zawierają też wymagane parametry response_type i client_id, a także opcjonalny parametr state. Każdy adres URL zawiera podziały wiersza i spacje w celu ułatwienia czytelności.
Niestandardowy schemat identyfikatora URI
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
Adres IP pętli zwrotnej
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Krok 3. Google prosi użytkownika o zgodę
Na tym etapie użytkownik decyduje, czy przyznać Twojej aplikacji wymagany dostęp. Na tym etapie Google wyświetla okno zgody, w którym podaje nazwę aplikacji i usługi interfejsu API Google, do której chce uzyskać dostęp, wraz z danymi autoryzującymi użytkownika oraz podsumowaniem zakresów dostępu. Użytkownik może wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu żądanego przez Twoją aplikację lub odrzucić prośbę.
Na tym etapie aplikacja nie musi nic robić, ponieważ czeka na odpowiedź z serwera OAuth 2.0 Google, która wskazuje, czy przyznano dostęp. Odpowiedź na to pytanie znajdziesz w następnym kroku.
Błędy
Żądania do punktu końcowego autoryzacji OAuth 2.0 Google mogą wyświetlać komunikaty o błędach zamiast oczekiwanych procesów uwierzytelniania i autoryzacji. Poniżej znajdziesz listę typowych kodów błędów i sugerowanych rozwiązań.
admin_policy_enforced
Konto Google nie może autoryzować co najmniej 1 żądanego zakresu uprawnień z powodu zasad administratora Google Workspace. Więcej informacji o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów poufnych i ograniczonych, dopóki nie zostanie wyraźnie przyznany dostęp do Twojego identyfikatora klienta OAuth, znajdziesz w artykule pomocy dla administratorów Google Workspace Control which third-party & internal apps access Google Workspace data.
disallowed_useragent
Punkt końcowy autoryzacji jest wyświetlany w ramach wbudowanego użytkownika-agenta, który jest niedozwolony przez zasady OAuth 2.0 Google.
Android
Deweloperzy aplikacji na Androida mogą zobaczyć ten komunikat o błędzie podczas otwierania żądań autoryzacji w android.webkit.WebView.
Deweloperzy powinni zamiast tego używać bibliotek Androida, takich jak Logowanie przez Google na Androida czy AppAuth na Androida od OpenID Foundation.
Deweloperzy mogą napotkać ten błąd, gdy aplikacja na Androida otwiera ogólny link internetowy w osadzonym user-agent i użytkownik przechodzi na punkt końcowy autoryzacji OAuth 2 Google z Twojej witryny. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym obsłudze linków systemu operacyjnego, co obejmuje zarówno obsługę linków aplikacji na Androida, jak i domyślną aplikację przeglądarki. Biblioteka kart niestandardowych Androida jest też obsługiwaną opcją.
iOS
Deweloperzy 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 Google Sign-In na iOS czy AppAuth na iOS od OpenID Foundation.
Deweloperzy witryn mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otwiera ogólny link internetowy w osadzonym user-agent i użytkownik przechodzi do punktu autoryzacji OAuth 2.0 Google z Twojej witryny. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym obsłudze linków systemu operacyjnego, który obejmuje zarówno obsługę linków uniwersalnych, jak i domyślną aplikację przeglądarki. Biblioteka SFSafariViewController jest też obsługiwaną opcją.
org_internal
Identyfikator klienta OAuth w żądaniu należy do 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 pomocy Konfigurowanie ekranu zgody OAuth.
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 skonfigurowany.
Podczas odświeżania tokena dostępu może się okazać, że token wygasł lub został unieważniony. Użytkownik musi się ponownie uwierzytelnić i wyrazić zgodę na uzyskanie nowych tokenów. Jeśli ten błąd będzie się powtarzał, sprawdź, czy aplikacja jest prawidłowo skonfigurowana i czy używasz w żądaniu prawidłowych tokenów i parametrów. W przeciwnym razie konto użytkownika mogło zostać usunięte lub wyłączone.
redirect_uri_mismatch
Wartość redirect_uri przekazana w żądaniu autoryzacji nie odpowiada autoryzowanemu identyfikatorowi URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania w sekcji Google API Console Credentials page.
Podana wartość redirect_uri może być nieprawidłowa dla typu klienta.
Parametr redirect_uri może odnosić się do przesyłania poza pasmem (OOB) w ramach protokołu OAuth, które zostało wycofane i nie jest już obsługiwane. Aby zaktualizować integrację, zapoznaj się z przewodnikiem po migracji.
invalid_request
Coś poszło nie tak z Twoją prośbą. Może to wynikać z kilku powodów:
- żądanie jest nieprawidłowo sformatowane;
- Brak wymaganych parametrów w prośbie
- Żądanie używa metody autoryzacji, której Google nie obsługuje. Sprawdź, czy integracja OAuth używa zalecanej metody integracji
- W przypadku adresu URI przekierowania używany jest niestandardowy schemat : jeśli widzisz komunikat o błędzie Niestandardowy schemat URI nie jest obsługiwany w aplikacjach Chrome lub Niestandardowy schemat URI nie jest włączony dla klienta na Androida, oznacza to, że używasz niestandardowego schematu URI, który nie jest obsługiwany w aplikacjach Chrome i domyślnie jest wyłączony na Androidzie. Dowiedz się więcej o niestandardowych schematach URI i ich alternatywach
Krok 4. Przetwórz odpowiedź serwera OAuth 2.0
Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacji, zależy od schematu identyfikatora URI przekierowania, którego używa. Niezależnie od schematu odpowiedź będzie zawierać kod autoryzacji (code) lub błąd (error). Na przykład error=access_denied wskazuje, że użytkownik odrzucił żądanie.
Jeśli użytkownik przyzna dostęp do aplikacji, możesz wymienić kod autoryzacji na token dostępu i token odświeżania w sposób opisany 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 API Console Credentials page. |
client_secret |
Tajny klucz klienta uzyskany z API Console Credentials page. |
code |
Kod autoryzacji zwrócony w odpowiedzi na początkowe żądanie. |
code_verifier |
Weryfikator kodu utworzony w kroku 1. |
grant_type |
Zgodnie ze specyfikacją OAuth 2.0 wartość tego pola musi wynosić authorization_code. |
redirect_uri |
Jeden z identyfikatorów URI przekierowania podanych w przypadku Twojego projektu w sekcji API Console
Credentials page w przypadku danego client_id. |
Ten fragment kodu pokazuje przykładowe żądanie:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
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 interfejsu Google API. |
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 Twoje żądanie zawiera zakres tożsamości, taki jak 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 czasu, gdy użytkownik anuluje dostęp. Pamiętaj, że tokeny odświeżania są zawsze zwracane w przypadku zainstalowanych aplikacji. |
scope |
Zakresy dostępu przyznane przez access_token wyrażone jako lista rozróżniających wielkość liter ciągów znaków oddzielonych spacjami. |
token_type |
Typ zwróconego tokena. Obecnie wartość tego pola zawsze wynosiBearer. |
Ten 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", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Krok 6. Sprawdź, jakie zakresy przyznali użytkownicy
Gdy żądasz dostępu do wielu zakresów naraz, użytkownicy mogą nie przyznać dostępu do wszystkich zakresów, o które prosi Twoja aplikacja. Aplikacja powinna zawsze sprawdzać, jakie zakresy zostały przyznane przez użytkownika, i w przypadku odmowy przyznania zakresu wyłączać odpowiednie funkcje. Więcej informacji znajdziesz w artykule Zarządzanie szczegółowymi uprawnieniami.
Aby sprawdzić, czy użytkownik przyznał aplikacji dostęp do określonego zakresu, sprawdź pole scope w odpowiedzi na żądanie tokena dostępu. Zakresy dostępu przyznawane przez token dostępu w postaci listy ciągów znaków oddzielonych spacjami, w których rozróżniane są wielkość liter.
Na przykład ta przykładowa odpowiedź na żądanie tokena dostępu wskazuje, że użytkownik przyznał Twojej aplikacji uprawnienia do przeglądania, edytowania i trwałego usuwania filmów, ocen, komentarzy i napisów użytkownika w YouTube:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Wywoływanie interfejsów API Google
Gdy aplikacja uzyska token dostępu, możesz używać tego tokena do wywoływania interfejsów API Google w imieniu danego konta użytkownika, jeśli przyznano uprawnienia dostępu wymagane przez interfejs API. Aby to zrobić, dodaj token dostępu do żądania do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka HTTP Authorization Bearer. Jeśli to możliwe, zalecamy użycie nagłówka HTTP, ponieważ ciągi znaków zapytania są zwykle widoczne w dziennikach 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 Data API).
Pamiętaj, że interfejs YouTube Data API obsługuje konta usługowe tylko w przypadku właścicieli treści w YouTube, którzy są właścicielami wielu kanałów YouTube i nimi zarządzają, np. wytwórni muzycznych czy studiów filmowych.
Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy na stronie OAuth 2.0 Playground.
Przykłady żądań HTTP GET
Wywołanie punktu końcowego
youtube.channels (interfejsu YouTube Data API) za pomocą nagłówka HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz podać własny token dostępu:
GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Oto wywołanie tego samego interfejsu API dla uwierzytelnionego użytkownika za pomocą parametru ciągu zapytania access_token:
GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
curl przykładu
Te polecenia możesz przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład użycia opcji nagłówka HTTP (preferowana):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true
Możesz też użyć parametru ciągu zapytania:
curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
Odświeżanie tokena dostępu
Tokeny dostępu okresowo wygasają i stają się nieprawidłowymi danymi logowania w przypadku powiązanego żądania interfejsu API. Jeśli poprosisz o dostęp offline do zakresów powiązanych z tokenem, możesz odświeżyć token dostępu bez wyświetlania użytkownikowi prośby o pozwolenie (także wtedy, gdy użytkownika nie ma w pobliżu).
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.
(client_secret nie dotyczy żądań od klientów zarejestrowanych jako aplikacje na Androida, iOS lub Chrome).
|
grant_type |
Zgodnie z specyfikacją OAuth 2.0 wartość tego pola musi wynosić refresh_token. |
refresh_token |
Token odświeżania zwrócony z wymiany kodu autoryzacji. |
Ten fragment kodu pokazuje przykładowe żądanie:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
Dopóki użytkownik nie cofnie przyznanego aplikacji dostępu, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Ten fragment kodu pokazuje 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 liczba wydawanych tokenów odświeżania jest ograniczona. Jeden limit dotyczy kombinacji klient/użytkownik, a drugi – wszystkich klientów. Tokeny odświeżania należy zapisać w długoterminowym magazynie danych i nadal z nich korzystać, dopóki są ważne. Jeśli aplikacja wysyła zbyt dużo żądań dotyczących 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 chcieć cofnąć dostęp aplikacji. Użytkownik może cofnąć dostęp, otwierając Ustawienia konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu strony lub aplikacji do Twojego konta w dokumentacji pomocy Strony internetowe i aplikacje innych firm z dostępem do Twojego konta.
Aplikacja może też automatycznie cofnąć przyznany dostęp. Automatyczne odwoływanie jest ważne w przypadkach, gdy użytkownik zrezygnuje z subskrypcji, usunie aplikację lub zasoby interfejsu API wymagane przez aplikację ulegną znacznym zmianom. Innymi słowy, część procesu usuwania może obejmować żądanie interfejsu API, aby usunąć uprawnienia wcześniej przyznane aplikacji.
Aby programowo unieważnić token, aplikacja wysyła żądanie do interfejsu https://oauth2.googleapis.com/revoke, dołączając token jako parametr:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}Token może być tokenem dostępu lub tokenem odświeżania. Jeśli token jest tokenem dostępu i ma odpowiadający mu token odświeżania, token odświeżania zostanie również cofnięty.
Jeśli odwołanie zostało przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędów zwracany jest kod stanu HTTP 400 oraz kod błędu.
Metody przekierowania aplikacji
Niestandardowy schemat identyfikatora URI (Android, iOS, UWP)
Niestandardowe schematy identyfikatorów URI to forma precyzyjnych linków, które do otwierania aplikacji używają niestandardowego schematu.
Alternatywa dla korzystania z niestandardowych schematów URI na Androidzie
Użyj pakietu SDK logowania Google na Androida, który przekazuje odpowiedź OAuth 2.0 bezpośrednio do aplikacji, co eliminuje konieczność korzystania z adresu URI przekierowania.
Jak przejść na pakiet SDK Logowania przez Google na Androida
Jeśli do integracji OAuth na Androidzie używasz niestandardowego schematu, musisz wykonać te czynności, aby w pełni przejść na zalecany pakiet SDK Logowania w Google na Androida:
- Zaktualizuj kod, aby używać pakietu SDK logowania w Google.
- Wyłącz obsługę schematu niestandardowego w Konsoli interfejsów API Google.
Aby przejść na pakiet Android SDK logowania w Google, wykonaj te czynności:
-
Zaktualizuj kod, aby używać pakietu Android SDK do logowania się w Google:
-
Sprawdź kod, aby znaleźć miejsce, w którym wysyłasz żądanie do serwera OAuth 2.0 Google. Jeśli używasz schematu niestandardowego, Twoje żą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:/oauth2redirectto identyfikator URI przekierowania w ramach schematu niestandardowego w przykładzie powyżej. Więcej informacji o formacie wartości niestandardowego schematu URI znajdziesz w definicji parametruredirect_uri. -
Zanotuj parametry żądania
scopeiclient_id, których będziesz potrzebować do skonfigurowania pakietu SDK logowania w Google. -
Aby skonfigurować pakiet SDK, wykonaj instrukcje podane w artykule
Rozpoczęcie integracji logowania Google z aplikacją na Androida. Możesz pominąć krok Uzyskaj identyfikator klienta OAuth 2.0 serwera zaplecza, ponieważ
client_iduzyskany w poprzednim kroku będzie używany ponownie. -
Wykonaj czynności opisane w
instrukcji włączania dostępu do interfejsu API po stronie serwera. Obejmuje ona te czynności:
-
Aby pobrać kod uwierzytelniający dla zakresów, których dotyczy prośba o uprawnienia, użyj metody
getServerAuthCode. - Wyślij kod uwierzytelniający do backendu aplikacji, aby wymienić go na token dostępu i odświeżania.
- Użyj pobranego tokena dostępu, aby wywoływać interfejsy API Google w imieniu użytkownika.
-
Aby pobrać kod uwierzytelniający dla zakresów, których dotyczy prośba o uprawnienia, użyj metody
-
Sprawdź kod, aby znaleźć miejsce, w którym wysyłasz żądanie do serwera OAuth 2.0 Google. Jeśli używasz schematu niestandardowego, Twoje żą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łącz niestandardowy schemat URI
Jeśli zalecana alternatywa nie działa, możesz włączyć niestandardowe schematy URI dla klienta Androida, wykonując te czynności:- 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.
Alternatywa dla korzystania z niestandardowych schematów URI w aplikacjach Chrome
Użyj interfejsu Chrome Identity API, który przekazuje odpowiedź OAuth 2.0 bezpośrednio do aplikacji, co eliminuje konieczność korzystania z identyfikatora URI przekierowania.
Adres IP 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 wyświetlić stronę HTML z instrukcją, aby użytkownik zamknął przeglądarkę i wrócił do aplikacji.
| Zalecane użycie | aplikacje na komputery z systemem macOS, Linux i Windows (ale nie na platformę uniwersalną systemu Windows); |
| Wartości formularzy | Jako typ aplikacji wybierz Aplikacja na komputer. |
Ręczne kopiowanie/wklejanie (wycofane)
Chroń swoje aplikacje
Potwierdzanie prawa własności do aplikacji (Android, Chrome)
Aby zmniejszyć ryzyko podszywania się pod aplikację, możesz zweryfikować prawo własności do niej.
Android
Aby przejść 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 przejść weryfikację, musisz spełnić te wymagania:
- W Konsoli Google Play musisz mieć zarejestrowaną aplikację z tą samą nazwą pakietu i odciskiem cyfrowym certyfikatu podpisującego SHA-1 co klient OAuth na Androida, którego weryfikację chcesz przeprowadzić.
- W Konsoli Google Play musisz mieć uprawnienia Administratora w przypadku tej aplikacji. Dowiedz się więcej o zarządzaniu dostępem w Konsoli Google Play.
W sekcji Weryfikacja własności aplikacji w kliencie na Androida kliknij przycisk Zweryfikuj własność, aby dokończyć proces weryfikacji.
Jeśli weryfikacja się powiedzie, wyświetli się powiadomienie z potwierdzeniem zakończenia procesu weryfikacji. W przeciwnym razie pojawi się komunikat o błędzie.
Aby naprawić nieudaną weryfikację:
- Upewnij się, że aplikacja, którą weryfikujesz, jest zarejestrowana w Konsoli Google Play.
- Sprawdź, czy w Konsoli Google Play masz uprawnienia administratora w odniesieniu do tej aplikacji.
Chrome
Aby ukończyć proces weryfikacji, musisz użyć konta dewelopera w Chrome Web Store. Aby przejść weryfikację, musisz spełnić te wymagania:
- Musisz mieć zarejestrowany produkt w panelu dewelopera Chrome Web Store z tym samym identyfikatorem produktu co klient OAuth rozszerzenia Chrome, którego dotyczy weryfikacja.
- Musisz być wydawcą produktu 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 w kliencie rozszerzenia Chrome kliknij przycisk Zweryfikuj własność, aby dokończyć proces weryfikacji.
Uwaga: po przyznaniu dostępu do konta odczekaj kilka minut, zanim zakończysz proces weryfikacji.
Jeśli weryfikacja się powiedzie, wyświetli się powiadomienie z potwierdzeniem zakończenia procesu weryfikacji. W przeciwnym razie pojawi się komunikat o błędzie.
Aby naprawić nieudaną weryfikację:
- Upewnij się, że w panelu dewelopera Chrome Web Store jest zarejestrowany produkt z tym samym identyfikatorem produktu co klient OAuth rozszerzenia Chrome, którego dotyczy weryfikacja.
- Upewnij się, że jesteś wydawcą aplikacji, czyli jesteś albo wydawcą indywidualnym, albo członkiem grupy wydawców aplikacji. Dowiedz się więcej o zarządzaniu dostępem w panelu dewelopera w Chrome Web Store.
- Jeśli właśnie zaktualizowałeś listę grup wydawców, sprawdź, czy lista członków grupy wydawców jest zsynchronizowana w panelu dewelopera Chrome Web Store. Dowiedz się więcej o synchronizowaniu listy wydawców.
Sprawdzanie aplikacji (tylko iOS)
Funkcja Sprawdzanie aplikacji pomaga chronić aplikacje na iOS przed nieautoryzowanym użyciem. Wykorzystuje do tego usługę 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ę w aplikacji.
Włącz Sprawdzanie aplikacji dla klienta na iOS
Aby móc włączyć Sprawdzanie aplikacji dla klienta na iOS, musisz spełnić te wymagania:- Musisz podać identyfikator zespołu dla klienta na iOS.
- W identyfikatorze pakietu nie można używać symboli wieloznacznych, ponieważ może to spowodować, że identyfikator będzie wskazywał więcej niż 1 aplikację. Oznacza to, że identyfikator pakietu nie może zawierać symbolu gwiazdki (*).
Po włączeniu Sprawdzania aplikacji w oknie edycji klienta OAuth zaczniesz widzieć dane dotyczące żądań OAuth z Twojego klienta. Żądania z niezweryfikowanych źródeł nie będą blokowane, dopóki nie włączysz sprawdzania aplikacji. Informacje na stronie monitorowania wskaźników mogą pomóc Ci określić, kiedy rozpocząć egzekwowanie zasad.
Po włączeniu funkcji sprawdzania aplikacji na urządzeniu z iOS mogą pojawić się błędy związane z tą funkcją. Aby je naprawić, wykonaj te czynności:
- Sprawdź, czy podany identyfikator pakietu i identyfikator zespołu są prawidłowe.
- Sprawdź, czy identyfikator pakietu nie zawiera symbolu wieloznacznego.
Wymuszanie Sprawdzania aplikacji na kliencie iOS
Włączenie Sprawdzania aplikacji nie powoduje automatycznego blokowania nierozpoznanych żądań. Aby zastosować to zabezpieczenie, przejdź do widoku edycji klienta na iOS. Po prawej stronie strony w sekcji Tożsamość Google w iOS znajdziesz dane Sprawdzania aplikacji. Dane obejmują:- Liczba zweryfikowanych żądań – żądania z prawidłowym tokenem Sprawdzania aplikacji. Gdy włączysz egzekwowanie kontroli aplikacji, tylko żądania z tej kategorii będą się udawać.
- 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ć sprawdzanie aplikacji, kliknij przycisk ENFORCE i potwierdź swój wybór. Gdy wymuszanie będzie aktywne, wszystkie niezweryfikowane żądania wysyłane przez Twojego klienta będą odrzucane.
Uwaga: po włączeniu egzekwowania zmian może minąć do 15 minut, zanim zaczną one obowiązywać.
Wyłącz wymuszanie Sprawdzania aplikacji w przypadku klienta na iOS
Wyłączenie wymuszania Sprawdzania aplikacji spowoduje zaprzestanie wymuszania i zezwoli na wszystkie żądania wysyłane przez Twojego klienta do punktów końcowych Google OAuth 2.0, w tym niezweryfikowane żądania.
Aby wyłączyć sprawdzanie aplikacji w przypadku klienta na iOS, otwórz widok edycji klienta na iOS i kliknij przycisk WYŁĄCZ, a potem potwierdź swój wybór.
Uwaga: po wyłączeniu sprawdzania aplikacji wprowadzenie zmian może potrwać do 15 minut.
Wyłączanie Sprawdzania aplikacji w przypadku klienta iOS
Wyłączenie Sprawdzania aplikacji spowoduje zaprzestanie wszystkich działań związanych z monitorowaniem i wymuszaniem. Rozważ wyłączenie Sprawdzania aplikacji, aby móc nadal monitorować dane klienta.
Aby wyłączyć Sprawdzanie aplikacji dla klienta na iOS, otwórz widok edycji klienta na iOS i wyłącz przełącznik Chroń klienta OAuth przed nadużyciami przy pomocy Sprawdzania aplikacji Firebase.
Uwaga: po wyłączeniu funkcji sprawdzania aplikacji wprowadzenie zmian może potrwać do 15 minut.
Więcej informacji
Wiele sprawdzonych metod opisanych w tym dokumencie zostało podanych w raporcie IETF OAuth 2.0 for Native Apps (Najlepsze metody IETF dotyczące OAuth 2.0 w przypadku aplikacji natywnych).
Wdrażanie Ochrony wszystkich kont
Dodatkowym krokiem, który należy wykonać, aby chronić konta użytkowników, jest wdrożenie ochrony na wielu kontach za pomocą usługi Google Cross-Account Protection. 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. Następnie możesz podjąć odpowiednie działania w zależności od tego, jak chcesz reagować na zdarzenia.
Przykłady typów zdarzeń wysyłanych do Twojej aplikacji przez usługę ochrony na wielu kontach:
-
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 oraz pełną listę dostępnych zdarzeń znajdziesz na stronie Ochrona kont użytkowników za pomocą ochrony wszystkich kont .