OAuth 2.0 na potrzeby aplikacji internetowych po stronie klienta

W tym dokumencie opisujemy, jak wdrożyć autoryzację OAuth 2.0, by 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ć protokołu OAuth 2.0, aby uzyskiwać od użytkowników uprawnienia do przechowywania plików na ich Dyskach Google.

Ten przepływ OAuth 2.0 jest nazywany przepływem niejawnym. Jest przeznaczona dla aplikacji, które uzyskują dostęp do interfejsów API tylko wtedy, gdy użytkownik jest obecny w aplikacji. Aplikacje te nie mogą przechowywać poufnych informacji.

W tym procesie aplikacja otwiera adres URL Google, który używa parametrów zapytania do identyfikacji aplikacji oraz typu dostępu do interfejsu API, którego wymaga aplikacja. Możesz otworzyć adres URL w bieżącym oknie przeglądarki lub w wyskakującym okienku. Użytkownik może uwierzytelnić się w Google i przyznać wymagane uprawnienia. Następnie Google przekierowuje użytkownika z powrotem do aplikacji. Przekierowanie zawiera token dostępu, który jest weryfikowany przez aplikację, a następnie wykorzystywany do wysył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ń do Google używasz biblioteki klienta interfejsów API Google dla JavaScript, do obsługi procesu OAuth 2.0 użyj biblioteki JavaScript usług Google Identity Services. Zobacz model tokena usług tożsamości Google oparty na przepływie niejawnego uwierzytelniania OAuth 2.0.

Wymagania wstępne

Włącz interfejsy API w projekcie

Każda aplikacja wywołująca interfejsy API Google musi włączyć te interfejsy w zadaniu API Console.

Aby włączyć interfejs API w projekcie:

  1. Open the API Library w: Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Lista API Library zawiera listę wszystkich dostępnych interfejsów API uporządkowanych według rodziny usług i popularności. Jeśli interfejsu API, który chcesz włączyć, nie ma na liście, wyszukaj go za pomocą wyszukiwarki lub kliknij Wyświetl wszystkie w rodzinie usług, do której należy.
  4. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Tworzenie danych uwierzytelniających

Każda aplikacja korzystająca z protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google musi mieć dane uwierzytelniające, które identyfikują aplikację na serwerze Google OAuth 2.0. Poniższe kroki wyjaśniają, jak utworzyć dane logowania do projektu. Aplikacje mogą następnie używać tych danych logowania, aby uzyskiwać dostęp do interfejsów API włączonych w tym projekcie.

  1. Go to the Credentials page.
  2. Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
  3. Wybierz typ aplikacji Aplikacja internetowa.
  4. Wypełnij formularz. Aplikacje, które używają JavaScriptu do wysyłania autoryzowanych żądań do interfejsu Google API, muszą określać autoryzowane źródła JavaScript. Ź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.

Zidentyfikuj zakresy dostępu

Zakresy umożliwiają aplikacji dostęp tylko do potrzebnych zasobów, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu, który przyznają Twojej aplikacji. Dlatego może występować odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Przed wdrożeniem autoryzacji OAuth 2.0 zalecamy wskazanie zakresów, do których aplikacja będzie potrzebować uprawnień.

Dokument Zakresy interfejsów API OAuth 2.0 zawiera pełną listę zakresów, które mogą być używane w celu uzyskania dostępu do interfejsów API Google.

Uzyskiwanie tokenów dostępu OAuth 2.0

Poniższe kroki pokazują, jak Twoja aplikacja współpracuje z serwerem OAuth 2.0 Google, aby uzyskać zgodę użytkownika na wykonanie żądania do interfejsu API w jego imieniu. Twoja aplikacja musi mieć taką zgodę, zanim będzie mogła wykonywać żądania do interfejsu Google API wymagające 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 Google OAuth 2.0.

Punkty końcowe OAuth 2.0

Wygeneruj 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. Odrzucane są zwykłe połączenia HTTP.

Serwer autoryzacji Google obsługuje te parametry ciągu zapytania dla aplikacji serwera WWW:

Parametry
client_id Wymagany

