Ten dokument wyjaśnia, jak zaimplementować autoryzację OAuth 2.0, aby uzyskać dostęp do interfejsów API Google z aplikacji internetowej JavaScript. Protokół 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 do uzyskiwania od użytkowników uprawnień do przechowywania plików na ich Dyskach Google.
Ten proces OAuth 2.0 jest nazywany domyślnym przebiegiem przyznania. Jest ona przeznaczona dla aplikacji, które korzystają z interfejsów API tylko wtedy, gdy użytkownik korzysta z aplikacji. Te aplikacje nie mogą przechowywać informacji poufnych.
W ramach tego procesu aplikacja otwiera adres URL Google, który używa parametrów zapytania, aby zidentyfikować Twoją aplikację, oraz typ dostępu API, którego wymaga aplikacja. Adres URL możesz otworzyć w bieżącym oknie przeglądarki lub w wyskakującym okienku. Użytkownik może uwierzytelnić się w Google i udzielić wymaganych uprawnień. Następnie Google przekierowuje użytkownika z powrotem do Twojej aplikacji. Przekierowanie zawiera token dostępu, który aplikacja weryfikuje i wykorzystuje do przesyłania żądań do interfejsu API.
Biblioteka klienta interfejsów API Google i Usługi tożsamości Google
Jeśli do wykonywania autoryzowanych wywołań Google używa biblioteki klienta interfejsów API Google do obsługi JavaScriptu, do obsługi protokołu OAuth 2.0 używaj biblioteki JavaScript Google Identity Services. Zapoznaj się z modelem usługi tożsamości Google, który jest oparty na przepływie przyzwyczajeń OAuth 2.0.
Wymagania wstępne
Włącz interfejsy API w swoim projekcie
Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć te interfejsy w interfejsie 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 liście API Library znajdziesz wszystkie dostępne interfejsy API pogrupowane według rodziny usług i popularności. Jeśli interfejsu API, który chcesz włączyć, nie widać na liście, wyszukaj go lub kliknij Wyświetl wszystkie w rodzinie usług, do której należy.
- Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
Tworzenie danych uwierzytelniających
Każda aplikacja, która uzyskuje dostęp do interfejsów API Google przy użyciu protokołu OAuth 2.0, musi mieć dane uwierzytelniające, które identyfikują aplikację na serwerze OAuth 2.0 Google. Z instrukcji poniżej dowiesz się, jak utworzyć dane logowania w projekcie. Dzięki temu aplikacje mogą używać danych logowania do uzyskiwania dostępu do interfejsów API włączonych w tym projekcie.
- Go to the Credentials page.
- Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
- Jako typ aplikacji wybierz Aplikacja internetowa.
- Wypełnij formularz. Aplikacje korzystające z JavaScriptu do wysyłania autoryzowanych żądań do interfejsu API Google muszą określać autoryzowane źródła JavaScriptu. Źródła wskazują domeny, z których aplikacja może wysyłać żądania do serwera OAuth 2.0. Te źródła muszą być zgodne z regułami weryfikacji Google.
Określ zakresy dostępu
Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, jednocześnie umożliwiając użytkownikom kontrolę nad poziomem dostępu, jaki przyznają aplikacji. W związku z tym może wystąpić odwrotna różnica między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.
Zanim zaczniesz wdrażać autoryzację OAuth 2.0, zalecamy wskazanie zakresów, do których aplikacja będzie potrzebowała dostępu.
Dokument Zakresy interfejsów API OAuth 2.0 zawiera pełną listę zakresów, których możesz używać do uzyskiwania dostępu do interfejsów API Google.
Uzyskiwanie tokenów dostępu OAuth 2.0
Poniżej znajdziesz opis interakcji Twojej aplikacji z serwerem OAuth 2.0 Google, aby uzyskać zgodę użytkownika na wysłanie żądania do interfejsu API w imieniu użytkownika. Twoja aplikacja musi uzyskać tę zgodę, zanim będzie mogła wykonać żądanie do interfejsu Google API, które wymaga autoryzacji użytkownika.
Krok 1. Przekieruj na serwer OAuth 2.0 Google
Aby poprosić o dostęp do danych użytkownika, przekieruj go na serwer OAuth 2.0 Google.
Punkty końcowe OAuth 2.0
Wygeneruj URL, aby poprosić o dostęp z punktu końcowego OAuth 2.0 Google na stronie https://accounts.google.com/o/oauth2/v2/auth
. Ten punkt końcowy jest dostępny przez HTTPS; zwykłe połączenia HTTP są odrzucane.
Serwer autoryzacji Google obsługuje następujące parametry ciągu zapytania dla aplikacji serwera WWW:
Parametry | |||||||
---|---|---|---|---|---|---|---|
client_id |
Wymagane
Identyfikator klienta Twojej aplikacji. Tę wartość możesz znaleźć w API Console Credentials page. |
||||||
redirect_uri |
Wymagane
Określa, gdzie serwer interfejsu API przekierowuje użytkownika po zakończeniu procesu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanego w API Consoleklienta Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI przekierowania dla podanego Pamiętaj, że wszystkie elementy ( |
||||||
response_type |
Wymagane
Aplikacje JavaScript muszą ustawić wartość parametru na |
||||||
scope |
Wymagane
Lista rozdzielonych spacjami zakresów identyfikujących zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi. Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, jednocześnie umożliwiając użytkownikom kontrolowanie poziomu dostępu, który przyznają aplikacji. W związku z tym występuje odwrotna relacja między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika. Zalecamy, aby w miarę możliwości Twoja aplikacja prosiła o dostęp do zakresów autoryzacji w odpowiednim kontekście. Prosząc użytkowników o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz im zorientowanie się, dlaczego aplikacja potrzebuje dostępu do danych, o które prosi. |
||||||
state |
Zalecane
Określa wartość ciągu używaną przez aplikację do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji.
Gdy użytkownik wyrazi zgodę na dostęp do aplikacji lub go odrzuci, serwer zwraca dokładną wartość, która jest wysyłana jako para Możesz używać tego parametru do różnych celów, np. kierowania użytkownika do właściwego zasobu w aplikacji, wysyłania liczb jednorazowych i zwalczania fałszerstwa żądań z innych witryn. Wartość |
||||||
include_granted_scopes |
Opcjonalny
Zezwala aplikacjom na używanie przyrostowej autoryzacji do żądania dostępu do dodatkowych zakresów kontekstowych. Jeśli ustawisz wartość tego parametru na |
||||||
login_hint |
Opcjonalny
Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może wykorzystać ten parametr do przekazania wskazówek do serwera uwierzytelniania Google. Aby uprościć proces logowania, serwer używa podpowiedzi, wypełniając pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania. Ustaw wartość parametru na adres e-mail lub identyfikator |
||||||
prompt |
Opcjonalny
Rozdzielona spacjami wielkość liter z prośbą o przedstawienie użytkownika. Jeśli nie określisz tego parametru, użytkownik otrzyma prośbę tylko wtedy, gdy pierwszy raz poprosi Twój projekt o dostęp. Więcej informacji znajdziesz w sekcji Prośba o ponowne wyrażenie zgody na wykorzystanie danych. Możliwe wartości to:
|
Przykładowe przekierowanie na serwer autoryzacji Google
Poniżej znajduje się przykładowy adres URL z podziałami między wierszami i spacjami pod kątem czytelności.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Po utworzeniu adresu URL żądania przekieruj użytkownika do tego adresu.
Przykładowy kod JavaScript
Ten fragment kodu JavaScript pokazuje, jak rozpocząć proces autoryzacji w języku JavaScript bez korzystania z biblioteki klienta interfejsów API Google. Ten punkt końcowy OAuth 2.0 nie obsługuje współdzielenia zasobów między serwerami z różnych źródeł (fragmenty kodu), dlatego fragment kodu tworzy formularz otwierający żądanie kierowane do tego punktu końcowego.
/* * Create form to request access token from Google's OAuth 2.0 server. */ function oauthSignIn() { // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create <form> element to submit parameters to OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': 'YOUR_CLIENT_ID', 'redirect_uri': 'YOUR_REDIRECT_URI', 'response_type': 'token', 'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly', 'include_granted_scopes': 'true', 'state': 'pass-through value'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); }
Krok 2. Google prosi użytkownika o zgodę
W tym kroku użytkownik decyduje, czy przyznać aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody z nazwą aplikacji i usługami interfejsu API Google, do których chce uzyskać dostęp, korzystając z danych uwierzytelniających użytkownika i podsumowania zakresów dostępu. Użytkownik będzie mógł wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu zgłoszonego w aplikacji lub odrzucić prośbę.
Twoja aplikacja nie musi nic robić na tym etapie, ponieważ czeka na odpowiedź serwera OAuth 2.0 Google w związku z przyznaniem dostępu. Odpowiedź objaśniamy 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 wyświetlane użytkownikom zamiast oczekiwanych procesów uwierzytelniania i autoryzacji. Typowe kody błędów i sugerowane sposoby rozwiązania problemu znajdziesz poniżej.
admin_policy_enforced
Na koncie Google nie udało się autoryzować co najmniej 1 zakresu wymaganych przez zasady administratora Google Workspace. Zapoznaj się z artykułem pomocy dla administratorów Google Workspace dotyczącym kontrolowania, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace. Dowiesz się z niego, jak administrator może ograniczyć dostęp do wszystkich zakresów lub poufnych i ograniczonych zakresów, dopóki nie uzyskasz wyraźnego dostępu do swojego identyfikatora klienta OAuth.
disallowed_useragent
Punkt końcowy autoryzacji jest wyświetlany w umieszczonym kliencie użytkownika, który nie jest zgodny z zasadami Google dotyczącymi protokołu OAuth 2.0.
Android
Deweloperzy Androida mogą zobaczyć ten komunikat o błędzie podczas otwierania żądań autoryzacji w android.webkit.WebView
.
Natomiast deweloperzy powinni korzystać z bibliotek Androida, takich jak Logowanie przez Google na Androidzie lub AppAuth for Android, oferowanych przez OpenID Foundation.
Ten błąd może wystąpić, gdy aplikacja na Androida otworzy ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przejdzie do punktu końcowego autoryzacji Google OAuth 2.0 z Twojej witryny. Deweloperzy powinni zezwalać na otwieranie ogólnych linków w domyślnym module obsługi linków w systemie operacyjnym, który obejmuje zarówno moduły Android App Links, jak i domyślną aplikację przeglądarki. Biblioteka niestandardowych kart na Androida również jest obsługiwana.
iOS
Deweloperzy iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView
.
Natomiast deweloperzy powinni korzystać z bibliotek iOS, takich jak Logowanie przez Google na iOS lub AppAuth for iOS w usłudze OpenID Foundation.
Ten błąd może wystąpić, gdy aplikacja na iOS lub macOS otwiera ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przechodzi do punktu końcowego autoryzacji Google OAuth 2.0 w Twojej witrynie. Deweloperzy powinni zezwalać na otwieranie ogólnych linków w domyślnym module obsługi linków w systemie operacyjnym, który obejmuje zarówno moduły uniwersalne linki, 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 konkretnej organizacji Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w sekcji Typ użytkownika w artykule pomocy poświęconym konfigurowaniu OAuth.
invalid_client
Źródło, z którego wysłano żądanie, nie jest autoryzowane dla tego klienta. Zobacz origin_mismatch
.
invalid_grant
Jeśli używasz autoryzacji przyrostowej, token mógł wygasnąć lub został unieważniony. Uwierzytelnij użytkownika ponownie i poproś go o zgodę na uzyskanie nowych tokenów. Jeśli ten błąd będzie się powtarzał, sprawdź, czy aplikacja została prawidłowo skonfigurowana oraz czy w żądaniu znajdują się poprawne tokeny i parametry. W przeciwnym razie konto użytkownika mogło zostać usunięte lub wyłączone.
origin_mismatch
Schemat, domena lub port kodu JavaScriptu, z którego pochodzi żądanie autoryzacji, mogą nie być zgodne z autoryzowanym identyfikatorem URI źródła JavaScript zarejestrowanym dla identyfikatora klienta OAuth. Sprawdź autoryzowane źródła JavaScript w Google API Console Credentials page.
redirect_uri_mismatch
redirect_uri
przekazany w żądaniu autoryzacji nie pasuje do autoryzowanego identyfikatora URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania w: Google API Console Credentials page.
Schemat, domena lub port kodu JavaScriptu, z którego pochodzi żądanie autoryzacji, mogą nie być zgodne z autoryzowanym identyfikatorem URI źródła JavaScript zarejestrowanym dla identyfikatora klienta OAuth. Sprawdź autoryzowane źródła JavaScript w: Google API Console Credentials page.
Parametr redirect_uri
może odnosić się do wycofanego procesu protokołu OAuth, który został wycofany i nie jest już obsługiwany. Aby zaktualizować integrację, zapoznaj się z przewodnikiem po migracji.
Krok 3. Przetwórz odpowiedź serwera OAuth 2.0
Punkty końcowe OAuth 2.0
Serwer OAuth 2.0 wysyła odpowiedź na żądanie redirect_uri
podane w żądaniu tokena dostępu.
Jeśli użytkownik zaakceptuje prośbę, odpowiedź będzie zawierać token dostępu. Jeśli użytkownik nie zaakceptuje żądania, odpowiedź będzie zawierać komunikat o błędzie. Token dostępu lub komunikat o błędzie jest zwracany we fragmencie skrótu identyfikatora URI przekierowania, jak pokazano poniżej:
Odpowiedź tokena dostępu:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
Oprócz parametru
access_token
ciąg znaków fragmentu zawiera też parametrtoken_type
, który zawsze ma wartośćBearer
, oraz parametrexpires_in
, który określa czas życia tokena (w sekundach). Jeśli w żądaniu tokena dostępu określono parametrstate
, jego wartość jest też uwzględniana w odpowiedzi.- Odpowiedź błędu:
https://oauth2.example.com/callback#error=access_denied
Przykładowa odpowiedź serwera OAuth 2.0
Możesz go przetestować, klikając ten przykładowy URL, który prosi o dostęp tylko do odczytu do wyświetlania metadanych plików na Dysku Google:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Po zakończeniu procedury OAuth 2.0 nastąpi przekierowanie na stronę http://localhost/oauth2callback
. Ten URL spowoduje wyświetlenie błędu 404 NOT FOUND
, chyba że komputer lokalny wyświetli plik pod tym adresem. Następny krok zawiera więcej szczegółów dotyczących informacji zwracanych w identyfikatorze URI, gdy użytkownik jest przekierowywany z powrotem do aplikacji.
Wywoływanie interfejsów API Google
Punkty końcowe OAuth 2.0
Gdy aplikacja uzyska token dostępu, możesz go używać do wywoływania interfejsu Google API w imieniu danego konta użytkownika, jeśli zostały przyznane zakresy dostępu wymagane przez ten interfejs. W tym celu umieść token dostępu w żądaniu wysyłanym do interfejsu API, dodają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 zapytań są zwykle widoczne w dziennikach serwera. W większości przypadków wywołania biblioteki interfejsów API Google możesz skonfigurować na przykład za pomocą biblioteki klienta Drive API.
Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w Play 2.0 Playground.
Przykłady HTTP GET
Wywołanie punktu końcowego
drive.files
(interfejsu Drive Files API) korzystającego z nagłówka HTTP Authorization: Bearer
może wyglądać tak: Pamiętaj, że musisz określić własny token dostępu:
GET /drive/v2/files 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/drive/v2/files?access_token=access_token
Przykłady zapytań z operatorem curl
Możesz je 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/drive/v2/files
Możesz też użyć opcji parametru ciągu zapytania:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Przykładowy kod JavaScript
Fragment kodu poniżej pokazuje, jak używać CORS (udostępniania zasobów między domenami) do wysyłania żądań do interfejsu API Google. W tym przykładzie nie wykorzystano biblioteki JavaScript interfejsów API Google. Nawet jeśli nie korzystasz z biblioteki klienta, przewodnik CORS w dokumentacji tej biblioteki pomoże Ci lepiej zrozumieć te żądania.
W tym fragmencie kodu zmienna access_token
reprezentuje token uzyskany w celu wysyłania żądań do interfejsu API w imieniu autoryzowanego użytkownika. Pełny przykład pokazuje, jak zapisać ten token w pamięci lokalnej przeglądarki i pobrać go podczas wysyłania żądania do interfejsu API.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { console.log(xhr.response); }; xhr.send(null);
Pełny przykład
Punkty końcowe OAuth 2.0
Ten przykładowy kod pokazuje, jak zakończyć obsługę protokołu OAuth 2.0 w języku JavaScript bez korzystania z biblioteki klienta interfejsów API Google dla JavaScriptu. Kod dotyczy strony HTML, która zawiera przycisk umożliwiający wypróbowanie żądania do interfejsu API. Jeśli klikniesz ten przycisk, kod sprawdzi, czy strona zapisała token dostępu API w pamięci lokalnej przeglądarki. Jeśli tak, wykonuje żądanie do interfejsu API. W przeciwnym razie inicjuje przepływ OAuth 2.0.
W przypadku protokołu OAuth 2.0 wykonaj te czynności:
- Kieruje użytkownika na serwer OAuth 2.0 Google, który prosi o dostęp do zakresu
https://www.googleapis.com/auth/drive.metadata.readonly
. - Po przyznaniu (lub odrzuceniu) dostępu do co najmniej 1 zakresu, użytkownik jest przekierowywany na stronę oryginalną, na której analizowany jest token dostępu z ciągu identyfikatora fragmentu.
Strona używa tokena dostępu do wykonywania przykładowego żądania do interfejsu API.
Żądanie interfejsu API wywołuje metodę
about.get
interfejsu Drive API, aby uzyskać informacje o koncie Dysku Google autoryzowanego użytkownika.- Jeśli żądanie zostanie wykonane, odpowiedź interfejsu API zostanie zarejestrowana w konsoli debugowania przeglądarki.
Dostęp do aplikacji możesz anulować na stronie Uprawnienia na koncie Google. Aplikacja będzie widoczna jako Prezentacja OAuth 2.0 dla Dokumentów Google API.
Aby uruchomić ten kod lokalnie, musisz ustawić wartości zmiennych YOUR_CLIENT_ID
i YOUR_REDIRECT_URI
, które odpowiadają Twoim danym logowania. Zmienna YOUR_REDIRECT_URI
powinna być ustawiona na ten sam adres URL, pod którym jest wyświetlana strona. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanego w API Console Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI, wystąpi błąd redirect_uri_mismatch
. Twój projekt musi też włączyć odpowiedni interfejs API dla tego żądania.
<html><head></head><body> <script> var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE'; var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE'; var fragmentString = location.hash.substring(1); // Parse query string to see if page request is coming from OAuth 2.0 server. var params = {}; var regex = /([^&=]+)=([^&]*)/g, m; while (m = regex.exec(fragmentString)) { params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]); } if (Object.keys(params).length > 0) { localStorage.setItem('oauth2-test-params', JSON.stringify(params) ); if (params['state'] && params['state'] == 'try_sample_request') { trySampleRequest(); } } // If there's an access token, try an API request. // Otherwise, start OAuth 2.0 flow. function trySampleRequest() { var params = JSON.parse(localStorage.getItem('oauth2-test-params')); if (params && params['access_token']) { var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { if (xhr.readyState === 4 && xhr.status === 200) { console.log(xhr.response); } else if (xhr.readyState === 4 && xhr.status === 401) { // Token invalid, so prompt for user permission. oauth2SignIn(); } }; xhr.send(null); } else { oauth2SignIn(); } } /* * Create form to request access token from Google's OAuth 2.0 server. */ function oauth2SignIn() { // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create element to open OAuth 2.0 endpoint in new window. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': YOUR_CLIENT_ID, 'redirect_uri': YOUR_REDIRECT_URI, 'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly', 'state': 'try_sample_request', 'include_granted_scopes': 'true', 'response_type': 'token'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); } </script> <button onclick="trySampleRequest();">Try sample request</button> </body></html>
Reguły weryfikacji źródła JavaScript
Google stosuje poniższe reguły weryfikacji do źródeł JavaScript, by pomóc deweloperom w zabezpieczaniu aplikacji. Twoje źródła JavaScript muszą być zgodne z tymi regułami. Definicja domeny, hosta i schematu znajdziesz w RFC 3986, sekcja 3 poniżej.
Reguły weryfikacji | |
---|---|
Schemat |
Źródła JavaScript muszą używać schematu HTTPS, a nie zwykłego HTTP. Identyfikatory URI lokalnego hosta (w tym identyfikatory URI adresów IP lokalnych hostów) są zwolnione z tej reguły. |
Osoba prowadząca |
Hosty nie mogą być nieprzetworzonymi adresami IP. Adresy IP lokalnego hosta są zwolnione z tej reguły. |
Domena |
“googleusercontent.com” .goo.gl ), chyba że właścicielem domeny jest aplikacja. |
Informacje o użytkowniku |
Źródła JavaScript nie mogą zawierać podkomponentu userinfo. |
Ścieżka |
Źródła JavaScript nie mogą zawierać komponentu ścieżki. |
Zapytanie |
Źródła JavaScript nie mogą zawierać komponentu zapytania. |
Fragment |
Źródła JavaScript nie mogą zawierać komponentu fragmentu. |
Znaki |
Źródła JavaScript nie mogą zawierać niektórych znaków, w tym:
|
Autoryzacja przyrostowa
W ramach protokołu OAuth 2.0 aplikacja prosi o dostęp do zasobów określonych za pomocą zakresów. Uznaje się, że sprawdzoną metodą jest wysyłanie próśb o zasoby w czasie, gdy są potrzebne. Aby to zrobić, serwer autoryzacji Google obsługuje autoryzację przyrostową. Ta funkcja umożliwia żądanie zakresów, gdy jest to wymagane. Jeśli użytkownik przyzna uprawnienia dla nowego zakresu, zwraca kod autoryzacji, który można wymienić na token zawierający wszystkie zakresy przyznane przez użytkownika dla projektu.
Na przykład aplikacja umożliwiająca użytkownikom próbkowanie utworów muzycznych i tworzenie miksów może wymagać bardzo niewiele zasobów podczas logowania, a może nawet nic więcej niż imię i nazwisko osoby zalogowanej. Zapisanie gotowej składanki będzie jednak wymagało dostępu do Dysku Google. Większość użytkowników uznałaby to za naturalne, gdy prosiła o dostęp do Dysku Google tylko wtedy, gdy była potrzebna.
W takim przypadku w trakcie logowania aplikacja może poprosić o zakresy openid
i profile
, aby przeprowadzić podstawowe logowanie, a potem, podczas pierwszego wysyłania żądania, zapisać zakres kombinacji https://www.googleapis.com/auth/drive.file
.
W przypadku tokena dostępu przyrostowego uzyskanego z uwierzytelniania przyrostowego obowiązują te reguły:
- Tokenu można używać do dostępu do zasobów odpowiadających dowolnym zakresom wdrożonym w nowej, połączonej autoryzacji.
- Gdy używasz tokena odświeżania połączonej autoryzacji do uzyskania tokena dostępu, token dostępu reprezentuje połączoną autoryzację i może być używany w przypadku dowolnej wartości
scope
zawartej w odpowiedzi. - Całkowita autoryzacja obejmuje wszystkie zakresy przyznawane użytkownikowi przez interfejs API, nawet jeśli prośba o grant została wysłana przez różnych klientów. Jeśli np. użytkownik przyznał dostęp do jednego zakresu za pomocą klienta na komputery w aplikacji, a potem innego zakresu do tej samej aplikacji za pomocą klienta mobilnego, połączona autoryzacja będzie uwzględniać oba zakresy.
- Jeśli unieważnisz token reprezentujący połączoną autoryzację, dostęp do wszystkich zakresów tej autoryzacji w imieniu użytkownika zostanie unieważniony.
Przykładowe fragmenty kodu pokazują, jak dodać zakresy do istniejącego tokena dostępu. Dzięki temu Twoja aplikacja nie będzie musiała zarządzać wieloma tokenami dostępu.
Punkty końcowe OAuth 2.0
Aby dodać zakresy do istniejącego tokena dostępu, umieść parametr include_granted_scopes
w żądaniu wysłanym do serwera OAuth 2.0 Google.
Odpowiedni fragment kodu pokazuje, jak to zrobić. Fragment kodu zakłada, że w pamięci lokalnej przeglądarki przechowywane są zakresy, dla których token dostępu jest prawidłowy. (Kod pełnego przykładu przechowuje listę zakresów, w przypadku których token dostępu jest prawidłowy, ustawiając właściwość oauth2-test-params.scope
w pamięci lokalnej przeglądarki).
Fragment kodu porównuje zakresy, w przypadku których token dostępu jest prawidłowy z zakresem obejmującym konkretne zapytanie. Jeśli token dostępu nie obejmuje tego zakresu, rozpocznie się proces OAuth 2.0.
W tym przypadku funkcja oauth2SignIn
jest taka sama jak w kroku 2 (i została udostępniona później w pełnym przykładzie).
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'; var params = JSON.parse(localStorage.getItem('oauth2-test-params')); var current_scope_granted = false; if (params.hasOwnProperty('scope')) { var scopes = params['scope'].split(' '); for (var s = 0; s < scopes.length; s++) { if (SCOPE == scopes[s]) { current_scope_granted = true; } } } if (!current_scope_granted) { oauth2SignIn(); // This function is defined elsewhere in this document. } else { // Since you already have access, you can proceed with the API request. }
Unieważnianie tokena
W niektórych przypadkach użytkownik może chcieć anulować dostęp przyznany aplikacji. Użytkownik może anulować dostęp na stronie Ustawienia konta. Więcej informacji znajdziesz w sekcji dotyczącej usuwania dostępu do witryn lub aplikacji w witrynach i aplikacjach innych firm, które mają dostęp do Twojego konta.
Aplikacja może również automatycznie anulować przyznany dostęp. Cofnięcie automatyzacji ma duże znaczenie w sytuacjach, gdy użytkownik anuluje subskrypcję, usunie aplikację lub zmienią się zasoby interfejsu API wymagane przez aplikację. Oznacza to, że część procesu usuwania może obejmować żądanie interfejsu API, które umożliwia usunięcie uprawnień wcześniej przyznanych aplikacji.
Punkty końcowe OAuth 2.0
Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke
i uwzględnia je 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, zostanie on też unieważniony.
Jeśli odwołanie zostanie przetworzone, kod stanu HTTP odpowiedzi będzie wynosił 200
. W przypadku błędów zwracany jest kod stanu HTTP 400
wraz z kodem błędu.
Poniższy fragment kodu JavaScript umożliwia unieważnienie tokena w kodzie JavaScript bez użycia biblioteki klienta interfejsów API Google. Ponieważ punkt końcowy OAuth 2.0 Google do anulowania tokenów nie obsługuje współdzielenia zasobów z innych domen (CORS), kod tworzy formularz i przesyła go do punktu końcowego, zamiast publikować metodę za pomocą metody XMLHttpRequest()
.
function revokeAccess(accessToken) { // Google's OAuth 2.0 endpoint for revoking access tokens. var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke'; // Create <form> element to use to POST data to the OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'post'); form.setAttribute('action', revokeTokenEndpoint); // Add access token to the form so it is set as value of 'token' parameter. // This corresponds to the sample curl request, where the URL is: // https://oauth2.googleapis.com/revoke?token={token} var tokenField = document.createElement('input'); tokenField.setAttribute('type', 'hidden'); tokenField.setAttribute('name', 'token'); tokenField.setAttribute('value', accessToken); form.appendChild(tokenField); // Add form to page and submit it to actually revoke the token. document.body.appendChild(form); form.submit(); }