Аутентификация и авторизация – это механизмы, используемые для подтверждения личности и доступа к ресурсам соответственно. В этом документе рассказывается, как работает аутентификация и авторизация для приложений Chat и запросов к Chat API.
Обзор
На приведенной ниже схеме показаны основные этапы аутентификации и авторизации для Google Chat.
Настройте проект Google Cloud, включите Chat API и настройте приложение Chat. Во время разработки вы создаете проект Google Cloud. В облачном проекте Google Cloud вы включите Chat API, настроите приложение Chat и зададите аутентификацию. Подробнее о том, как разрабатывать приложения для Google Workspace и как создать приложение для Chat…
Вызов Chat API. Когда приложение вызывает Chat API, оно отправляет учетные данные для аутентификации в Chat API. Если для аутентификации в приложении используется сервисный аккаунт, учетные данные отправляются как часть кода приложения. Если для вашего приложения требуется вызывать Chat API с использованием аутентификации пользователя, которая ещё не была предоставлена, пользователю будет предложено войти в аккаунт.
Запрос ресурсов. Приложение запрашивает доступ с помощью областей действия, которые вы указываете при настройке аутентификации.
Запрос согласия. Если приложение проходит аутентификацию как пользователь, Google показывает окно запроса согласия OAuth, чтобы пользователь мог решить, предоставлять ли приложению доступ к запрошенным данным. Для аутентификации с помощью сервисного аккаунта не требуется согласие пользователя.
Отправьте одобренный запрос на ресурсы. Если пользователь предоставил согласие на области авторизации, ваше приложение объединяет учетные данные и одобренные пользователем области в запрос. Запрос отправляется на сервер авторизации Google, чтобы получить токен доступа.
Google возвращает токен доступа. Токен доступа содержит список предоставленных областей действия. Если возвращенный список областей действия более ограничен, чем запрошенный, приложение отключает все функции, ограниченные токеном.
Доступ к запрошенным ресурсам. Ваше приложение использует токен доступа от Google, чтобы вызывать Chat API и получать доступ к ресурсам Chat API.
Получите токен обновления (необязательно). Если приложению требуется доступ к Google Chat API дольше, чем действует токен доступа, оно может получить токен обновления. Подробнее о том, как использовать протокол OAuth 2.0 для доступа к API Google…
Запросить дополнительные ресурсы. Если приложению требуется больше доступа, оно просит пользователя предоставить новые области действия, в результате чего отправляется новый запрос на получение токена доступа (шаги 3–6).
Когда приложения для чата требуют аутентификации
Приложения Chat могут отправлять сообщения в ответ на действия пользователя или асинхронно. Они также могут выполнять задачи от имени пользователя, например создавать чат-группы Google Chat или получать список участников чат-группы.
Приложениям для Chat не требуется аутентификация, чтобы отвечать на действия пользователей, если только приложение не вызывает Chat API или другой API Google при обработке ответа.
Чтобы отправлять асинхронные сообщения или выполнять задачи от имени пользователя, приложения для Chat отправляют REST-запросы к Chat API, для которых требуется аутентификация и авторизация.
Ответы на действия пользователей не требуют аутентификации
Приложениям Google Chat не нужно проходить аутентификацию как пользователь или приложение Chat, чтобы получать события взаимодействия и отвечать на них синхронно.
Приложения Google Chat получают события взаимодействия, когда пользователь взаимодействует с приложением Chat или вызывает его, например:
- Пользователь отправляет сообщение в приложение Chat.
- Пользователь упоминает приложение Chat.
- Пользователь вызывает одну из команд приложения Chat.
На приведенной ниже схеме показана последовательность запросов и ответов между пользователем Chat и приложением Chat.
- Пользователь отправляет сообщение приложению Chat в Google Chat.
- Google Chat пересылает сообщение приложению.
- Приложение получает сообщение, обрабатывает его и отправляет ответ в Google Chat.
- Google Chat отображает ответ для пользователя или в чат-группе.
Эта последовательность повторяется для каждого события взаимодействия с приложением Chat.
Для асинхронных сообщений требуется аутентификация
Асинхронные сообщения появляются, когда приложение Chat отправляет запрос к Chat API, для которого требуется аутентификация и авторизация.
Вызывая Chat API, приложения Chat могут публиковать сообщения в Google Chat или выполнять задачи и получать доступ к данным от имени пользователя. Например, после обнаружения сбоя в работе сервера приложение Chat может вызвать Chat API, чтобы:
- Создайте чат-группу Chat, посвященную расследованию и устранению сбоя.
- Добавьте пользователей в чат-группу Chat.
- Опубликуйте в чат-группе сообщение с подробной информацией о сбое.
На диаграмме ниже показана последовательность асинхронных сообщений между приложением Chat и чат-группой Chat.
- Приложение Chat создает сообщение, вызывая Chat API с помощью метода
spaces.messages.createи включая учетные данные пользователя в HTTP-запрос. - Google Chat выполняет аутентификацию приложения Chat с помощью сервисного аккаунта или учетных данных пользователя.
- Google Chat преобразует сообщение приложения в чат-группу Chat.
Области действия Chat API
Настройте окно запроса доступа OAuth и выберите области действия, чтобы определить, какая информация будет показываться пользователям и проверяющим приложение, а также зарегистрируйте приложение, чтобы опубликовать его позже.
Чтобы определить уровень доступа, предоставленный приложению, необходимо указать области авторизации. Область авторизации – это строка URI OAuth 2.0, которая содержит название приложения Google Workspace, тип данных, к которым оно получает доступ, и уровень доступа.
Области действия, не связанные с конфиденциальными данными
| Код области действия | Описание |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
Позволяет приложениям Chat просматривать чаты и отправлять сообщения. Эта область действия поддерживает только аутентификацию приложений с помощью сервисных аккаунтов. Вы не можете выполнить аутентификацию с помощью учетных данных пользователя или делегирования на уровне домена, используя эту область действия. |
Области действия с доступом к конфиденциальным данным
| Код области действия | Описание |
|---|---|
https://www.googleapis.com/auth/chat.spaces
|
Создание чатов и чат-групп, а также просмотр и изменение их метаданных в Chat (включая настройки доступа и сохранения истории). |
https://www.googleapis.com/auth/chat.spaces.create
|
Создавать новые чаты в Chat. |
https://www.googleapis.com/auth/chat.spaces.readonly
|
Просматривать чаты и чат-группы в Chat. |
https://www.googleapis.com/auth/chat.memberships
|
Просмотр, изменение, добавление и удаление участников чатов в Chat. |
https://www.googleapis.com/auth/chat.memberships.app
|
Добавление и удаление самого себя в чатах Google Chat. |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Просмотр участников чатов в Chat |
https://www.googleapis.com/auth/chat.messages.create
|
Создание и отправка сообщений в Chat. |
https://www.googleapis.com/auth/chat.messages.reactions
|
Просмотр, добавление и удаление реакций на сообщения в Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
Добавьте реакцию на сообщение в Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
Просматривать реакции на сообщения в Chat. |
https://www.googleapis.com/auth/chat.users.readstate
|
Просмотр и изменение времени последнего прочтения чатов в Chat. |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
Просмотр времени последнего прочтения чатов в Chat. |
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
Просматривать чаты и чат-группы, принадлежащие домену администратора, в Chat. |
https://www.googleapis.com/auth/chat.admin.spaces
|
Просматривать и изменять чаты и чат-группы, принадлежащие домену администратора, в Chat. |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
Просмотр участников и менеджеров чатов, принадлежащих домену администратора, в Chat. |
https://www.googleapis.com/auth/chat.admin.memberships
|
Просмотр, добавление, изменение и удаление участников и менеджеров чатов в домене администратора в Chat. |
https://www.googleapis.com/auth/chat.app.spaces
|
Создание чатов и чат-групп, а также просмотр и изменение их метаданных в Chat как приложения Chat (включая настройки доступа и сохранения истории). Требуется одобрение администратора. Эта область действия поддерживает только аутентификацию приложений с помощью сервисных аккаунтов. Вы не можете выполнить аутентификацию с помощью учетных данных пользователя или делегирования на уровне домена, используя эту область действия. |
https://www.googleapis.com/auth/chat.app.spaces.readonly
|
Просмотр метаданных (включая настройки сохранения истории) в Chat в качестве приложения Chat. Требуется одобрение администратора. Эта область действия поддерживает только аутентификацию приложений с помощью сервисных аккаунтов. Вы не можете выполнить аутентификацию с помощью учетных данных пользователя или делегирования на уровне домена, используя эту область действия. |
https://www.googleapis.com/auth/chat.app.spaces.create
|
Создание чатов и чат-групп в Chat в качестве приложения Chat. Требуется одобрение администратора. Эта область действия поддерживает только аутентификацию приложений с помощью сервисных аккаунтов. Вы не можете выполнить аутентификацию с помощью учетных данных пользователя или делегирования на уровне домена, используя эту область действия. |
https://www.googleapis.com/auth/chat.app.memberships
|
Просмотр, добавление или удаление участников, а также обновление их списка в чатах и чат-группах в Chat как приложение Chat. Требуется одобрение администратора. Эта область действия поддерживает только аутентификацию приложений с помощью сервисных аккаунтов. Вы не можете выполнить аутентификацию с помощью учетных данных пользователя или делегирования на уровне домена, используя эту область действия. |
https://www.googleapis.com/auth/chat.app.memberships.readonly
|
Просматривать участников чатов и чат-групп в Chat как приложение Chat. Требуется одобрение администратора. Эта область действия поддерживает только аутентификацию приложений с помощью сервисных аккаунтов. Вы не можете выполнить аутентификацию с помощью учетных данных пользователя или делегирования на уровне домена, используя эту область действия. |
https://www.googleapis.com/auth/chat.customemojis
|
Просмотр, создание и удаление пользовательских эмодзи в Chat. |
https://www.googleapis.com/auth/chat.customemojis.readonly
|
Просматривать пользовательские эмодзи в Chat. |
https://www.googleapis.com/auth/chat.users.spacesettings
|
Просматривать и изменять настройки чат-групп пользователей Chat. |
https://www.googleapis.com/auth/chat.users.sections
|
Просмотр, создание, обновление и удаление разделов в Chat; перемещение объектов в ваших разделах и составление списка этих объектов в Chat. |
https://www.googleapis.com/auth/chat.users.sections.readonly
|
Просмотр разделов и их содержимого в Chat. |
Ограниченные области действия
| Код области действия | Описание |
|---|---|
https://www.googleapis.com/auth/chat.delete
|
Удаление чатов и чат-групп, а также закрытие доступа к связанным с ними файлам в Chat. |
https://www.googleapis.com/auth/chat.import
|
Импорт чат-групп, данных об участии и сообщений в Chat Подробнее о том, как разрешить приложениям Chat импортировать данные… |
https://www.googleapis.com/auth/chat.messages
|
Просмотр, создание, отправка, изменение и удаление сообщений, а также добавление, просмотр и удаление откликов на сообщения |
https://www.googleapis.com/auth/chat.messages.readonly
|
Просматривать сообщения и реакции в Chat. |
https://www.googleapis.com/auth/chat.app.messages.readonly
|
Просмотр сообщений и реакций в Chat в качестве приложения Chat. Требуется одобрение администратора. Эта область действия поддерживает только аутентификацию приложений с помощью сервисных аккаунтов. Вы не можете выполнить аутентификацию с помощью учетных данных пользователя или делегирования на уровне домена, используя эту область действия. |
https://www.googleapis.com/auth/chat.admin.delete
|
Удаление чатов и чат-групп, принадлежащих домену администратора, и закрытие доступа к связанным с ними файлам в Chat. |
https://www.googleapis.com/auth/chat.app.delete
|
Удаление чатов и чат-групп, а также закрытие доступа к связанным с ними файлам в Chat в качестве приложения Chat. Требуется одобрение администратора. Эта область действия поддерживает только аутентификацию приложений с помощью сервисных аккаунтов. Вы не можете выполнить аутентификацию с помощью учетных данных пользователя или делегирования на уровне домена, используя эту область действия. |
В таблицах выше указаны области действия и их уровень конфиденциальности в соответствии со следующими определениями:
Неконфиденциальные. Эти области предоставляют минимальный уровень доступа и требуют только базовой проверки приложения. Подробнее о том, как подготовиться к проверке…
Конфиденциальные. Эти области действия предоставляют приложению доступ к определенным данным пользователя в Google после того, как он предоставит разрешение. Вам потребуется пройти дополнительную проверку приложения. Подробнее о требованиях к приложениям, запрашивающим конфиденциальные области действия…
Ограниченные. Эти области действия предоставляют широкий доступ к пользовательским данным Google и требуют прохождения процесса проверки ограниченной области действия. Подробнее об этом требовании можно узнать из Правил в отношении пользовательских данных сервисов API Google и дополнительных требований для определенных областей действия API. Также ознакомьтесь с инструкциями для приложений, запрашивающих ограниченные области действия.
Если вашему приложению требуется доступ к другим API Google, вы также можете добавить эти области. Подробнее об использовании OAuth 2.0 для доступа к API Google…
Подробнее о настройке окна запроса доступа OAuth и выборе областей действия…
Типы обязательной аутентификации
Приложения Chat могут проходить аутентификацию и авторизацию в Chat API двумя способами:
- Аутентификация пользователей
- Аутентификация пользователей позволяет приложению Chat получать доступ к пользовательским данным и выполнять действия от имени пользователя. Области действия OAuth определяют, к каким данным и действиям предоставляется доступ. Если приложение Chat не было установлено администратором или ему не было предоставлено делегирование на уровне домена, при первом выполнении приложением Chat действия от имени пользователя он должен авторизовать приложение Chat с помощью окна запроса доступа OAuth.
- Аутентификация приложений
Аутентификация приложений позволяет приложению Chat использовать учетные данные сервисного аккаунта, получать доступ к данным и выполнять действия от своего имени. Поскольку приложение Chat использует собственные учетные данные для доступа к ресурсам и работы с ними, конечным пользователям не нужно одобрять вызовы API приложения Chat, и вы не можете добавить области авторизации OAuth, поддерживающие авторизацию приложений, на окно запроса доступа OAuth.
Для аутентификации приложений поддерживаются два типа областей действия авторизации OAuth:
https://www.googleapis.com/auth/chat.bot: Приложение Chat может вызывать методы Google Chat API, поддерживающие эту область авторизации, чтобы создавать, обновлять, получать, перечислять или удалять ресурсы, к которым у него есть доступ, например сообщения в чат-группах, в которые конечные пользователи добавили приложение Chat. Приложение Chat может самостоятельно предоставить себе эту область авторизации. Разрешение администратора или конечного пользователя не требуется.https://www.googleapis.com/auth/chat.app.*: Для использования этих областей действия требуется одноразовое одобрение администратора. Чтобы получить одобрение администратора, подготовьте сервисный аккаунт приложения Chat к получению одобрения администратора, создав OAuth-клиент, совместимый с Google Workspace Marketplace, и настроив приложение в Google Workspace Marketplace SDK. Эти области действия позволяют приложению Chat вызывать определенные методы Google Chat API. Например,chat.app.spaces.createпозволяет приложениям создавать чат-группы Chat.
Если метод поддерживает аутентификацию как пользователя, так и приложения, Chat API возвращает разные результаты в зависимости от типа аутентификации:
- При аутентификации приложения методы возвращают только те ресурсы, к которым может получить доступ приложение Chat.
- При аутентификации пользователя методы возвращают только те ресурсы, к которым у пользователя есть доступ.
Например, при вызове метода spaces.list() с авторизацией приложения возвращается список чат-групп, в которых состоит приложение Chat.
При вызове spaces.list() с авторизацией пользователя возвращается список чат-групп, в которых он состоит. На практике при вызове Chat API можно использовать оба типа аутентификации в зависимости от дизайна и функций приложения Chat.
Для асинхронных вызовов Chat API
В таблице ниже перечислены методы Chat API и поддерживаемые ими области авторизации:
| Метод | Поддерживается аутентификация пользователей. | Поддерживается аутентификация приложений. | Поддерживаемые области авторизации | |
|---|---|---|---|---|
| Чат-группы | ||||
| Как создать чат-группу |
При использовании аутентификации пользователей:
|
|||
| Как настроить чат-группу | — |
При использовании аутентификации пользователей:
|
||
| Как получить чат-группу |
При использовании аутентификации пользователей:
|
|||
| Как посмотреть список чат-групп |
При использовании аутентификации пользователей:
|
|||
| Поиск чат-групп | — |
При аутентификации пользователей с использованием прав администратора:
|
||
| Как изменить чат-группу |
При использовании аутентификации пользователей:
|
|||
| Как удалить чат-группу |
При использовании аутентификации пользователей:
|
|||
| Как завершить импорт чат-группы | — |
При использовании аутентификации пользователей:
|
||
| Как найти прямую переписку |
При использовании аутентификации пользователей:
|
|||
| Участники | ||||
| Как создать участника |
При использовании аутентификации пользователей:
|
|||
| Получение информации о спонсоре |
При использовании аутентификации пользователей:
|
|||
| Участники списка |
При использовании аутентификации пользователей:
|
|||
| Как удалить участника |
При использовании аутентификации пользователей:
|
|||
| Как изменить данные участника |
При использовании аутентификации пользователей:
|
|||
| Сообщения | ||||
| Как создать сообщение |
При использовании аутентификации пользователей:
|
|||
| Получить сообщение |
При использовании аутентификации пользователей:
|
|||
| Как посмотреть список писем |
При использовании аутентификации пользователей:
|
|||
| Как искать сообщения | — |
При использовании аутентификации пользователей:
|
||
| Как изменить сообщение |
При использовании аутентификации пользователей:
|
|||
| Как удалить сообщение |
При использовании аутентификации пользователей:
|
|||
| Как закрепить сообщение | — |
При использовании аутентификации пользователей:
|
||
| Как открепить сообщение | — |
При использовании аутентификации пользователей:
|
||
| Как посмотреть список закрепленных сообщений | — |
При использовании аутентификации пользователей:
|
||
| Обновление карточек в письме | — |
Аутентификация приложения:
|
||
| Отклики | ||||
| Как создать реакцию | — |
При использовании аутентификации пользователей:
|
||
| Как посмотреть реакции | — |
При использовании аутентификации пользователей:
|
||
| Как удалить реакцию | — |
При использовании аутентификации пользователей:
|
||
| Особые эмодзи | ||||
| Как создать собственный эмодзи | — |
При использовании аутентификации пользователей:
|
||
| Как удалить собственный эмодзи | — |
При использовании аутентификации пользователей:
|
||
| Как получить собственный эмодзи | — |
При использовании аутентификации пользователей:
|
||
| Как посмотреть список собственных эмодзи | — |
При использовании аутентификации пользователей:
|
||
| Медиа и прикрепленные файлы | ||||
| Как загрузить медиаконтент в виде прикрепленного файла | — |
При использовании аутентификации пользователей:
|
||
| Скачать медиаконтент |
При использовании аутентификации пользователей:
|
|||
| Как получить прикрепленный файл | — |
Аутентификация приложения:
|
||
| Статусы прочтения | ||||
| Как получить статус прочтения чат-группы для пользователя | — |
При использовании аутентификации пользователей:
|
||
| Как изменить статус "Прочитано" для чат-группы | — |
При использовании аутентификации пользователей:
|
||
| Как получить статус прочтения цепочки писем пользователя | — |
При использовании аутентификации пользователей:
|
||
| Настройки чат-групп пользователей | ||||
| Как получить настройки уведомлений чат-группы для пользователя | — |
При использовании аутентификации пользователей:
|
||
| Как изменить настройки уведомлений для чат-группы | — |
При использовании аутентификации пользователей:
|
||
| События в чатах | ||||
| Получение событий чат-группы | — |
При использовании аутентификации пользователей необходимо задать область действия на основе
типа события:
|
||
| Список событий чат-группы | — |
При использовании аутентификации пользователей для каждого
типа события, включенного в запрос, необходимо указать область:
|
||
| Разделы | ||||
| Как создать раздел | — |
При использовании аутентификации пользователей:
|
||
| Как удалить раздел | — |
При использовании аутентификации пользователей:
|
||
| Как посмотреть разделы списка | — |
При использовании аутентификации пользователей:
|
||
| Как изменить раздел | — |
При использовании аутентификации пользователей:
|
||
| Как расположить раздел | — |
При использовании аутентификации пользователей:
|
||
| Элементы раздела | ||||
| Как переместить элемент раздела | — |
При использовании аутентификации пользователей:
|
||
| Как составить список задач | — |
При использовании аутентификации пользователей:
|
||
Для событий взаимодействия с приложением Chat
В таблице ниже перечислены распространенные способы взаимодействия пользователей с приложениями Chat и указано, требуется ли аутентификация и поддерживается ли она.
| Сценарий | Аутентификация не требуется | Поддерживается аутентификация пользователей. | Поддерживается аутентификация приложений. | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Получать сообщения от: |
|
|||||||||||||||
| Отвечать на сообщения: |
|
|||||||||||||||
| Отправлять новые сообщения: |
|
|||||||||||||||
Статьи по теме
- Общие сведения об аутентификации и авторизации в Google Workspace можно найти в статье Аутентификация и авторизация.
- Общую информацию об аутентификации и авторизации в Google Cloud можно найти в обзоре аутентификации.
- Подробнее о сервисных аккаунтах…
- Подробнее о том, как использовать протокол OAuth 2.0 для доступа к API Google…
- Настройте аутентификацию и авторизацию с помощью учетных данных пользователя или сервисного аккаунта.
- Чтобы управлять детализированными разрешениями OAuth, ознакомьтесь со статьей Как управлять детализированными разрешениями OAuth для приложений Google Chat.