Использование OAuth 2.0 для веб-приложений JavaScript

Конечные точки OAuth 2.0

Создайте URL-адрес для запроса доступа к конечной точке Google OAuth 2.0 по адресу https://accounts.google.com/o/oauth2/v2/auth . Эта конечная точка доступна через HTTPS; простые HTTP-соединения отклоняются.

Сервер авторизации Google поддерживает следующие параметры строки запроса для приложений веб-сервера:

Пример перенаправления на сервер авторизации Google

В приведенном ниже примере URL-адреса запрашивается автономный доступ ( access_type=offline ) к области, которая разрешает доступ для просмотра учетной записи YouTube пользователя. Он использует добавочную авторизацию, чтобы гарантировать, что новый токен доступа охватывает все области, к которым пользователь ранее предоставил доступ приложению. URL-адрес также устанавливает значения для обязательных параметров redirect_uri , response_type и client_id , а также для параметра state . URL-адрес содержит разрывы строк и пробелы для удобства чтения.

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

После создания URL-адреса запроса перенаправьте на него пользователя.

Пример кода JavaScript

В следующем фрагменте JavaScript показано, как инициировать поток авторизации в JavaScript без использования клиентской библиотеки Google API для JavaScript. Поскольку эта конечная точка OAuth 2.0 не поддерживает совместное использование ресурсов между источниками (CORS), фрагмент создает форму, которая открывает запрос к этой конечной точке.

