Библиотека JavaScript google.accounts.oauth2 помогает запрашивать согласие пользователя и получать токен доступа для работы с данными пользователя. Она основана на неявном потоке предоставления доступа OAuth 2.0 и предназначена для того, чтобы вы могли либо напрямую вызывать API Google с использованием REST и CORS, либо использовать нашу клиентскую библиотеку Google API для JavaScript (также известную как gapi.client ) для простого и гибкого доступа к нашим более сложным API.
Прежде чем получить доступ к защищенным пользовательским данным из браузера, пользователи вашего сайта запускают веб-процесс выбора учетной записи Google, входа в систему и получения согласия, после чего серверы OAuth Google выдают и возвращают токен доступа вашему веб-приложению.
В модели авторизации на основе токенов нет необходимости хранить токены обновления для каждого пользователя на вашем бэкэнд-сервере.
Рекомендуется использовать подход, описанный здесь, вместо методов, рассмотренных в более старом руководстве по OAuth 2.0 для клиентских веб-приложений .
Предварительные требования
Выполните действия, описанные в разделе «Настройка» , чтобы настроить экран согласия OAuth, получить идентификатор клиента и загрузить библиотеку клиентов.
Инициализация клиента токенов
Для инициализации нового клиента токена с использованием идентификатора клиента вашего веб-приложения необходимо указать список из одного или нескольких областей доступа, к initTokenClient() пользователь должен иметь доступ:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (response) => {
...
},
});
Запустить процесс передачи токена OAuth 2.0.
Используйте метод requestAccessToken() для запуска процесса получения токена и получения токена доступа. Google предлагает пользователю:
- Выберите их аккаунт,
- Войдите в свой аккаунт Google, если вы еще не вошли в него.
- Предоставьте вашему веб-приложению разрешение на доступ к каждой запрошенной области.
Жест пользователя запускает процесс получения токена: <button onclick="client.requestAccessToken();">Authorize me</button>
Затем Google возвращает обработчику обратного вызова TokenResponse содержащий токен доступа и список областей действия, к которым пользователь предоставил доступ, или сообщение об ошибке.
Пользователи могут закрыть окна выбора учетной записи или входа в систему, в этом случае ваша функция обратного вызова не будет вызвана.
Как обрабатывать согласие
Разработка дизайна и пользовательского интерфейса вашего приложения должна осуществляться только после тщательного изучения политики Google OAuth 2.0 . Эти политики охватывают работу с несколькими областями действия, когда и как обрабатывать согласие пользователя и многое другое.
Поэтапная авторизация — это методология проектирования приложений и политик, используемая для запроса доступа к ресурсам с использованием областей действия только по мере необходимости, а не сразу и целиком. Пользователи могут одобрять или отклонять предоставление доступа к отдельным ресурсам, запрашиваемым вашим приложением; это называется детализированными разрешениями .
В ходе этого процесса Google запрашивает согласие пользователя, индивидуально перечисляя каждый запрашиваемый объем данных, пользователи выбирают ресурсы, которые будут предоставлены вашему приложению, и, наконец, Google вызывает вашу функцию обратного вызова, которая возвращает токен доступа и одобренные пользователем объемы данных. Затем ваше приложение безопасно обрабатывает различные возможные результаты с помощью детального управления разрешениями.
Однако есть исключения. Приложения Google Workspace Enterprise с делегированием полномочий на уровне домена или приложения, помеченные как «Доверенные» , обходят экран подтверждения согласия на предоставление детальных разрешений. Для таких приложений пользователи не увидят экран подтверждения согласия на предоставление детальных разрешений. Вместо этого ваше приложение получит либо все запрошенные области действия, либо ни одной.
Более подробную информацию см. в разделе «Как управлять детализированными правами доступа» .
Поэтапная авторизация
Для веб-приложений следующие два основных сценария демонстрируют поэтапную авторизацию с использованием:
- Одностраничное Ajax-приложение, часто использующее
XMLHttpRequestс динамическим доступом к ресурсам. - Многочисленные веб-страницы и ресурсы разделены и управляются на уровне отдельных страниц.
Эти два сценария представлены для иллюстрации проектных соображений и методологий, но не являются исчерпывающими рекомендациями по внедрению механизма согласия в ваше приложение. В реальных приложениях могут использоваться различные варианты или комбинации этих методов.
Аякс
Добавьте в свое приложение поддержку инкрементальной авторизации, выполняя несколько вызовов метода requestAccessToken() и используя параметр scope объекта OverridableTokenClientConfig для запроса отдельных областей действия по мере необходимости и только тогда, когда это требуется. В этом примере ресурсы будут запрашиваться и отображаться только после того, как жест пользователя развернет свернутый раздел контента.
| Приложение Ajax |
|---|
Инициализировать клиент для получения токена при загрузке страницы:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Документы для чтенияПоказать последние документы
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Предстоящие событияПоказать информацию календаря
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
ФотокарусельПоказать фотографии
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
})
);
|
Каждый вызов метода requestAccessToken инициирует момент получения согласия пользователя, в результате чего ваше приложение будет иметь доступ только к тем ресурсам, которые необходимы для раздела, который пользователь решит развернуть, тем самым ограничивая совместное использование ресурсов в зависимости от выбора пользователя.
Несколько веб-страниц
При разработке системы поэтапной авторизации используется несколько страниц для запроса только тех областей действия, которые необходимы для загрузки страницы, что снижает сложность и необходимость выполнения нескольких запросов для получения согласия пользователя и получения токена доступа.
| Многостраничное приложение | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Каждая страница запрашивает необходимую область действия и получает токен доступа, вызывая методы initTokenClient() и requestAccessToken() во время загрузки. В этом сценарии отдельные веб-страницы используются для четкого разделения функциональности и ресурсов пользователя по областям действия. В реальной ситуации отдельные страницы могут запрашивать несколько связанных областей действия.
Детальные разрешения
Детальная настройка разрешений обрабатывается одинаково во всех сценариях; после того, как requestAccessToken() вызовет вашу функцию обратного вызова и вернет токен доступа, проверьте, подтвердил ли пользователь запрошенные области действия, используя hasGrantedAllScopes() или hasGrantedAnyScope() . Например:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly \
https://www.googleapis.com/auth/documents.readonly \
https://www.googleapis.com/auth/photoslibrary.readonly',
callback: (tokenResponse) => {
if (tokenResponse && tokenResponse.access_token) {
if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
'https://www.googleapis.com/auth/photoslibrary.readonly')) {
// Look at pictures
...
}
if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
'https://www.googleapis.com/auth/calendar.readonly',
'https://www.googleapis.com/auth/documents.readonly')) {
// Meeting planning and review documents
...
}
}
},
});
Любые ранее полученные разрешения из предыдущих сессий или запросов также будут включены в ответ. Запись о согласии пользователя хранится для каждого пользователя и идентификатора клиента и сохраняется при многократных вызовах initTokenClient() или requestAccessToken() . По умолчанию согласие пользователя требуется только при первом посещении вашего веб-сайта и запросе новой области действия, но может запрашиваться при каждой загрузке страницы с помощью prompt=consent в объектах конфигурации Token Client.
Работа с токенами
В модели Token токен доступа не хранится операционной системой или браузером; вместо этого новый токен сначала получается во время загрузки страницы, либо впоследствии путем вызова функции requestAccessToken() в результате действия пользователя, например, нажатия кнопки.
Использование REST и CORS с API Google.
Токен доступа можно использовать для выполнения аутентифицированных запросов к API Google с использованием REST и CORS. Это позволяет пользователям входить в систему, давать согласие, Google выдавать токен доступа, а вашему сайту — работать с данными пользователя.
В этом примере просмотрите предстоящие события календаря авторизованных пользователей, используя токен доступа, возвращаемый функцией tokenRequest() :
var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();
API Google по умолчанию поддерживают CORS; включение токена доступа в запрос XMLHttpRequest или fetch запускает предварительную проверку CORS; запрос OPTIONS выполняется перед запросом GET или POST.
В следующем разделе рассматривается, как легко интегрироваться с более сложными API.
Работа с библиотекой JavaScript для API Google
Клиент для токенов работает с библиотекой Google API Client Library для JavaScript. См. фрагмент кода ниже.
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
callback: (tokenResponse) => {
if (tokenResponse && tokenResponse.access_token) {
gapi.client.setApiKey('YOUR_API_KEY');
gapi.client.load('calendar', 'v3', listUpcomingEvents);
}
},
});
function listUpcomingEvents() {
gapi.client.calendar.events.list(...);
}
Срок действия токена истекает
По своей природе токены доступа имеют короткий срок действия. Если срок действия токена доступа истекает до окончания сеанса пользователя, получите новый токен, вызвав метод requestAccessToken() при возникновении события, инициированного пользователем, например, нажатия кнопки.
Использование токена доступа для отзыва согласия
Вызовите метод google.accounts.oauth2.revoke , чтобы отозвать согласие пользователя и доступ к ресурсам для всех областей действия, предоставленных вашему приложению. Для отзыва этого разрешения требуется действительный токен доступа:
google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
console.log(done);
console.log(done.successful);
console.log(done.error);
console.log(done.error_description);
});