Korzystanie z protokołu OAuth 2.0 w aplikacjach internetowych po stronie klienta

Punkty końcowe OAuth 2.0

Wygeneruj adres URL, aby poprosić o dostęp do 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. Połączenia HTTP nie są obsługiwane.

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

Przykładowe przekierowanie do serwera autoryzacji Google

Poniżej znajduje się przykładowy adres URL z przecinkami wierszy i spacją dla czytelności. Adres URL prosi o dostęp do zakresu, który umożliwia pobieranie danych użytkownika z YouTube. Używa ona stopniowego udzielania uprawnień (include_granted_scopes=true), aby zapewnić, że nowy token dostępu obejmuje wszystkie zakresy, do których użytkownik wcześniej przyznał aplikacji dostęp. W przykładzie ustawiono też kilka innych parametrów.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 client_id=client_id

Po utworzeniu adresu URL żądania przekieruj użytkownika na niego.

Przykładowy kod JavaScript

Ten fragment kodu JavaScriptu pokazuje, jak zainicjować proces autoryzacji w JavaScript bez użycia biblioteki klienta interfejsów API Google dla JavaScriptu. Ponieważ ten punkt końcowy OAuth 2.0 nie obsługuje współdzielenia zasobów pomiędzy serwerami z różnych domen (CORS), 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/youtube.force-ssl 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();
}

Punkty końcowe OAuth 2.0

Serwer OAuth 2.0 wysyła odpowiedź do redirect_uri podanego w żądaniu tokena dostępu.

Jeśli użytkownik zatwierdzi żądanie, odpowiedź będzie zawierać token dostępu. Jeśli użytkownik nie zaakceptuje prośby, odpowiedź będzie zawierać komunikat o błędzie. Token dostępu lub komunikat o błędzie jest zwracany w haśle fragmentu 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 zawiera on też parametr token_type, który jest zawsze ustawiony na wartość Bearer, oraz parametr expires_in, który określa czas ważności tokenu w sekundach. Jeśli parametr state został określony w żądaniu tokena dostępu, 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 przetestować ten proces, klikając ten przykładowy adres URL, który prosi o dostęp tylko do odczytu w celu wyświetlania metadanych plików na Dysku Google oraz dostęp tylko do odczytu w celu wyświetlania wydarzeń w Kalendarzu Google:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 client_id=client_id

Po zakończeniu procesu OAuth 2.0 zostaniesz przekierowany na stronę http://localhost/oauth2callback. Ten adres URL spowoduje błąd 404 NOT FOUND, chyba że na Twoim komputerze lokalnym znajduje się plik o tym adresie. Następny krok zawiera więcej informacji o danych zwracanych w identyfikatorze URI, gdy użytkownik zostanie przekierowany z powrotem do aplikacji.

Punkty końcowe OAuth 2.0

Aby sprawdzić, czy użytkownik przyznał aplikacji dostęp do określonego zakresu, sprawdź pole scope w odpowiedzi na żądanie tokena dostępu. Zakresy dostępu przyznawane przez token dostępu w postaci listy ciągów znaków oddzielonych spacjami, w których rozróżniane są wielkość liter.

Na przykład ta przykładowa odpowiedź na żądanie tokena dostępu wskazuje, że użytkownik przyznał Twojej aplikacji uprawnienia do odczytu aktywności na Dysku i do wydarzeń w Kalendarzu:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Punkty końcowe OAuth 2.0

Gdy aplikacja uzyska token dostępu, możesz używać tego tokena do wywoływania interfejsów API Google w imieniu danego konta użytkownika, jeśli przyznano uprawnienia dostępu wymagane przez interfejs API. Aby to zrobić, dodaj token dostępu do żądania do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka HTTP Authorization Bearer. Jeśli to możliwe, zalecamy użycie nagłówka HTTP, ponieważ ciągi znaków zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków do konfigurowania wywołań interfejsów API Google (np. wywołania interfejsu YouTube Live Streaming API) możesz użyć biblioteki klienta.

Pamiętaj, że interfejs YouTube Live Streaming API nie obsługuje procesu tworzenia konta usługi. Nie można połączyć konta usługi z kontem YouTube, więc próby autoryzacji żądań za pomocą tego procesu spowodują błąd NoLinkedYouTubeAccount.

Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy na stronie OAuth 2.0 Playground.

Przykłady żądań HTTP GET

Wywołanie punktu końcowego liveBroadcasts.list (interfejsu YouTube Live Streaming API) za pomocą nagłówka HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz podać własny token dostępu:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Oto wywołanie tego samego interfejsu API dla uwierzytelnionego użytkownika za pomocą parametru ciągu zapytania access_token:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl przykładu

Te polecenia możesz przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład użycia opcji nagłówka HTTP (preferowana):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Możesz też użyć parametru ciągu zapytania:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Przykładowy kod JavaScript

