OAuth 2.0 для клиентских веб-приложений

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

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

В этом процессе ваше приложение открывает URL-адрес Google, который использует параметры запроса для идентификации вашего приложения и типа доступа к API, необходимого приложению. Вы можете открыть URL-адрес в текущем окне браузера или во всплывающем окне. Пользователь может пройти аутентификацию в Google и предоставить запрошенные разрешения. Затем Google перенаправляет пользователя обратно в ваше приложение. Перенаправление включает токен доступа, который ваше приложение проверяет, а затем использует для выполнения запросов к API.

Библиотека клиентов Google API и сервисы идентификации Google.

Если вы используете клиентскую библиотеку Google API для JavaScript для выполнения авторизованных вызовов к Google, вам следует использовать библиотеку Google Identity Services для JavaScript для обработки потока OAuth 2.0. См. модель токенов Google Identity Services, которая основана на неявном потоке предоставления доступа OAuth 2.0.

Предварительные требования

Включите API для вашего проекта

Любое приложение, использующее API Google, должно включить эти API в своих настройках. API Console.

Чтобы включить API для вашего проекта:

1. Open the API Library в Google API Console.
2. If prompted, select a project, or create a new one.
3. Он API Library В списке отображаются все доступные API, сгруппированные по семействам продуктов и популярности. Если нужный вам API отсутствует в списке, воспользуйтесь поиском, чтобы найти его, или нажмите «Показать все» в семействе продуктов, к которому он относится.
4. Выберите API, который хотите включить, затем нажмите кнопку «Включить» .
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Создать учетные данные авторизации

Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учетные данные авторизации, идентифицирующие приложение для сервера OAuth 2.0 Google. Следующие шаги описывают, как создать учетные данные для вашего проекта. Затем ваши приложения смогут использовать эти учетные данные для доступа к API, которые вы включили для этого проекта.

1. Go to the Clients page.
2. Нажмите «Создать клиента» .
3. Выберите тип приложения: Веб-приложение .
4. Заполните форму. Приложения, использующие JavaScript для выполнения авторизованных запросов к API Google, должны указать авторизованные источники JavaScript . Источники определяют домены, с которых ваше приложение может отправлять запросы на сервер OAuth 2.0. Эти источники должны соответствовать правилам проверки Google .

Определите области доступа

Области доступа (scopes) позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также дают пользователям возможность контролировать объем предоставляемого ими доступа. Таким образом, может существовать обратная зависимость между количеством запрашиваемых областей доступа и вероятностью получения согласия пользователя.

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

В документе «Области действия API OAuth 2.0» содержится полный список областей действия, которые вы можете использовать для доступа к API Google.

Получение токенов доступа OAuth 2.0

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

Шаг 1: Перенаправление на сервер Google OAuth 2.0

Чтобы запросить разрешение на доступ к данным пользователя, перенаправьте пользователя на сервер Google OAuth 2.0.

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

/*
 * 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 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();
}

Шаг 2: Google запрашивает у пользователя согласие.

На этом этапе пользователь решает, предоставлять ли вашему приложению запрошенный доступ. На этом этапе Google отображает окно согласия, в котором указывается название вашего приложения и сервисы Google API, к которым запрашивается разрешение на доступ, а также учетные данные пользователя и краткое описание предоставляемых областей доступа. Затем пользователь может дать согласие на предоставление доступа к одной или нескольким областям, запрошенным вашим приложением, или отклонить запрос.

На данном этапе вашему приложению не нужно ничего делать, поскольку оно ожидает ответа от сервера OAuth 2.0 от Google, указывающего, был ли предоставлен доступ. Этот ответ объясняется на следующем шаге.

Шаг 3: Обработка ответа сервера OAuth 2.0

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

Шаг 4: Проверьте, какие права доступа были предоставлены пользователям.

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

Однако есть исключения. Приложения Google Workspace Enterprise с делегированием полномочий на уровне домена или приложения, помеченные как «Доверенные» , обходят экран подтверждения согласия на предоставление детальных разрешений. Для таких приложений пользователи не увидят экран подтверждения согласия на предоставление детальных разрешений. Вместо этого ваше приложение получит либо все запрошенные области действия, либо ни одной.

Более подробную информацию см. в разделе «Как управлять детализированными правами доступа» .

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

Вызов API Google

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

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

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

curl https://www.googleapis.com/drive/v2/files?access_token=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) {
  console.log(xhr.response);
};
xhr.send(null);

Полный пример

<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/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 {
        // 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/drive.metadata.readonly 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>

Правила проверки источника JavaScript

Google применяет следующие правила проверки к источникам JavaScript, чтобы помочь разработчикам обеспечить безопасность своих приложений. Ваши источники JavaScript должны соответствовать этим правилам. Определение домена, хоста и схемы, упомянутых ниже, см. в разделе 3 RFC 3986 .

Поэтапная авторизация

В протоколе OAuth 2.0 ваше приложение запрашивает авторизацию для доступа к ресурсам, которые идентифицируются с помощью областей действия (scopes). Рекомендуется запрашивать авторизацию для ресурсов только тогда, когда они вам необходимы, чтобы обеспечить удобство использования. Для этого сервер авторизации Google поддерживает инкрементальную авторизацию. Эта функция позволяет запрашивать области действия по мере необходимости, и если пользователь предоставляет разрешение на новую область действия, возвращается код авторизации, который можно обменять на токен, содержащий все области действия, предоставленные пользователем проекту.

Например, приложению, позволяющему пользователям сэмплировать музыкальные треки и создавать миксы, может потребоваться очень мало ресурсов при входе в систему, возможно, всего лишь имя пользователя. Однако для сохранения готового микса потребуется доступ к его Google Диску. Большинство пользователей сочли бы естественным, если бы доступ к Google Диску запрашивался только тогда, когда это действительно необходимо приложению.

В этом случае при входе в систему приложение может запросить области действия openid и profile для выполнения базового входа, а затем позже запросить область действия https://www.googleapis.com/auth/drive.file при первом запросе для сохранения смешанного файла.

К токену доступа, полученному в результате поэтапной авторизации, применяются следующие правила:

• Токен можно использовать для доступа к ресурсам, соответствующим любой из областей действия, объединенных в новую, комбинированную авторизацию.
• При использовании токена обновления для комбинированной авторизации для получения токена доступа, этот токен доступа представляет собой комбинированную авторизацию и может использоваться для любого из значений scope , включенных в ответ.
• Объединенная авторизация включает все области действия, предоставленные пользователем проекту API, даже если запросы на предоставление были отправлены от разных клиентов. Например, если пользователь предоставил доступ к одной области действия с помощью настольного клиента приложения, а затем предоставил другой доступ к той же области действия через мобильный клиент, объединенная авторизация будет включать обе области действия.
• Если вы отзываете токен, представляющий собой объединенную авторизацию, доступ ко всем областям действия этой авторизации для соответствующего пользователя отзывается одновременно.

Приведенные ниже примеры кода показывают, как добавить области действия (scopes) к существующему токену доступа. Такой подход позволяет вашему приложению избежать необходимости управлять несколькими токенами доступа.

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

аннулирование токена

В некоторых случаях пользователь может захотеть отозвать предоставленный приложению доступ. Отозвать доступ можно, перейдя в «Настройки учетной записи» . Дополнительную информацию см. в разделе «Удаление доступа к сайту или приложению» документа поддержки «Сторонние сайты и приложения, имеющие доступ к вашей учетной записи» .

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

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

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();
}