OAuth 2.0 dla aplikacji internetowych po stronie klienta

Punkty końcowe OAuth 2.0

Wygeneruj URL, aby poprosić o dostęp z punktu końcowego OAuth 2.0 Google na stronie https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy jest dostępny przez HTTPS; zwykłe połączenia HTTP są odrzucane.

Serwer autoryzacji Google obsługuje następujące parametry ciągu zapytania dla aplikacji serwera WWW:

Przykładowe przekierowanie na serwer autoryzacji Google

Poniżej znajduje się przykładowy adres URL z podziałami między wierszami i spacjami pod kątem czytelności.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Po utworzeniu adresu URL żądania przekieruj użytkownika do tego adresu.

Przykładowy kod JavaScript

Ten fragment kodu JavaScript pokazuje, jak rozpocząć proces autoryzacji w języku JavaScript bez korzystania z biblioteki klienta interfejsów API Google. Ten punkt końcowy OAuth 2.0 nie obsługuje współdzielenia zasobów między serwerami z różnych źródeł (fragmenty kodu), dlatego fragment kodu tworzy formularz otwierający żądanie kierowane do tego punktu końcowego.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

Punkty końcowe OAuth 2.0

Serwer OAuth 2.0 wysyła odpowiedź na żądanie redirect_uri podane w żądaniu tokena dostępu.

Jeśli użytkownik zaakceptuje prośbę, odpowiedź będzie zawierać token dostępu. Jeśli użytkownik nie zaakceptuje żądania, odpowiedź będzie zawierać komunikat o błędzie. Token dostępu lub komunikat o błędzie jest zwracany we fragmencie skrótu identyfikatora URI przekierowania, jak pokazano poniżej:

• Odpowiedź tokena dostępu:

  https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

  Oprócz parametru access_token ciąg znaków fragmentu zawiera też 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ść jest też uwzględniana w odpowiedzi.

• Odpowiedź błędu:

  https://oauth2.example.com/callback#error=access_denied

Przykładowa odpowiedź serwera OAuth 2.0

Możesz go przetestować, klikając ten przykładowy URL, który prosi o dostęp tylko do odczytu do wyświetlania metadanych plików na Dysku Google:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Po zakończeniu procedury OAuth 2.0 nastąpi przekierowanie na stronę http://localhost/oauth2callback. Ten URL spowoduje wyświetlenie błędu 404 NOT FOUND, chyba że komputer lokalny wyświetli plik pod tym adresem. Następny krok zawiera więcej szczegółów dotyczących informacji zwracanych w identyfikatorze URI, gdy użytkownik jest przekierowywany z powrotem do aplikacji.

Punkty końcowe OAuth 2.0

Gdy aplikacja uzyska token dostępu, możesz go używać do wywoływania interfejsu Google API w imieniu danego konta użytkownika, jeśli zostały przyznane zakresy dostępu wymagane przez ten interfejs. W tym celu umieść token dostępu w żądaniu wysyłanym do interfejsu API, dodając parametr zapytania access_token lub wartość nagłówka HTTP Authorization Bearer. Jeśli to możliwe, zalecamy użycie nagłówka HTTP, ponieważ ciągi zapytań są zwykle widoczne w dziennikach serwera. W większości przypadków wywołania biblioteki interfejsów API Google możesz skonfigurować na przykład za pomocą biblioteki klienta Drive API.

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

Przykłady HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) korzystającego z nagłówka HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz określić własny token dostępu:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Przykłady zapytań z operatorem curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

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

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Przykładowy kod JavaScript

Fragment kodu poniżej pokazuje, jak używać CORS (udostępniania zasobów między domenami) do wysyłania żądań do interfejsu API Google. W tym przykładzie nie wykorzystano biblioteki JavaScript interfejsów API Google. Nawet jeśli nie korzystasz z biblioteki klienta, przewodnik CORS w dokumentacji tej biblioteki pomoże Ci lepiej zrozumieć te żądania.

