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

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

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

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

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

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

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

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

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

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

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

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

• В потоке всплывающего окна UX установите ux_mode в popup , а значение callback на имя функции, которую вы будете использовать для отправки кодов авторизации на вашу платформу. Значение redirect_uri по умолчанию равно источнику страницы, которая вызывает initCodeClient . Поток использует это значение позже, когда вы обмениваете код авторизации на токен доступа или обновления. Например, https://www.example.com/index.html вызывает initCodeClient , и источником: https://www.example.com является значение redirect_url .

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

В режимах перенаправления и всплывающего окна используются несколько разные методы для предотвращения атак типа «подделка межсайтовых запросов» (CSRF). В режиме перенаправления используйте параметр состояния OAuth 2.0. Подробнее о генерации и проверке параметра состояния см. в разделе 10.12 RFC6749 «Подделка межсайтовых запросов» . В режиме всплывающего окна вы добавляете пользовательский HTTP-заголовок к своим запросам, а затем на сервере подтверждаете, что он соответствует ожидаемому значению и источнику.

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

Как правило, ваша серверная платформа будет вызывать API Google, используя токен доступа. Если ваше веб-приложение также будет напрямую вызывать API Google из браузера пользователя, вам необходимо реализовать способ обмена токеном доступа с вашим веб-приложением; это выходит за рамки данного руководства. При использовании этого подхода и библиотеки Google API Client Library for JavaScript используйте gapi.client.SetToken() для временного хранения токена доступа в памяти браузера и включения возможности вызова API Google библиотекой.