/*
 * 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

Сервер OAuth 2.0 отправляет ответ на redirect_uri , указанный в запросе токена доступа.

Если пользователь одобряет запрос, то ответ содержит токен доступа. Если пользователь не одобряет запрос, ответ содержит сообщение об ошибке. Токен доступа или сообщение об ошибке возвращается в хеш-фрагменте URI перенаправления, как показано ниже:

• Ответ токена доступа:

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

  Помимо параметра access_token , строка фрагмента также содержит параметр token_type , для которого всегда установлено значение Bearer , и параметр expires_in , который определяет время жизни токена в секундах. Если параметр state был указан в запросе токена доступа, его значение также включается в ответ.

• Ответ об ошибке:

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

Пример ответа сервера OAuth 2.0

Вы можете протестировать этот процесс, щелкнув следующий пример URL-адреса, который запрашивает доступ только для чтения для просмотра метаданных файлов на вашем 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

После завершения потока OAuth 2.0 вы будете перенаправлены на http://localhost/oauth2callback . Этот URL-адрес выдаст ошибку 404 NOT FOUND если только ваш локальный компьютер не обслуживает файл по этому адресу. Следующий шаг предоставляет более подробную информацию об информации, возвращаемой в URI, когда пользователь перенаправляется обратно в ваше приложение.

Конечные точки OAuth 2.0

После того как ваше приложение получит токен доступа, вы можете использовать его для выполнения вызовов API Google от имени определенной учетной записи пользователя, если предоставлены области доступа, требуемые API. Для этого включите токен доступа в запрос к API, включив либо параметр запроса access_token , либо значение Bearer HTTP-заголовка Authorization . Когда это возможно, предпочтительнее использовать HTTP-заголовок, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев вы можете использовать клиентскую библиотеку для настройки вызовов API Google (например, при вызове API данных YouTube ).

Обратите внимание, что API данных YouTube поддерживает учетные записи служб только для владельцев контента YouTube, которые владеют и управляют несколькими каналами YouTube, например звукозаписывающих компаний и киностудий.

Вы можете опробовать все API Google и просмотреть их возможности на игровой площадке OAuth 2.0 .

Примеры HTTP GET

Вызов конечной точки youtube.channels (API данных YouTube) с использованием HTTP-заголовка Authorization: Bearer может выглядеть следующим образом. Обратите внимание, что вам необходимо указать свой собственный токен доступа:

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

Вот вызов того же API для аутентифицированного пользователя с использованием параметра строки запроса access_token :

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

примеры curl

Вы можете протестировать эти команды с помощью приложения командной строки curl . Вот пример, в котором используется опция HTTP-заголовка (предпочтительно):

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

Или, альтернативно, опция параметра строки запроса:

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

Пример кода JavaScript

В приведенном ниже фрагменте кода показано, как использовать CORS (совместное использование ресурсов между источниками) для отправки запроса в API Google. В этом примере не используется клиентская библиотека API Google для JavaScript. Однако даже если вы не используете клиентскую библиотеку, руководство по поддержке CORS в документации этой библиотеки, скорее всего, поможет вам лучше понять эти запросы.

В этом фрагменте кода переменная access_token представляет токен, который вы получили для выполнения запросов API от имени авторизованного пользователя. Полный пример демонстрирует, как сохранить этот токен в локальном хранилище браузера и получить его при выполнении запроса 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

В этом примере кода показано, как выполнить поток OAuth 2.0 в JavaScript без использования клиентской библиотеки API Google для JavaScript. Код предназначен для HTML-страницы, на которой отображается кнопка для попытки запроса API. Если вы нажмете кнопку, код проверит, сохранил ли страница токен доступа к API в локальном хранилище вашего браузера. Если да, он выполняет запрос API. В противном случае он инициирует поток OAuth 2.0.

Для потока OAuth 2.0 на странице выполняются следующие шаги:

1. Он направляет пользователя на сервер OAuth 2.0 Google, который запрашивает доступ к области https://www.googleapis.com/auth/youtube.force-ssl .
2. После предоставления (или отказа) доступа к одной или нескольким запрошенным областям пользователь перенаправляется на исходную страницу, которая анализирует токен доступа из строки идентификатора фрагмента.

3. Страница использует токен доступа для выполнения примера запроса API.

   Этот запрос API вызывает метод channels.list API данных YouTube для получения данных о канале YouTube авторизованного пользователя.

4. Если запрос выполняется успешно, ответ API регистрируется в консоли отладки браузера.

Вы можете отозвать доступ к приложению на странице разрешений своей учетной записи Google. Приложение будет указано как демонстрационная версия OAuth 2.0 для документов Google API .

Чтобы запустить этот код локально, вам необходимо установить значения для переменных YOUR_CLIENT_ID и YOUR_REDIRECT_URI , соответствующие вашим учетным данным для авторизации . В переменной YOUR_REDIRECT_URI должен быть установлен тот же URL-адрес, по которому обслуживается страница. Значение должно точно соответствовать одному из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в разделе API Console Credentials page. Если это значение не соответствует авторизованному URI, вы получите ошибку redirect_uri_mismatch . В вашем проекте также должен быть включен соответствующий API для этого запроса.

<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

В этом примере вызывающее приложение запрашивает доступ для получения данных YouTube Analytics пользователя в дополнение к любому другому доступу, который пользователь уже предоставил приложению.

Чтобы добавить области к существующему токену доступа, включите параметр include_granted_scopes в свой запрос к серверу OAuth 2.0 Google .

Следующий фрагмент кода демонстрирует, как это сделать. В этом фрагменте предполагается, что вы сохранили области, для которых действителен ваш токен доступа, в локальном хранилище браузера. ( Полный код примера сохраняет список областей, для которых действителен токен доступа, путем установки свойства oauth2-test-params.scope в локальном хранилище браузера.)

Фрагмент сравнивает области, для которых действителен токен доступа, с областью, которую вы хотите использовать для определенного запроса. Если токен доступа не охватывает эту область, запускается поток OAuth 2.0. Здесь функция oauth2SignIn аналогична той, которая была предоставлена ​​на шаге 2 (и она представлена ​​позже в полном примере ).

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

Чтобы программно отозвать токен, ваше приложение отправляет запрос https://oauth2.googleapis.com/revoke и включает токен в качестве параметра:

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

Маркер может быть маркером доступа или маркером обновления. Если токен является токеном доступа и имеет соответствующий токен обновления, токен обновления также будет отозван.

Если отзыв успешно обработан, код состояния HTTP ответа — 200 . В случае возникновения ошибки код состояния HTTP 400 возвращается вместе с кодом ошибки.

В следующем фрагменте JavaScript показано, как отозвать токен в JavaScript без использования клиентской библиотеки Google API для JavaScript. Поскольку конечная точка OAuth 2.0 Google для отзыва токенов не поддерживает совместное использование ресурсов между источниками (CORS), код создает форму и отправляет ее в конечную точку, а не использует метод 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();
}