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

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

Сводка потока кода авторизации OAuth 2.0:

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

Ключевой момент: на вашем внутреннем сервере вы обмениваете код авторизации на токены обновления и токены доступа , вызывая конечную точку токена Google .

Предпосылки

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

Инициализировать клиент кода

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

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

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

Чтобы инициализировать клиент для:

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

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

Ключевой момент: для достижения наилучшего баланса удобства использования и безопасности мы рекомендуем использовать UX-поток всплывающего режима с моделью кода авторизации.

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

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

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

Режим перенаправления

Инициализируйте клиент, при котором Google перенаправляет браузер пользователя на вашу конечную точку аутентификации, передавая код аутентификации в качестве параметра URL.

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

Ключевой момент: конечная точка на вашем внутреннем сервере получает и проверяет код авторизации, обменивая его на токены доступа и обновления .

Всплывающий режим

Инициализируйте клиент, где пользователь начинает процесс авторизации во всплывающем диалоговом окне. После получения согласия Google возвращает код авторизации в браузер пользователя с помощью функции обратного вызова. Запрос POST от обработчика обратного вызова JS доставляет код авторизации в конечную точку на внутреннем сервере, где вы сначала проверяете его, а затем завершаете оставшуюся часть процесса OAuth.

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

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

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

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

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

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

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

Имя	Ценить
authuser	Запрос на аутентификацию при входе пользователя в систему
код	Код авторизации OAuth2, сгенерированный Google
hd	Размещенный домен учетной записи пользователя
быстрый	Диалог согласия пользователя
объем	Список из одной или нескольких областей OAuth2, подлежащих авторизации, разделенных пробелами
состояние	Переменная состояния CRSF

Пример запроса 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

Важно: Ранее для запросов использовался POST . Обновите обработчик, чтобы он принимал запросы GET и POST или рассмотрите возможность размещения двух разных конечных точек, если вы планируете продолжать использовать старые библиотеки JS или напрямую вызывать конечные точки Google OAuth 2.0 при использовании библиотеки Google Identity Services.

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

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

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

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

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

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

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

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

Примечание: При использовании всплывающего режима значение redirect_uri , используемое в шаге 5 и далее, является источником вызывающей страницы. Например, https://www.example.com/index.html вызывает initCodeClient , а источник: https://www.example.com — это значение redirect_url .

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

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

При желании вы можете рассмотреть возможность использования RISC для защиты учетных записей пользователей с помощью Cross-Account Protection .

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