Korzystanie z protokołu OAuth 2.0 w aplikacjach internetowych JavaScript

OAuth 2.0 Endpoints

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 te parametry ciągu zapytania w aplikacjach serwera WWW:

Przykładowe przekierowanie na serwer autoryzacji Google

Przykładowy adres URL poniżej prosi o dostęp offline (access_type=offline) do zakresu, który umożliwia wyświetlanie konta YouTube użytkownika. Korzysta on z autoryzacji przyrostowej, aby zagwarantować, że nowy token dostępu obejmuje wszystkie zakresy, do których użytkownik przyznał wcześniej dostęp aplikacji. Adres URL określa też wartości wymaganych parametrów redirect_uri, response_type i client_id oraz parametru state. Aby zapewnić czytelność, adres URL zawiera podziały wierszy i spacje.

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

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

Przykładowy kod JavaScript

Ten fragment kodu JavaScript pokazuje, jak rozpocząć proces autoryzacji w JavaScripcie bez użycia biblioteki klienta interfejsów API Google do JavaScriptu. Ten punkt końcowy OAuth 2.0 nie obsługuje współdzielenia zasobów między pochodzeniem (CORS), więc fragment kodu tworzy formularz, który otwiera żądanie kierujące 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',
                '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();
}

OAuth 2.0 Endpoints

Serwer OAuth 2.0 wysyła odpowiedź do elementu redirect_uri określonego w żądaniu tokena dostępu.

Jeśli użytkownik zatwierdzi żądanie, odpowiedź będzie zawierać token dostępu. Jeśli użytkownik nie zatwierdzi żądania, odpowiedź będzie zawierać komunikat o błędzie. Token dostępu lub komunikat o błędzie jest zwracany we fragmencie z krzyżykiem 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 z fragmentem zawiera też parametr token_type, który zawsze jest ustawiony na Bearer, oraz parametr expires_in, który określa czas trwania tokena (w sekundach). Jeśli w żądaniu tokena dostępu określono parametr state, jego wartość jest również 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 ten przykładowy adres URL, który prosi o dostęp tylko do odczytu z możliwością wyświetlania metadanych plików na Dysku Google:

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

Po zakończeniu procesu OAuth 2.0 przekierujemy Cię do http://localhost/oauth2callback. Ten adres URL zwróci błąd 404 NOT FOUND, chyba że komputer lokalny wyświetli plik pod tym adresem. W następnym kroku znajdziesz więcej informacji na temat informacji zwracanych w identyfikatorze URI, gdy użytkownik jest przekierowywany z powrotem do Twojej aplikacji.

OAuth 2.0 Endpoints

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ć, uwzględnij token dostępu w żądaniu wysyłanym do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka HTTP Bearer Authorization. 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, aby skonfigurować wywołania interfejsów API Google (na przykład wywołując YouTube Data API).

Pamiętaj, że interfejs YouTube Data API obsługuje konta usługi tylko w przypadku właścicieli treści YouTube, którzy są właścicielami wielu kanałów YouTube, takich jak wytwórnie płytowe i studia filmowe, i zarządzają nimi.

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

Przykłady żądań HTTP GET

Wywołanie punktu końcowego youtube.channels (YouTube Data API) przy użyciu nagłówka HTTP Authorization: Bearer może wyglądać tak. Pamiętaj, że musisz podać własny token dostępu:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl przykładu

Możesz je przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład z wykorzystaniem opcji nagłówka HTTP (preferowana):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Przykładowy kod JavaScript

Fragment kodu poniżej pokazuje, jak używać CORS (udostępniania zasobów między domenami) do wysłania żądania do interfejsu API Google. W tym przykładzie nie korzystamy z biblioteki klienta interfejsów API Google dla JavaScriptu. Jednak nawet wtedy, gdy 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, aby wysyłać żądania 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/youtube/v3/channels?part=snippet&mine=true&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

OAuth 2.0 Endpoints

Ten przykładowy kod pokazuje, jak wykonać przepływ OAuth 2.0 w JavaScripcie bez użycia biblioteki klienta interfejsów API Google do JavaScriptu. Kod jest przeznaczony dla strony HTML, która wyświetla 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 procesu OAuth 2.0 na stronie wykonaj te czynności:

1. Kieruje użytkownika do serwera OAuth 2.0 Google, który żąda dostępu do zakresu https://www.googleapis.com/auth/youtube.force-ssl.
2. Po przyznaniu (lub odmowie) dostępu do co najmniej 1 żą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 do przykładowego żądania do interfejsu API.

   To żądanie do interfejsu API wywołuje metodę channels.list interfejsu YouTube Data API, aby pobrać dane o kanale YouTube autoryzowanego użytkownika.

4. 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 swoim koncie Google. Aplikacja będzie widoczna jako Wersja demonstracyjna OAuth 2.0 w Dokumentach interfejsu Google API.

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świetla się strona. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania 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ż mieć 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']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/channels?part=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 {
      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',
                  '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>

OAuth 2.0 Endpoints

W tym przykładzie aplikacja do wykonywania połączeń prosi o dostęp do danych Statystyk YouTube użytkownika, a także o dostęp, który użytkownik przyznał aplikacji.

Aby dodać zakresy do istniejącego tokena dostępu, umieść parametr include_granted_scopes w żądaniu wysyłanym do serwera OAuth 2.0 Google.

Fragment kodu poniżej pokazuje, jak to zrobić. W tym fragmencie założono, że zakresy, dla których Twój token dostępu jest zapisany, w pamięci lokalnej przeglądarki. (Pełny przykład zawiera listę zakresów, dla których token dostępu jest prawidłowy. W tym celu należy ustawić właściwość oauth2-test-params.scope w pamięci lokalnej przeglądarki).

Fragment kodu porównuje zakresy, dla 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, rozpoczyna się przepływ OAuth 2.0. W tym przypadku funkcja oauth2SignIn jest taka sama jak funkcja z kroku 2 (została przedstawiona w dalszej części pełnego przykładu).

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.
}

OAuth 2.0 Endpoints

Aby automatycznie 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 będzie miał postać 200. W przypadku wystąpienia 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 JavaScriptu. Używany przez Google punkt końcowy OAuth 2.0 służący do unieważniania tokenów nie obsługuje udostępniania zasobów między domenami (CORS), dlatego kod tworzy formularz i przesyła go do punktu końcowego, zamiast korzystać z 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();
}