Ten fragment kodu pokazuje, jak za pomocą CORS (udostępnianie zasobów między domenami) wysłać żądanie do interfejsu Google API. W tym przykładzie nie używamy biblioteki klienta interfejsów API Google dla JavaScriptu. Nawet jeśli nie używasz biblioteki klienta, przewodnik po obsłudze CORS w dokumentacji tej biblioteki może Ci pomóc 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 odzyskać go podczas wysyłania żądania do interfejsu API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Punkty końcowe OAuth 2.0

Ten przykładowy kod pokazuje, jak ukończyć proces OAuth 2.0 w JavaScript bez używania biblioteki klienta interfejsów Google API dla JavaScriptu. Kod jest przeznaczony do strony HTML, na której wyświetla się przycisk umożliwiający wypróbowanie żądania interfejsu API. Gdy 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 interfejsu API. W przeciwnym razie rozpocznie przepływ OAuth 2.0.

W przypadku protokołu OAuth 2.0 strona wykonuje te czynności:

1. Przekierowuje użytkownika do serwera OAuth 2.0 Google, który prosi o dostęp do zakresów https://www.googleapis.com/auth/youtube.force-ssl i https://www.googleapis.com/auth/calendar.readonly.
2. Po przyznaniu (lub odmowie przyznania) dostępu do co najmniej jednego żądanego zakresu użytkownik jest przekierowywany na stronę pierwotną, która zinterpretuje token dostępu z łańcucha identyfikatora fragmentu.
3. Strona sprawdza, do których zakresów użytkownik przyznał dostęp aplikacji.

4. Jeśli użytkownik przyznał dostęp do żądanych zakresów, strona używa tokena dostępu do przesłania przykładowego żądania interfejsu API.

   To żądanie interfejsu API wywołuje metodę liveBroadcasts.list interfejsu YouTube Data API, aby pobrać listę transmisji wideo na kanale YouTube autoryzowanego użytkownika.

5. Jeśli żądanie zostanie wykonane pomyślnie, odpowiedź interfejsu API zostanie zarejestrowana w konsoli debugowania przeglądarki.

Możesz cofnąć dostęp aplikacji na stronie Uprawnienia na koncie Google. Aplikacja będzie widoczna jako Demo OAuth 2.0 dla interfejsu Google Docs API.

Aby uruchomić ten kod lokalnie, musisz ustawić wartości zmiennych YOUR_CLIENT_ID i YOUR_REDIRECT_URI odpowiadające Twoim danym autoryzacyjnym. Zmienna YOUR_REDIRECT_URI powinna być ustawiona na ten sam URL, pod którym wyświetlana jest strona. Wartość musi dokładnie pasować do jednego z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API Console Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI, pojawi się błąd redirect_uri_mismatch. Twój projekt musi też mieć włączony odpowiedni interfejs API do obsługi tej prośby.

<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/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
          '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/youtube.force-ssl 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>

Punkty końcowe OAuth 2.0

W tym przykładzie aplikacja wywołująca prosi o dostęp do danych użytkownika w YouTube, oprócz innych uprawnień, które użytkownik już przyznał aplikacji.

Aby dodać zakresy do istniejącego tokena dostępu, dodaj parametr include_granted_scopes do żądania wysyłanego na serwer OAuth 2.0 Google.

Poniżej znajdziesz fragment kodu, który pokazuje, jak to zrobić. Fragment kodu zakłada, że zakresy, dla których token dostępu jest ważny, są przechowywane w pamięci lokalnej przeglądarki. (Kod pełnego przykładu przechowuje listę zakresów, w których token dostępu jest ważny, ustawiając właściwość oauth2-test-params.scope w pamięci lokalnej przeglądarki.)

Fragment kodu porównuje zakresy, w których token dostępu jest ważny, z zakresem, którego chcesz użyć w konkretnym zapytaniu. Jeśli token dostępu nie obejmuje tego zakresu, rozpoczyna się przepływ OAuth 2.0. Funkcja oauth2SignIn jest taka sama jak w kroku 2 (i jest podana później w pełnym przykładzie).

var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
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.
}

Punkty końcowe OAuth 2.0

Aby programowo unieważnić token, aplikacja wysyła żądanie do interfejsu https://oauth2.googleapis.com/revoke, dołączając token jako parametr:

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

Token może być tokenem dostępu lub tokenem odświeżania. Jeśli token jest tokenem dostępu i ma odpowiadający mu token odświeżania, token odświeżania zostanie również cofnięty.

Jeśli odwołanie zostało przetworzone, kod stanu HTTP odpowiedzi to 200. W przypadku błędów zwracany jest kod stanu HTTP 400 oraz kod błędu.

Ten fragment kodu JavaScriptu pokazuje, jak cofnąć token w JavaScriptzie bez używania biblioteki klienta interfejsów Google API dla JavaScriptu. Ponieważ punkt końcowy Google OAuth 2.0 do odwoływania tokenów nie obsługuje udostępniania zasobów między domenami (CORS), kod tworzy formularz i przesyła go do punktu końcowego zamiast używać metody XMLHttpRequest() do przesył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();
}