OAuth 2.0 na potrzeby aplikacji internetowych po stronie klienta

Punkty końcowe OAuth 2.0

Wygeneruj adres URL, aby poprosić o dostęp z punktu końcowego Google OAuth 2.0 pod adresem 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 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. Ten punkt końcowy OAuth 2.0 nie obsługuje udostępniania zasobów między serwerami (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',
                '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 określone 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ła komunikat o błędzie. Token dostępu lub komunikat o błędzie są zwracane 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 jest ustawiony na 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ść również zostanie uwzględniona w odpowiedzi.

• Odpowiedź błędu:

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

Przykładowa odpowiedź serwera OAuth 2.0

Aby przetestować ten proces, kliknij poniższy przykładowy adres URL, który poprosi 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

Gdy zakończy się proces obsługi OAuth 2.0, przekierujemy Cię do http://localhost/oauth2callback. Ten adres URL spowoduje błąd 404 NOT FOUND, chyba że komputer lokalny wyświetli 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 Twojej aplikacji.

Punkty końcowe OAuth 2.0

Gdy aplikacja uzyska token dostępu, możesz za jego pomocą wywoływać interfejs Google API w imieniu danego konta użytkownika(o ile 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, 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 (np. podczas wywołania interfejsu Drive Files API).

Wszystkie interfejsy API Google możesz wypróbować i zobaczyć ich zakresy w OAuth 2.0 Playground.

Przykłady HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) za pomocą 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 za pomocą aplikacji wiersza poleceń curl. Oto przykład, w którym użyto 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 API Google. W tym przykładzie nie wykorzystano biblioteki klienta interfejsów API Google do obsługi JavaScriptu. 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 na potrzeby wysyłania żądań do interfejsu API w imieniu autoryzowanego użytkownika. Pełny przykład pokazuje, jak zapisać ten token w lokalnej pamięci przeglądarki i pobrać go podczas wykonywania żą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 wykonać przepływ OAuth 2.0 w JavaScripcie bez korzystania z 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 klikniesz przycisk, kod sprawdzi, czy strona zapisała token dostępu interfejsu API w pamięci lokalnej przeglądarki. Jeśli tak, wykona żądanie do interfejsu API. W przeciwnym razie inicjuje przepływ OAuth 2.0.

W przypadku protokołu OAuth 2.0 strona wykonuje następujące czynności:

1. Kieruje on użytkownika na serwer Google OAuth 2.0, który żąda dostępu 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 z identyfikatorem fragmentu.

3. Strona używa tokena dostępu, aby wysył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 zostanie zarejestrowana w konsoli debugowania przeglądarki.

Dostęp do aplikacji możesz odebrać na stronie Uprawnienia na swoim koncie Google. Aplikacja będzie wymieniona 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 odpowiadające Twoim danych logowania do autoryzacji. Zmienna YOUR_REDIRECT_URI powinna mieć ustawiony ten sam adres URL, pod którym wyświetla się strona. Wartość musi być dokładnie taka sama jak jeden z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanych 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 wysyłanym do serwera OAuth 2.0 Google.

Poniższy fragment kodu pokazuje, jak to zrobić. Fragment kodu zakłada, że zakresy, dla których token dostępu jest prawidłowy, są zapisane w pamięci lokalnej przeglądarki. (Kod pełnego przykładu zawiera listę zakresów, dla 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, którego chcesz użyć w przypadku konkretnego zapytania. Jeśli token dostępu nie obejmuje tego zakresu, rozpocznie się przepływ OAuth 2.0. Funkcja oauth2SignIn jest tu taka sama jak funkcja podana w kroku 2 (została podana w dalszej części pełnego przykładu).

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 programowo unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i umieszcza 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 jest to token dostępu, który ma odpowiedni token odświeżania, token odświeżania również zostanie unieważniony.

Jeśli odwołanie zostanie przetworzone pomyślnie, kod stanu HTTP odpowiedzi to 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 obsługi JavaScriptu. 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, zamiast używać metody XMLHttpRequest() do publikowania żą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();
}