Identyfikator klienta aplikacji. Tę wartość znajdziesz w API Console Credentials page.
redirect_uri Wymagany

Określa, dokąd serwer interfejsu API przekierowuje użytkownika po zakończeniu procesu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0, które zostały skonfigurowane w API Console Credentials pageTwojego klienta. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI przekierowania dla podanego identyfikatora client_id, pojawi się błąd redirect_uri_mismatch.

Pamiętaj, że schemat http lub https, wielkość liter i ukośnik na końcu („/”) muszą być zgodne.
response_type Wymagany

Aplikacje JavaScript muszą ustawić wartość parametru na token. Ta wartość instruuje serwer autoryzacji Google, że zwraca token dostępu w postaci pary name=value w identyfikatorze fragmentu identyfikatora URI (#), do którego użytkownik jest przekierowywany po ukończeniu procesu autoryzacji.
scope Wymagany

Lista rozdzielonych spacjami zakresów określających zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Wartości te mają wpływ na ekran zgody wyświetlany przez Google użytkownikowi.

Zakresy umożliwiają aplikacji dostęp tylko do potrzebnych zasobów, a jednocześnie pozwalają użytkownikom kontrolować zakres dostępu, który przyznają Twojej aplikacji. Dlatego istnieje 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 jest to możliwe. Wysyłając prośbę o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz użytkownikom zrozumienie, dlaczego aplikacja potrzebuje dostępu, o który prosi.
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ę name=value w identyfikatorze fragmentu adresu URL (#) parametru redirect_uri, gdy użytkownik wyrazi zgodę na dostęp aplikacji lub go odrzuci.

Parametru tego można używać do różnych celów, np. do kierowania użytkownika do odpowiedniego zasobu w aplikacji, wysyłania liczb jednorazowych i łagodzenia skutków fałszowania żądań pochodzących z innych witryn. Ponieważ redirect_uri można odgadnąć, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli generujesz losowy ciąg znaków lub zakodujesz skrót pliku cookie bądź inną wartość, która przechwytuje stan klienta, możesz zweryfikować odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zabezpiecza to przed atakami, takimi jak fałszowanie żądań z innych witryn. Przykład sposobu tworzenia i potwierdzania tokena state znajdziesz w dokumentacji OpenID Connect.
include_granted_scopes Opcjonalny

Umożliwia aplikacjom korzystanie z przyrostowej autoryzacji w celu zażądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na true i żądanie autoryzacji zostanie przyznane, nowy token dostępu będzie też obejmować wszystkie zakresy, do których użytkownik przyznał dostęp aplikacji. Przykłady znajdziesz w sekcji o przyrostowej autoryzacji.
login_hint Opcjonalny

Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby wyświetlić wskazówkę dla serwera uwierzytelniania Google. Serwer korzysta z podpowiedzi, aby uprościć proces logowania, wstępnie 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 sub, który odpowiada identyfikatorowi Google użytkownika.
prompt Opcjonalny

Lista rozdzielanych spacjami promptów dla użytkownika (z uwzględnieniem wielkości liter). Jeśli nie określisz tego parametru, użytkownik będzie pytany tylko wtedy, gdy Twój projekt po raz pierwszy poprosi o dostęp. Więcej informacji znajdziesz w sekcji Proszenie o ponowne wyrażenie zgody.

Możliwe wartości to:

none Nie wyświetlaj żadnych ekranów uwierzytelniania ani zgody. Nie można podawać innych wartości.
consent Wyświetlaj użytkownikowi prośbę o zgodę na wykorzystanie danych.
select_account Proś użytkownika o wybranie konta.

Przykładowe przekierowanie na serwer autoryzacji Google

Poniżej znajduje się przykładowy adres URL ze znakami podziału wiersza i spacjami, aby zwiększyć czytelność.

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 na niego użytkownika.

Przykładowy kod JavaScript

Poniższy fragment kodu JavaScript pokazuje, jak rozpocząć proces autoryzacji w JavaScripcie bez używania biblioteki klienta interfejsów API Google do obsługi JavaScriptu. Ponieważ ten punkt końcowy OAuth 2.0 nie obsługuje udostępniania zasobów między serwerami (CORS), fragment kodu tworzy formularz otwierający żą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',
                '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ę na wykorzystanie danych

W tym kroku użytkownik decyduje, czy przyznać aplikacji wymagany dostęp. Na tym etapie Google wyświetla okno zgody z nazwą Twojej aplikacji i usług interfejsu Google API, do których prosi o dostęp za pomocą danych uwierzytelniających użytkownika, a także podsumowanie zakresów do przyznania dostępu. Użytkownik może następnie wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu żądanego przez Twoją aplikację lub odrzucić żądanie.

Na tym etapie Twoja aplikacja nie musi nic robić, ponieważ czeka na odpowiedź serwera OAuth 2.0 Google z informacją, czy został przyznany dostęp. Odpowiedź wyjaśnimy 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żytkowników zamiast oczekiwanych przepływów uwierzytelniania i autoryzacji. Poniżej znajdziesz typowe kody błędów i sugerowane sposoby ich rozwiązania.

admin_policy_enforced

Na koncie Google nie można autoryzować co najmniej jednego żądanego zakresu ze względu na zasady administratora Google Workspace. Przeczytaj artykuł pomocy dla administratorów Google Workspace Określanie, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace, aby dowiedzieć się więcej o tym, jak administrator może ograniczać dostęp do wszystkich zakresów lub zakresów wrażliwych i zakresów z ograniczeniami do czasu wyraźnego przyznania dostępu Twojemu identyfikatorowi klienta OAuth.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany wewnątrz osadzonego klienta użytkownika, który jest niedozwolony przez zasady Google OAuth 2.0.

Android

Deweloperzy aplikacji na Androida mogą napotkać ten komunikat o błędzie podczas otwierania żądań autoryzacji w zadaniu android.webkit.WebView. Deweloperzy powinni używać bibliotek Androida takich jak Google Sign-In for Android czy AppAuth for Android fundacji OpenID.

Programiści stron internetowych mogą napotkać ten błąd, gdy aplikacja na Androida otwiera ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przechodzi z Twojej witryny do punktu końcowego autoryzacji OAuth 2.0 Google. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który obejmuje moduły obsługi linków do aplikacji na Androida lub domyślną aplikację przeglądarki. Obsługiwana jest też biblioteka kart niestandardowych na Androida.

iOS

Deweloperzy korzystający z systemów iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView. Deweloperzy powinni używać bibliotek iOS takich jak Google Sign-In for iOS czy AppAuth for iOS od OpenID Foundation.

Programiści stron internetowych mogą napotkać ten błąd, gdy aplikacja na iOS lub macOS otworzy ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przejdzie z Twojej witryny do punktu końcowego autoryzacji OAuth 2.0 Google. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który obejmuje moduły obsługi linków uniwersalnych lub domyślną aplikację przeglądarki. Obsługiwaną opcją jest też biblioteka SFSafariViewController.
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 konfiguracji znajdziesz w sekcji Typ użytkownika artykułu pomocy „Konfigurowanie ekranu zgody OAuth”.

invalid_client

Źródło, z którego przesłano żądanie, nie jest autoryzowane dla tego klienta. Zobacz origin_mismatch.

invalid_grant

Podczas korzystania z autoryzacji przyrostowej token mógł wygasnąć lub został unieważniony. Uwierzytelnij użytkownika ponownie i poproś o zgodę użytkownika na uzyskanie nowych tokenów. Jeśli ten błąd nadal się pojawia, sprawdź, czy aplikacja została skonfigurowana prawidłowo 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, z którego pochodzi żądanie autoryzacji, mogą nie być zgodne z autoryzowanym identyfikatorem URI źródła JavaScriptu zarejestrowanym dla identyfikatora klienta OAuth. Sprawdź autoryzowane źródła JavaScriptu w: Google API Console Credentials page.

redirect_uri_mismatch

Wartość redirect_uri przekazana 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 JavaScript, z którego pochodzi żądanie autoryzacji, mogą nie być zgodne z autoryzowanym identyfikatorem URI źródła JavaScriptu zarejestrowanym dla identyfikatora klienta OAuth. Sprawdź autoryzowane źródła JavaScriptu w pliku Google API Console Credentials page.

Parametr redirect_uri może odnosić się do poza zakresem protokołu OAuth (OOB), który został wycofany i nie jest już obsługiwany. Informacje na temat aktualizacji integracji znajdziesz w przewodniku po migracji.

invalid_request

Coś poszło nie tak z przesłaną przez Ciebie prośbą. Istnieje kilka możliwych przyczyn tej sytuacji:

  • Żądanie nie było poprawnie sformatowane
  • W żądaniu brakowało wymaganych parametrów
  • Żądanie używa metody autoryzacji, której Google nie obsługuje. Sprawdź, czy integracja OAuth używa 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ź na żądanie redirect_uri określone w żądaniu tokena dostępu.

Jeśli użytkownik zatwierdzi prośbę, odpowiedź będzie zawierała token dostępu. Jeśli użytkownik nie zaakceptuje prośby, odpowiedź będzie zawierała komunikat o błędzie. Token dostępu lub komunikat o błędzie jest zwracany we fragmencie z krzyżykiem identyfikatora URI przekierowania, jak w tym przykładzie:

  • 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 fragmentu zawiera też parametr token_type, który zawsze ma wartość Bearer, oraz parametr expires_in, który określa czas życia tokena w sekundach. Jeśli w żądaniu tokena dostępu określono parametr state, jego wartość także zostanie uwzględniona w odpowiedzi.

  • Odpowiedź dotycząca błędu: 
    https://oauth2.example.com/callback#error=access_denied

Przykładowa odpowiedź serwera OAuth 2.0

Możesz przetestować ten proces, klikając poniższy 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 przekierujemy Cię do http://localhost/oauth2callback. Adres URL zwróci błąd 404 NOT FOUND, chyba że komputer lokalny udostępni plik pod tym adresem. Następny krok zawiera więcej szczegółów na temat informacji zwracanych w identyfikatorze URI, gdy użytkownik zostaje przekierowany z powrotem do aplikacji.

Wywoływanie interfejsów API Google

Punkty końcowe OAuth 2.0

Gdy aplikacja uzyska token dostępu, możesz za jego pomocą wywoływać interfejs API Google w imieniu danego konta użytkownika, jeśli zostały przyznane zakresy dostępu wymagane przez interfejs API. Aby to zrobić, dołącz token dostępu do żądania wysyłanego do interfejsu API, uwzględniając parametr zapytania access_token lub wartość nagłówka HTTP Authorization Bearer. W miarę możliwości preferowany jest nagłówek HTTP, ponieważ ciągi zapytań są zwykle widoczne w logach serwera. W większości przypadków możesz użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (na przykład podczas wywoływania interfejsu Drive Files API).

Wszystkie interfejsy API Google możesz wypróbować na stronie OAuth 2.0 Playground.

Przykłady HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) przy użyciu 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 przetestować te polecenia w aplikacji wiersza poleceń curl. Oto przykład użycia opcji nagłówka HTTP (preferowane):

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 (współdzielenia zasobów między domenami) do wysyłania żądania do interfejsu Google API. W tym przykładzie nie użyto biblioteki klienta interfejsów API Google do obsługi kodu JavaScript. Jednak nawet jeśli nie korzystasz z biblioteki klienta, przewodnik pomocy CORS w dokumentacji tej biblioteki prawdopodobnie pomoże Ci lepiej zrozumieć te żądania.

W tym fragmencie kodu zmienna access_token reprezentuje token uzyskany przez Ciebie do 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 tworzenia żą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 wykonać proces OAuth 2.0 w JavaScripcie bez używania biblioteki klienta interfejsów API Google do obsługi JavaScriptu. Kod jest przeznaczony do strony HTML, na której wyświetla się przycisk umożliwiający wykonanie żądania do interfejsu API. Jeśli go klikniesz, kod sprawdzi, czy strona zapisała w pamięci lokalnej przeglądarki token dostępu interfejsu API. Jeśli tak, wykona żądanie do interfejsu API. W przeciwnym razie inicjuje proces OAuth 2.0.

W przypadku protokołu OAuth 2.0 strona powinna wyglądać następująco:

  1. Kieruje on użytkownika na serwer Google OAuth 2.0, który prosi o dostęp do zakresu https://www.googleapis.com/auth/drive.metadata.readonly.
  2. Po przyznaniu (lub odmowie) dostępu do co najmniej jednego żądanego zakresu użytkownik jest przekierowywany na stronę oryginalną, która analizuje token dostępu z ciągu identyfikatora fragmentu.

  3. Strona używa tokena dostępu, aby wysłać przykładowe żądanie do interfejsu API.

    Żądanie do interfejsu API wywołuje metodę about.get interfejsu Drive API, aby pobrać informacje o koncie Dysku Google autoryzowanego użytkownika.

  4. Jeśli żądanie zostanie wykonane, odpowiedź interfejsu API jest rejestrowana w konsoli debugowania przeglądarki.

Dostęp do aplikacji możesz odebrać na stronie Uprawnienia na swoim koncie Google. Aplikacja będzie oznaczona jako Wersja demonstracyjna OAuth 2.0 dla Dokumentów Google API.

Aby uruchomić ten kod lokalnie, ustaw wartości zmiennych YOUR_CLIENT_ID i YOUR_REDIRECT_URI, które odpowiadają Twoim danych logowania do autoryzacji. Zmienna YOUR_REDIRECT_URI powinna być ustawiona na ten sam adres URL, pod którym wyświetla się strona. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanych w API Console Credentials page. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem 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 do źródeł JavaScript podane niżej reguły weryfikacji, by pomóc programistom chronić ich aplikacje. Źródło JavaScript musi być zgodne z tymi regułami. Definicję domeny, hosta i schematu znajdziesz w sekcji 3 RFC 3986.

Reguły weryfikacji
Schemat

Źródło JavaScript musi korzystać ze schematu HTTPS, a nie zwykłego protokołu HTTP. Identyfikatory URI lokalnego hosta (w tym identyfikatory URI adresu IP lokalnego hosta) są zwolnione z tej reguły.
Osoba prowadząca

Hosty nie mogą być nieprzetworzonymi adresami IP. Adresy IP lokalnego hosta są wykluczone z tej reguły.
Domena
  • Domeny najwyższego poziomu hosta (domeny najwyższego poziomu) muszą należeć do listy domen publicznych.
  • Domeny hosta nie mogą być typu “googleusercontent.com”.
  • Źródło JavaScript nie może zawierać domen skracających adresy URL (np. goo.gl), chyba że domena jest własnością aplikacji.
    		•
    Informacje o użytkowniku

    Źródło JavaScript nie może zawierać podkomponentu informacji o użytkowniku.
    Ścieżka

    Źródło JavaScript nie może zawierać komponentu ścieżki.
    Zapytanie

    Źródło JavaScript nie może zawierać komponentu zapytania.
    Fragment

    Źródło JavaScript nie może zawierać komponentu fragment.
    Znaki Źródło JavaScript nie może zawierać niektórych znaków, w tym:
    • Symbole wieloznaczne ('*')
    • Niedrukowalne znaki ASCII
    • Nieprawidłowe kodowanie procentowe (dowolne kodowanie procentowe niezgodne z formatem adresu URL ze znakiem procentu, po którym następują 2 cyfry szesnastkowe)
    • Znaki null (zakodowany znak NULL, np. %00, %C0%80)

    Autoryzacja przyrostowa

    W protokole OAuth 2.0 aplikacja żąda autoryzacji dostępu do zasobów identyfikowanych przez zakresy. Żądanie autoryzacji zasobów we właściwym momencie jest uważane za najlepszą metodę dla użytkowników. Aby umożliwić korzystanie z tej metody, serwer autoryzacji Google obsługuje autoryzację przyrostową. Ta funkcja pozwala żądać zakresów w razie potrzeby oraz, jeśli użytkownik przyzna uprawnienia do nowego zakresu, zwraca kod autoryzacji, który można wymienić na token zawierający wszystkie zakresy przyznane projektowi przez użytkownika.

    Na przykład aplikacja, która umożliwia użytkownikom próbkowanie utworów muzycznych i tworzenie składanek, może wymagać bardzo niewielu zasobów w momencie logowania – być może nie wystarczy imię i nazwisko zalogowanej osoby. Żeby zapisać gotową składankę, trzeba mieć jednak dostęp do Dysku Google. Dla większości osób byłoby to naturalne, gdyby poproszono ich tylko o dostęp do Dysku Google w momencie, gdy aplikacja rzeczywiście tego potrzebowała.

    W tym przypadku w momencie logowania aplikacja może zażądać zakresów openid i profile w celu przeprowadzenia podstawowego logowania, a następnie w momencie pierwszego żądania zapisania składanki zażądać zakresu https://www.googleapis.com/auth/drive.file.

    Do tokena dostępu uzyskanego dzięki autoryzacji przyrostowej obowiązują te reguły:

    • Token można używać do uzyskiwania dostępu do zasobów odpowiadających dowolnym zakresom wdrożonym w nowej, połączonej autoryzacji.
    • Gdy w celu uzyskania tokena dostępu używasz tokena odświeżania połączonej autoryzacji, token dostępu reprezentuje połączoną autoryzację i może być użyty w przypadku dowolnej z wartości scope zawartych w odpowiedzi.
    • Połączona autoryzacja obejmuje wszystkie zakresy przyznane przez użytkownika projektowi API, nawet jeśli o przyznanie tych uprawnień zażądano różne klienty. Jeśli na przykład użytkownik przyznał dostęp do jednego zakresu za pomocą klienta aplikacji na komputer, a następnie przyznał inny zakres tej samej aplikacji za pomocą klienta mobilnego, łączna autoryzacja obejmie oba zakresy.
    • Jeśli unieważnisz token reprezentujący połączoną autoryzację, dostęp do wszystkich zakresów tej autoryzacji w imieniu powiązanego użytkownika zostanie jednocześnie unieważniony.

    Przykładowe fragmenty kodu poniżej pokazują, jak dodać zakresy do istniejącego tokena dostępu. Dzięki temu rozwiązaniu aplikacja nie musi 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.

    Poniższy fragment kodu pokazuje, jak to zrobić. Fragment kodu zakłada, że masz zapisane zakresy, dla których token dostępu jest prawidłowy w lokalnej pamięci przeglądarki. (Pełny przykładowy kod zawiera listę zakresów, których token dostępu jest prawidłowy – wystarczy ustawić właściwość oauth2-test-params.scope w pamięci lokalnej przeglądarki).

    Fragment kodu porównuje zakresy, których token dostępu jest prawidłowy, z zakresem, którego chcesz użyć w przypadku konkretnego zapytania. Jeśli token dostępu nie obejmuje tego zakresu, rozpocznie się proces OAuth 2.0. W tym przypadku funkcja oauth2SignIn jest taka sama jak funkcja podana w kroku 2 (która jest podana 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 zechcieć 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 do witryny lub aplikacji innych firm, które mają dostęp do Twojego konta.

    Aplikacja może też automatycznie anulować przyznany jej dostęp. Automatyczne unieważnienie jest ważne w sytuacjach, gdy użytkownik anuluje subskrypcję, usunie aplikację lub znacząco zmieniły się wymagane przez aplikację zasoby interfejsu API. Inaczej mówiąc, część procesu usuwania może obejmować żądanie do interfejsu API, aby mieć pewność, że uprawnienia przyznane wcześniej aplikacji zostaną usunięte.

    Punkty końcowe OAuth 2.0

    Aby programowo unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i uwzględnia token jako parametr:

    curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

    Tokenem może być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma odpowiedni token odświeżania, token odświeżania również zostanie unieważniony.

    Jeśli odwołanie zostanie przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędu zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

    Poniższy fragment kodu JavaScript pokazuje, jak unieważnić token w JavaScript bez użycia biblioteki klienta interfejsów API Google do obsługi JavaScriptu. Ponieważ punkt końcowy Google OAuth 2.0 do unieważniania tokenów nie obsługuje udostępniania zasobów między domenami (CORS), kod tworzy formularz i przesyła go do punktu końcowego, a nie za pomocą metody XMLHttpRequest() do opublikowania żą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();
}