Ten dokument wyjaśnia, jak wdrożyć autoryzację OAuth 2.0, aby uzyskać dostęp do interfejsów API Google z aplikacji internetowej JavaScript. OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy jednoczesnym zachowaniu poufności nazw użytkowników, haseł i innych informacji. Na przykład aplikacja może używać protokołu OAuth 2.0, aby uzyskać od użytkowników uprawnienia do przechowywania plików na ich Dyskach Google.
Ten przepływ OAuth 2.0 jest nazywany przepływem niejawnego przyznawania uprawnień. Jest on przeznaczony dla aplikacji, które uzyskują dostęp do interfejsów API tylko wtedy, gdy użytkownik korzysta z aplikacji. Te aplikacje nie mogą przechowywać informacji poufnych.
W tym procesie aplikacja otwiera adres URL Google, który używa parametrów zapytania do identyfikacji aplikacji i typu dostępu do interfejsu API, którego aplikacja wymaga. URL możesz otworzyć w bieżącym oknie przeglądarki lub w oknie. Użytkownik może uwierzytelnić się w Google i przyznać żądane uprawnienia. Następnie Google przekierowuje użytkownika z powrotem do Twojej aplikacji. Przekierowanie zawiera token dostępu, który aplikacja weryfikuje, a następnie używa do wysyłania żądań do interfejsu API.
Biblioteka klienta interfejsów API Google i usługi Google Identity Services
Jeśli używasz biblioteki klienta interfejsów API Google dla języka JavaScript do wykonywania autoryzowanych wywołań do Google, do obsługi procesu autoryzacji musisz używać biblioteki JavaScript Google Identity Services. Zdecydowanie zalecamy korzystanie z modelu kodu Google Identity Services, który opiera się na bezpieczniejszym przepływie kodu autoryzacji z PKCE.
Wymagania wstępne
Włączanie interfejsów API w projekcie
Każda aplikacja, która wywołuje interfejsy API Google, musi je włączyć w Konsoli interfejsów API.
Aby włączyć interfejs API w projekcie:
- Otwórz Bibliotekę interfejsów API w Konsoli interfejsów API Google.
- Jeśli pojawi się taka prośba, wybierz projekt lub utwórz nowy.
- Biblioteka interfejsów API zawiera listę wszystkich dostępnych interfejsów API pogrupowanych według rodziny usług i popularności. Jeśli interfejs API, który chcesz włączyć, nie jest widoczny 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.
- Jeśli pojawi się taka prośba, włącz płatności.
- Jeśli pojawi się taka prośba, przeczytaj i zaakceptuj Warunki korzystania z interfejsu API.
Tworzenie danych uwierzytelniających
Każda aplikacja, która używa protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google, musi mieć dane uwierzytelniające, które identyfikują ją na serwerze OAuth 2.0 Google. Poniżej znajdziesz instrukcje tworzenia danych logowania do projektu. Twoje aplikacje mogą następnie używać tych danych logowania, aby uzyskiwać dostęp do interfejsów API, które zostały włączone w tym projekcie.
- Otwórz stronę Klienci.
- Kliknij Utwórz klienta.
- Wybierz typ aplikacji Aplikacja internetowa.
- Wypełnij formularz. Aplikacje, które używają JavaScriptu do wysyłania autoryzowanych żądań do interfejsów API Google, muszą określać autoryzowane źródła JavaScriptu. Źródła identyfikują 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.
Identyfikowanie zakresów dostępu
Zakresy umożliwiają aplikacji żądanie dostępu tylko do tych zasobów, których potrzebuje, a użytkownikom – kontrolowanie zakresu dostępu, który przyznają aplikacji. W związku z tym 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, zalecamy określenie zakresów, do których aplikacja będzie potrzebować uprawnień dostępu.
Dokument Zakresy interfejsu OAuth 2.0 API 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 opisujemy, jak aplikacja współdziała z serwerem OAuth 2.0 Google, aby uzyskać zgodę użytkownika na wysłanie żądania do interfejsu API w jego imieniu. Twoja aplikacja musi uzyskać tę zgodę, zanim będzie mogła wykonać żądanie do interfejsu API Google, które wymaga autoryzacji użytkownika.
Krok 1. Przekierowanie na serwer OAuth 2.0 Google
Aby poprosić o uprawnienia dostępu do danych użytkownika, przekieruj go na serwer OAuth 2.0 Google.
Punkty końcowe OAuth 2.0
Wygeneruj adres URL, aby poprosić o dostęp z punktu końcowego OAuth 2.0 Google pod adresem https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy jest dostępny przez HTTPS. Połączenia przez zwykły protokół HTTP są odrzucane.
Serwer autoryzacji Google obsługuje te parametry ciągu zapytania w przypadku aplikacji serwera WWW:
| Parametry | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Wymagany
Identyfikator klienta aplikacji. Tę wartość znajdziesz na stronie Klienci w konsoli Cloud. |
||||||
redirect_uri |
Wymagany
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, które zostały skonfigurowane na stronie Klienci w konsoli Cloud klienta. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI przekierowania dla podanego Pamiętaj, że schemat |
||||||
response_type |
Wymagany
Aplikacje w JavaScripcie muszą ustawić wartość parametru na |
||||||
scope |
Wymagany
Rozdzielona spacjami lista zakresów, które identyfikują zasoby, do których aplikacja może uzyskać dostęp w imieniu użytkownika. Te wartości są przekazywane do ekranu zgody, który Google wyświetla użytkownikowi. Zakresy umożliwiają aplikacji żądanie dostępu tylko do tych zasobów, których potrzebuje, a użytkownikom – kontrolowanie zakresu dostępu, który przyznają aplikacji. Istnieje więc odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika. Zalecamy, aby aplikacja prosiła o dostęp do zakresów autoryzacji w kontekście, gdy tylko jest to możliwe. Jeśli poprosisz o dostęp do danych użytkownika w odpowiednim kontekście, korzystając z autoryzacji stopniowej, użytkownicy będą rozumieć, do czego aplikacja potrzebuje konkretnych danych. |
||||||
state |
Zalecane
Określa dowolną wartość ciągu, której aplikacja używa do utrzymania 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 liczb jednorazowych i ograniczania ryzyka sfałszowania żądania z innej witryny. Ponieważ wartość |
||||||
include_granted_scopes |
Opcjonalny
Umożliwia aplikacjom korzystanie z autoryzacji przyrostowej w celu żądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na |
||||||
enable_granular_consent |
Opcjonalny
Domyślna wartość to Gdy Google włączy uprawnienia szczegółowe dla aplikacji, ten parametr nie będzie już działać. |
||||||
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 wskazówki, aby uprościć proces logowania, wstępnie wypełniając pole z adresem e-mail w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania. Ustaw wartość parametru na adres e-mail lub identyfikator |
||||||
prompt |
Opcjonalny
Rozdzielana spacjami lista promptów, które mają być wyświetlane użytkownikowi, z uwzględnieniem wielkości liter. Jeśli nie określisz tego parametru, użytkownik zostanie poproszony o wyrażenie zgody tylko wtedy, gdy Twój projekt po raz pierwszy poprosi o dostęp. Więcej informacji znajdziesz w sekcji Prośba o ponowne wyrażenie zgody. Możliwe wartości to:
|
||||||
Przykładowe przekierowanie na serwer autoryzacji Google
Poniżej znajduje się przykładowy adres URL z podziałami wierszy i spacjami, które ułatwiają czytanie.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//developers.google.com/oauthplayground& client_id=client_id
Po utworzeniu adresu URL żądania przekieruj na niego użytkownika.
Przykładowy kod JavaScript
Poniższy fragment kodu JavaScript pokazuje, jak zainicjować proces autoryzacji w języku JavaScript bez użycia biblioteki klienta interfejsów API Google dla języka JavaScript. Ten punkt końcowy OAuth 2.0 nie obsługuje współdzielenia zasobów pomiędzy serwerami z różnych domen (CORS), dlatego fragment kodu tworzy formularz, który otwiera żądanie 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 https://www.googleapis.com/auth/calendar.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, które zawiera nazwę aplikacji i interfejsy API Google, do których aplikacja prosi o dostęp, oraz dane uwierzytelniające użytkownika i podsumowanie zakresów dostępu, które zostaną przyznane. Użytkownik może wtedy wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu, o który prosi aplikacja, 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 dostęp został przyznany. Odpowiedź została wyjaśniona w następnym kroku.
Błędy
Żądania wysyłane do punktu końcowego autoryzacji OAuth 2.0 Google mogą wyświetlać komunikaty o błędach 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 żądanego zakresu ze względu na zasady administratora Google Workspace. Więcej informacji o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów poufnych i ograniczonych, dopóki nie zostanie on wyraźnie przyznany Twojemu 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 ramach wbudowanego klienta użytkownika, który jest niedozwolony przez zasady Google dotyczące protokołu OAuth 2.0.
Deweloperzy aplikacji na iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView.
Deweloperzy powinni zamiast tego używać bibliotek iOS, takich jak Logowanie przez Google na iOS lub AppAuth na iOS od OpenID Foundation.
Twórcy stron internetowych mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otwiera ogólny link internetowy we wbudowanym kliencie użytkownika, a użytkownik przechodzi z Twojej witryny do punktu końcowego autoryzacji OAuth 2.0 Google. Deweloperzy powinni zezwalać na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który obejmuje zarówno moduły obsługi uniwersalnych linków, jak i 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 pomocy dotyczącym konfigurowania ekranu zgody OAuth.
invalid_client
Źródło, z którego wysłano żądanie, nie jest autoryzowane dla tego klienta. Zobacz origin_mismatch.
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 autoryzacji przyrostowej, token mógł wygasnąć lub zostać unieważniony. Ponownie uwierzytelnij użytkownika i poproś go o zgodę użytkownika 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.
origin_mismatch
Schemat, domena lub port kodu JavaScript, który wysyła żądanie autoryzacji, mogą nie pasować do autoryzowanego identyfikatora URI źródła JavaScript zarejestrowanego dla identyfikatora klienta OAuth. Sprawdź autoryzowane źródła JavaScript na stronie Klienty w konsoli Google Cloud.
redirect_uri_mismatch
Wartość redirect_uri przekazana w żądaniu autoryzacji nie jest zgodna z autoryzowanym identyfikatorem URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania na stronie Klienty w konsoli Google Cloud.
Schemat, domena lub port kodu JavaScript, który wysyła żądanie autoryzacji, mogą nie pasować do autoryzowanego identyfikatora URI źródła JavaScript zarejestrowanego dla identyfikatora klienta OAuth. Sprawdź autoryzowane źródła JavaScript na stronie Klienci w konsoli Google Cloud.
Parametr redirect_uri może odnosić się do przepływu OAuth poza pasmem (OOB), który został wycofany i nie jest już obsługiwany. Aby zaktualizować integrację, zapoznaj się z przewodnikiem po migracji.
invalid_request
Wystąpił błąd w Twoim żądaniu. Może to wynikać z kilku powodów:
- Żądanie nie zostało prawidłowo sformatowane.
- W żądaniu brakowało wymaganych parametrów.
- Żądanie używa metody autoryzacji, której Google nie obsługuje. Sprawdź, czy integracja OAuth korzysta z zalecanej metody integracji
Krok 3. Przetwórz odpowiedź serwera OAuth 2.0
Punkty końcowe OAuth 2.0
Serwer OAuth 2.0 wysyła odpowiedź do redirect_uri określonego w żądaniu tokena dostępu.
Jeśli użytkownik zatwierdzi prośbę, odpowiedź będzie zawierać token dostępu. Jeśli użytkownik nie zatwierdzi prośby, odpowiedź będzie zawierać komunikat o błędzie. Token dostępu lub komunikat o błędzie jest zwracany we fragmencie hasha identyfikatora URI przekierowania, jak pokazano w tych przykładach:
Odpowiedź tokena dostępu:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
Oprócz parametru
access_tokenciąg znaków fragmentu zawiera też parametrtoken_type, który jest zawsze ustawiony naBearer, oraz parametrexpires_in, który określa czas ważności tokena w sekundach. Jeśli w żądaniu tokena dostępu określono parametrstate, jego wartość również jest uwzględniana w odpowiedzi.- Odpowiedź błędu:
https://oauth2.example.com/callback#error=access_denied
Przykładowa odpowiedź serwera OAuth 2.0
Możesz przetestować ten proces, klikając ten przykładowy adres URL, który żąda dostępu tylko do odczytu do metadanych plików na Dysku Google i do wydarzeń w Kalendarzu Google:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//developers.google.com/oauthplayground& client_id=client_id
Po zakończeniu przepływu OAuth 2.0 przeglądarka przekieruje Cię do OAuth 2.0 Playground, narzędzia do testowania przepływów OAuth. Zobaczysz, że OAuth 2.0 Playground automatycznie przechwycił kod autoryzacji.
Krok 4. Sprawdź, które zakresy przyznali użytkownicy
Jeśli poprosisz o kilka uprawnień (zakresów), użytkownicy mogą nie przyznać aplikacji dostępu do wszystkich z nich. Aplikacja musi sprawdzić, które zakresy zostały faktycznie przyznane, i odpowiednio obsłużyć sytuacje, w których niektóre uprawnienia zostały odrzucone, zwykle przez wyłączenie funkcji, które korzystają z tych odrzuconych zakresów.
Są jednak wyjątki. Aplikacje Google Workspace Enterprise z przekazywaniem uprawnień dostępu w całej domenie lub aplikacje oznaczone jako zaufane pomijają ekran zgody na uprawnienia szczegółowe. W przypadku tych aplikacji użytkownicy nie zobaczą ekranu zgody na szczegółowe uprawnienia. Zamiast tego aplikacja otrzyma wszystkie żądane zakresy lub żadne.
Więcej informacji znajdziesz w artykule Jak postępować z uprawnieniami szczegółowymi.
Punkty końcowe OAuth 2.0
Aby sprawdzić, czy użytkownik przyznał aplikacji dostęp do określonego zakresu, sprawdź pole scope w odpowiedzi tokena dostępu. Zakresy dostępu przyznane przez parametr access_token, wyrażone jako lista ciągów znaków rozdzielonych spacjami, z uwzględnieniem wielkości liter.
Na przykład ta przykładowa odpowiedź z tokenem dostępu wskazuje, że użytkownik przyznał aplikacji uprawnienia 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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
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 API Google 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 do interfejsu API, podając parametr zapytania access_token lub wartość Bearer nagłówka HTTP Authorization. Jeśli to możliwe, lepiej używać nagłówka 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 (na przykład podczas wywoływania interfejsu Drive Files API).
Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w OAuth 2.0 Playground.
Przykłady HTTP GET
Wywołanie punktu końcowego
drive.files (interfejs Drive Files API) za pomocą nagłówka HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz podać 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 z użyciem parametru ciągu zapytania access_token:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl przykładu
Możesz przetestować te polecenia za pomocą aplikacji wiersza poleceń curl. Oto przykład użycia opcji nagłówka HTTP (preferowanej):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Możesz też użyć parametru ciągu zapytania:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Przykładowy kod JavaScript
Poniższy fragment kodu pokazuje, jak używać CORS (współdzielenie zasobów między domenami) do wysyłania żądania do interfejsu API Google. W tym przykładzie nie używamy biblioteki klienta interfejsów API Google dla języka JavaScript. Nawet jeśli nie korzystasz z biblioteki klienta, przewodnik Obsługa CORS w dokumentacji tej biblioteki prawdopodobnie 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. Kompletny przykład pokazuje, jak przechowywać ten token w pamięci lokalnej przeglądarki i pobierać 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);
Kompletny przykład
Punkty końcowe OAuth 2.0
Ten przykładowy kod pokazuje, jak przeprowadzić przepływ OAuth 2.0 w języku JavaScript bez użycia biblioteki klienta interfejsów API Google dla języka JavaScript. Kod dotyczy strony HTML, na której wyświetla się przycisk umożliwiający wypróbowanie żądania do interfejsu API. Jeśli klikniesz przycisk, kod sprawdzi, czy strona zapisała token dostępu do interfejsu 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 przepływu OAuth 2.0 strona wykonuje te czynności:
- Przekierowuje użytkownika na serwer OAuth 2.0 Google, który prosi o dostęp do zakresów
https://www.googleapis.com/auth/drive.metadata.readonlyihttps://www.googleapis.com/auth/calendar.readonly. - Po przyznaniu (lub odmowie) dostępu do co najmniej 1 żądanego zakresu użytkownik jest przekierowywany na pierwotną stronę, która analizuje token dostępu z ciągu identyfikatora fragmentu.
- Strona sprawdza, do których zakresów użytkownik przyznał dostęp aplikacji.
Jeśli użytkownik przyznał dostęp do żądanych zakresów, strona używa tokena dostępu do wysłania przykładowego żądania do interfejsu API.
Żądanie do interfejsu API wywołuje metodę
about.getinterfejsu Drive API, aby pobrać informacje o koncie Dysku Google autoryzowanego użytkownika.- Jeśli żądanie zostanie wykonane pomyślnie, odpowiedź interfejsu API zostanie zarejestrowana w konsoli debugowania przeglądarki.
Dostęp do aplikacji możesz cofnąć na stronie Uprawnienia na koncie Google. Aplikacja jest wymieniona jako nazwa aplikacji podana na stronie marki na ekranie zgody OAuth podczas tworzenia identyfikatora klienta.
Aby uruchomić ten kod lokalnie, musisz ustawić wartości zmiennych YOUR_CLIENT_ID i YOUR_REDIRECT_URI, które odpowiadają Twoim danym uwierzytelniającym. Zmienna YOUR_REDIRECT_URI powinna być ustawiona na ten sam adres URL, pod którym wyświetlana jest strona. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0, które zostały skonfigurowane na stronie Klienty w konsoli Cloud. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI, pojawi się błąd redirect_uri_mismatch. W projekcie musi być też włączony 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';
// Parse query string to see if page request is coming from OAuth 2.0 server.
var fragmentString = location.hash.substring(1);
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0 && params['state']) {
if (params['state'] == localStorage.getItem('state')) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
trySampleRequest();
} else {
console.log('State mismatch. Possible CSRF attack');
}
}
// Function to generate a random state value
function generateCryptoRandomState() {
const randomValues = new Uint32Array(2);
window.crypto.getRandomValues(randomValues);
// Encode as UTF-8
const utf8Encoder = new TextEncoder();
const utf8Array = utf8Encoder.encode(
String.fromCharCode.apply(null, randomValues)
);
// Base64 encode the UTF-8 data
return btoa(String.fromCharCode.apply(null, utf8Array))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// 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']) {
// User authorized the request. Now, check which scopes were granted.
if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
// User authorized read-only Drive activity permission.
// Calling the APIs, etc.
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 {
// User didn't authorize read-only Drive activity permission.
// Update UX and application accordingly
console.log('User did not authorize read-only Drive activity permission.');
}
// Check if user authorized Calendar read permission.
if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
// User authorized Calendar read permission.
// Calling the APIs, etc.
console.log('User authorized Calendar read permission.');
}
else {
// User didn't authorize Calendar read permission.
// Update UX and application accordingly
console.log('User did not authorize Calendar read permission.');
}
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// create random state value and store in local storage
var state = generateCryptoRandomState();
localStorage.setItem('state', state);
// 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 https://www.googleapis.com/auth/calendar.readonly',
'state': state,
'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 te reguły sprawdzania poprawności do źródeł JavaScriptu, aby pomóc deweloperom w zapewnieniu bezpieczeństwa aplikacji. Źródła JavaScriptu muszą być zgodne z tymi regułami. Definicje domeny, hosta i schematu używane w tych regułach znajdziesz w sekcji 3 dokumentu RFC 3986.
| Reguły weryfikacji | |
|---|---|
| Schemat |
Źródła JavaScriptu muszą używać schematu HTTPS, a nie zwykłego HTTP. Identyfikatory URI hosta lokalnego (w tym identyfikatory URI adresów IP hosta lokalnego) są wyłączone z tej reguły. |
| Osoba prowadząca |
Hosty nie mogą być nieprzetworzonymi adresami IP. Adresy IP hosta lokalnego są wyłączone z tej reguły. |
| Domena |
“googleusercontent.com”.goo.gl), chyba że aplikacja jest właścicielem domeny. |
| Userinfo |
Źródła JavaScriptu nie mogą zawierać komponentu podrzędnego userinfo. |
| Ścieżka |
Źródła JavaScriptu nie mogą zawierać komponentu ścieżki. |
| Zapytanie |
Źródła JavaScriptu nie mogą zawierać komponentu zapytania. |
| Fragment |
Źródła JavaScriptu nie mogą zawierać komponentu fragmentu. |
| Znaki |
Punkty początkowe JavaScript nie mogą zawierać niektórych znaków, takich jak:
|
Autoryzacja przyrostowa
W protokole OAuth 2.0 aplikacja prosi o autoryzację dostępu do zasobów, które są identyfikowane przez zakresy. Zgodnie ze sprawdzonymi metodami dotyczącymi wygody użytkowników najlepiej jest prosić o autoryzację zasobów w momencie, gdy są one potrzebne. Aby umożliwić takie działanie, serwer autoryzacji Google obsługuje autoryzację przyrostową. Ta funkcja umożliwia wysyłanie żądań o zakresy, gdy są one potrzebne. Jeśli użytkownik przyzna uprawnienia do nowego zakresu, zwraca kod autoryzacji, który można wymienić na token zawierający wszystkie zakresy, które użytkownik przyznał projektowi.
Na przykład aplikacja, która umożliwia użytkownikom odsłuchiwanie próbek utworów muzycznych i tworzenie miksów, może wymagać bardzo niewielu zasobów podczas logowania, być może tylko imienia i nazwiska osoby logującej się. Jednak zapisanie gotowego miksu wymagałoby dostępu do Dysku Google. Większość osób uznałaby za naturalne, gdyby prośba o dostęp do Dysku Google pojawiała się tylko wtedy, gdy aplikacja faktycznie go potrzebuje.
W takim przypadku podczas logowania aplikacja może poprosić o zakresy openid i profile, aby przeprowadzić podstawowe logowanie, a później, przy pierwszym żądaniu zapisania miksu, o zakres https://www.googleapis.com/auth/drive.file.
W przypadku tokena dostępu uzyskanego w ramach autoryzacji przyrostowej obowiązują te reguły:
- Tokena można używać do uzyskiwania dostępu do zasobów odpowiadających dowolnemu zakresowi uwzględnionemu w nowej, połączonej autoryzacji.
- Gdy używasz tokena odświeżania do uzyskania tokena dostępu, token dostępu reprezentuje połączone uprawnienia i może być używany w przypadku dowolnej wartości
scopezawartej w odpowiedzi. - Połączona autoryzacja obejmuje wszystkie zakresy, które użytkownik przyznał projektowi interfejsu API, nawet jeśli uprawnienia zostały zażądane przez różnych klientów. Jeśli na przykład użytkownik przyznał dostęp do jednego zakresu za pomocą klienta aplikacji na komputery, a następnie przyznał dostęp do innego zakresu tej samej aplikacji za pomocą klienta mobilnego, połączona autoryzacja będzie obejmować oba zakresy.
- Jeśli unieważnisz token reprezentujący autoryzację łączoną, dostęp do wszystkich zakresów tej autoryzacji w imieniu powiązanego użytkownika zostanie unieważniony jednocześnie.
Przykładowe kody poniżej pokazują, jak dodać zakresy do istniejącego tokena dostępu. Dzięki temu aplikacja nie musi zarządzać wieloma tokenami dostępu.
Punkty końcowe OAuth 2.0
Aby dodać zakresy do istniejącego tokena dostępu, uwzględnij parametr include_granted_scopes w żądaniu wysyłanym do serwera OAuth 2.0 Google.
Poniższy fragment kodu pokazuje, jak to zrobić. We fragmencie kodu założono, że zakresy, dla których token dostępu jest ważny, są przechowywane w pamięci lokalnej przeglądarki. (Kod kompletnego przykładu przechowuje listę zakresów, dla których token dostępu jest ważny, przez ustawienie właściwości oauth2-test-params.scope w pamięci lokalnej przeglądarki).
Fragment kodu porównuje zakresy, dla których token dostępu jest ważny, z zakresem, którego chcesz użyć w przypadku konkretnego zapytania. Jeśli token dostępu nie obejmuje tego zakresu, rozpoczyna się przepływ OAuth 2.0.
Funkcja oauth2SignIn jest taka sama jak ta, która została podana w kroku 2 (i która jest podana później w kompletnym 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żnienie tokena
W niektórych przypadkach użytkownik może chcieć anulować dostęp przyznany aplikacji. Użytkownik może anulować dostęp w ustawieniach konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu witryny lub aplikacji w dokumencie pomocy „Aplikacje i witryny innych firm mające dostęp do Twojego konta”.
Aplikacja może też programowo unieważnić przyznany jej dostęp. Programowe unieważnianie jest ważne w przypadkach, gdy użytkownik anuluje subskrypcję, usunie aplikację lub zasoby interfejsu API wymagane przez aplikację ulegną znacznej zmianie. Innymi słowy, część procesu usuwania może obejmować żądanie do interfejsu API, aby upewnić się, że uprawnienia wcześniej przyznane aplikacji zostały usunięte.
Punkty końcowe OAuth 2.0
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}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 również zostanie unieważniony.
Jeśli unieważnienie zostanie przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędów zwracany jest kod stanu HTTP 400 wraz z kodem błędu.
Poniższy fragment kodu JavaScript pokazuje, jak unieważnić token w języku JavaScript bez użycia biblioteki klienta interfejsów API Google dla języka JavaScript. Punkt końcowy OAuth 2.0 Google do unieważniania tokenów nie obsługuje współdzielenia zasobów między serwerami z różnych domen (CORS), dlatego kod tworzy formularz i przesyła go do punktu końcowego, zamiast używać metody XMLHttpRequest() do wysyłania żądania.
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(); }
Wdrażanie ochrony wszystkich kont
Dodatkowym krokiem, który należy podjąć, aby chronić konta użytkowników, jest wdrożenie ochrony wszystkich kont za pomocą usługi ochrony wszystkich kont 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. Możesz następnie wykorzystać te informacje, aby podjąć działania w zależności od tego, jak chcesz zareagować na zdarzenia.
Oto kilka przykładów typów zdarzeń wysyłanych do Twojej aplikacji przez usługę ochrony wszystkich 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 tym, jak wdrożyć ochronę wszystkich kont, oraz pełną listę dostępnych zdarzeń znajdziesz na stronie Chroń konta użytkowników za pomocą ochrony wszystkich kont .