Библиотека Google Identity Services позволяет пользователям запрашивать код авторизации у Google, используя всплывающее окно в браузере или пользовательский интерфейс Redirect. Это запускает защищенный процесс 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 Console. Оно также должно соответствовать правилам валидации URI перенаправления .В потоке UX-окон для всплывающего окна установите для
popup
ux_mode
значение popup , а для параметраcallback
— имя функции, которая будет использоваться для отправки кодов авторизации на вашу платформу. Значениеredirect_uri
по умолчанию соответствует источнику страницы, вызывающейinitCodeClient
. Поток использует это значение позже, когда вы обмениваете код авторизации на токен доступа или обновления. Например,https://www.example.com/index.html
вызываетinitCodeClient
, а источник:https://www.example.com
— значениеredirect_url
.
Защита от 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
Подтвердить запрос
Чтобы избежать CSRF-атак, выполните на своем сервере следующие действия.
Проверьте значение параметра состояния для режима перенаправления.
Убедитесь , что заголовок X-Requested-With: XmlHttpRequest
присутствует для всплывающего режима.
Затем вам следует приступить к получению токенов обновления и доступа от Google, только если вы предварительно успешно подтвердили запрос кода авторизации.
Получить доступ и обновить токены
После того как ваша внутренняя платформа получит код авторизации от Google и проверит запрос, используйте код авторизации для получения доступа и обновления токенов от Google для выполнения вызовов API.
Следуйте инструкциям, начиная с Шага 5: Обмен кода авторизации на токены обновления и доступа из руководства Использование OAuth 2.0 для приложений веб-сервера .
Управление токенами
Ваша платформа безопасно хранит токены обновления. Удаляйте сохранённые токены обновления при удалении учётных записей пользователей или при отзыве согласия пользователем через 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.