W tym fragmencie kodu zmienna access_token reprezentuje token uzyskany w celu wysyłania żądań do interfejsu API w imieniu autoryzowanego użytkownika. Pełny przykład pokazuje, jak zapisać ten token w pamięci lokalnej przeglądarki i pobrać go podczas wysyłania żądania do interfejsu API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Punkty końcowe OAuth 2.0

Ten przykładowy kod pokazuje, jak zakończyć obsługę protokołu OAuth 2.0 w języku JavaScript bez korzystania z biblioteki klienta interfejsów API Google dla JavaScriptu. Kod dotyczy strony HTML, która zawiera przycisk umożliwiający wypróbowanie żądania do interfejsu API. Jeśli klikniesz ten przycisk, kod sprawdzi, czy strona zapisała token dostępu API w pamięci lokalnej przeglądarki. Jeśli tak, wykonuje żądanie do interfejsu API. W przeciwnym razie inicjuje przepływ OAuth 2.0.

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

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

3. Strona używa tokena dostępu do wykonywania przykładowego żądania do interfejsu API.

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

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 koncie Google. Aplikacja będzie widoczna jako Prezentacja OAuth 2.0 dla Dokumentów Google API.

Aby uruchomić ten kod lokalnie, musisz ustawić wartości zmiennych YOUR_CLIENT_ID i YOUR_REDIRECT_URI, które odpowiadają Twoim danym logowania. Zmienna YOUR_REDIRECT_URI powinna być ustawiona na ten sam adres URL, pod którym jest wyświetlana strona. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanego w API Console Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI, wystąpi błąd redirect_uri_mismatch. Twój projekt musi też włączyć odpowiedni interfejs API dla tego żądania.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0) {
    localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
    if (params['state'] && params['state'] == 'try_sample_request') {
      trySampleRequest();
    }
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null);
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
                  'state': 'try_sample_request',
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

Punkty końcowe OAuth 2.0

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

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

Fragment kodu porównuje zakresy, w przypadku których token dostępu jest prawidłowy z zakresem obejmującym konkretne zapytanie. Jeśli token dostępu nie obejmuje tego zakresu, rozpocznie się proces OAuth 2.0. W tym przypadku funkcja oauth2SignIn jest taka sama jak w kroku 2 (i została udostępniona później w pełnym przykładzie).

var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));

var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
  var scopes = params['scope'].split(' ');
  for (var s = 0; s < scopes.length; s++) {
    if (SCOPE == scopes[s]) {
      current_scope_granted = true;
    }
  }
}

if (!current_scope_granted) {
  oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
  // Since you already have access, you can proceed with the API request.
}

Punkty końcowe OAuth 2.0

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

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

Może to być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma odpowiedni token odświeżania, zostanie on też unieważniony.

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

Poniższy fragment kodu JavaScript umożliwia unieważnienie tokena w kodzie JavaScript bez użycia biblioteki klienta interfejsów API Google. Ponieważ punkt końcowy OAuth 2.0 Google do anulowania tokenów nie obsługuje współdzielenia zasobów z innych domen (CORS), kod tworzy formularz i przesyła go do punktu końcowego, zamiast publikować metodę za pomocą metody XMLHttpRequest().

function revokeAccess(accessToken) {
  // Google's OAuth 2.0 endpoint for revoking access tokens.
  var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';

  // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'post');
  form.setAttribute('action', revokeTokenEndpoint);

  // Add access token to the form so it is set as value of 'token' parameter.
  // This corresponds to the sample curl request, where the URL is:
  //      https://oauth2.googleapis.com/revoke?token={token}
  var tokenField = document.createElement('input');
  tokenField.setAttribute('type', 'hidden');
  tokenField.setAttribute('name', 'token');
  tokenField.setAttribute('value', accessToken);
  form.appendChild(tokenField);

  // Add form to page and submit it to actually revoke the token.
  document.body.appendChild(form);
  form.submit();
}