Использовать модель кода

Библиотека Google Identity Services позволяет пользователям запрашивать код авторизации у Google, используя всплывающее окно в браузере или перенаправление. Это запускает безопасный процесс аутентификации OAuth 2.0 и приводит к получению токена доступа, используемого для вызова API Google от имени пользователя.

Сводная информация о процессе авторизации с использованием кода OAuth 2.0:

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

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

Выполните действия, описанные в разделе «Настройка» , чтобы настроить экран согласия OAuth, получить идентификатор клиента и загрузить библиотеку клиентов.

Инициализация клиента кода

Метод google.accounts.oauth2.initCodeClient() инициализирует клиент кода.

Всплывающее окно или режим перенаправления

You can choose to share an auth code using either the Redirect or Popup mode user flow. With Redirect mode you host an OAuth2 authorization endpoint on your server and Google redirects the user-agent to this endpoint, sharing the auth code as a URL parameter. For Popup mode you define a JavaScript callback handler, which sends the authorization code to your server. You can use Popup mode to provide a seamless user experience without visitors having to leave your site.

Для инициализации клиента:

• Для перенаправления потока UX установите ux_mode в redirect , а значение redirect_uri на конечную точку кода авторизации вашей платформы. Значение должно точно соответствовать одному из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили в консоли Google Cloud. Оно также должно соответствовать правилам проверки URI перенаправления .

• Popup UX flow, set ux_mode to popup , and the value of callback to the name of the function you will use to send authorization codes to your platform. The value of redirect_uri defaults to the origin of the page that calls initCodeClient . The flow uses this value later when you exchange the auth code for an access or refresh token. For example, https://www.example.com/index.html calls initCodeClient and the origin: https://www.example.com is the value of redirect_url .

Защита от CSRF-атак

Redirect and Popup mode UX flows use slightly different techniques to help prevent Cross-Site-Request-Forgery (CSRF) attacks. For Redirect mode, use the OAuth 2.0 state parameter. See RFC6749 section 10.12 Cross-Site Request Forgery for more on generating and validating the state parameter. With Popup mode, you add a custom HTTP header to your requests, and then on your server confirm it matches the expected value and origin.

Выберите режим пользовательского интерфейса, чтобы просмотреть фрагмент кода, демонстрирующий код авторизации и обработку CSRF-атак:

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

Запуск потока кода OAuth 2.0

Для запуска пользовательского сценария вызовите метод requestCode() клиентского кода:

<button onclick="client.requestCode();">Authorize with Google</button>

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

Обработка кода авторизации

Google генерирует уникальный код авторизации для каждого пользователя, который вы получаете и проверяете на своем бэкэнд-сервере.

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

В режиме перенаправления Google отправляет GET запрос на конечную точку, указанную параметром redirect_uri , передавая код авторизации в параметре code URL. Чтобы получить код авторизации:

• Если у вас нет существующей реализации, создайте новую конечную точку авторизации .

• Обновите существующую конечную точку, чтобы она принимала GET запросы и параметры URL. Ранее Google отправлял PUT запрос со значением кода авторизации в полезной нагрузке.

Конечная точка авторизации

Ваша конечная точка для авторизационного кода должна обрабатывать GET запросы со следующими параметрами строки запроса URL:

В соответствии с RFC 6749, клиенты ОБЯЗАТЕЛЬНО должны игнорировать неопознанные параметры ответа, независимо от того, указаны ли они в приведенной выше таблице.

Пример GET запроса с параметрами URL к конечной точке с именем auth-code , размещенной на сайте example.com:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

При запуске процесса авторизации с использованием более ранних версий библиотек JavaScript или при прямых вызовах к конечным точкам Google OAuth 2.0, Google отправляет POST запрос.

Пример POST запроса, содержащего код авторизации в качестве полезной нагрузки в теле HTTP-запроса:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

Подтвердите запрос

Для предотвращения CSRF-атак выполните следующие действия на вашем сервере.

Проверьте значение параметра state для режима перенаправления.

Убедитесь , что заголовок X-Requested-With: XmlHttpRequest присутствует в режиме всплывающего окна.

Получение токенов обновления и доступа от Google следует осуществлять только после успешной проверки запроса кода авторизации.

Получите токены доступа и обновления.

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

Следуйте инструкциям, начиная с шага 5: Обменяйте код авторизации на токены обновления и доступа, согласно руководству «Использование OAuth 2.0 для веб-серверных приложений» .

Управление токенами

Ваша платформа надежно хранит токены обновления. Удалите сохраненные токены обновления при удалении учетных записей пользователей или при отзыве согласия пользователем с помощью google.accounts.oauth2.revoke или напрямую через https://myaccount.google.com/permissions .

В качестве дополнительной меры вы можете рассмотреть возможность использования RISC для защиты учетных записей пользователей с помощью функции защиты от межсетевых атак .

Typically, your backend platform will call Google APIs using an access token. If your web app will also directly call Google APIs from the user's browser you must implement a way to share the access token with your web application, doing so is out of scope of this guide. When following this approach and using the Google API Client Library for JavaScript use gapi.client.SetToken() to temporarily store the access token in browser memory, and enable the library to call Google APIs.