Аутентификация и авторизация – это механизмы, используемые для проверки личности и доступа к ресурсам соответственно. В этом документе описывается, как работают аутентификация и авторизация для приложений 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 с использованием аутентификации пользователя, которая ещё не была предоставлена, пользователю будет предложено войти в систему.
Запрос ресурсов. Приложение запрашивает доступ к областям действия, которые вы указываете при настройке аутентификации.
Запрос согласия. Если приложение выполняет аутентификацию от имени пользователя, Google показывает окно запроса доступа OAuth, чтобы пользователь мог решить, предоставлять ли приложению доступ к запрашиваемым данным. При аутентификации с помощью сервисного аккаунта согласие пользователя не требуется.
Отправка одобренного запроса на доступ к ресурсам. Если пользователь соглашается на предоставление доступа к областям авторизации, ваше приложение объединяет учетные данные и одобренные пользователем области в запрос. Запрос отправляется на сервер авторизации Google для получения токена доступа.
Google возвращает токен доступа. Токен доступа содержит список предоставленных областей действия. Если возвращенный список областей действия более ограничен, чем запрошенные области действия, ваше приложение отключает все функции, ограниченные токеном.
Доступ к запрашиваемым ресурсам. Приложение использует токен доступа от Google, чтобы вызвать Chat API и получить доступ к ресурсам Chat API.
Получите токен обновления (необязательно). Если вашему приложению требуется доступ к Google Chat API в течение более длительного времени, чем срок действия одного токена доступа, оно может получить токен обновления. Подробнее о том, как использовать протокол OAuth 2.0 для доступа к API Google…
Запрос дополнительных ресурсов. Если приложению требуется расширенный доступ, оно запрашивает у пользователя новые области доступа, что приводит к новому запросу на получение токена доступа (шаги 3–6).
Когда приложениям Chat требуется аутентификация
Приложения Chat могут отправлять сообщения в ответ на действия пользователя или асинхронно. Они также могут выполнять задачи от имени пользователя, например создавать чат-группы или получать список участников чат-группы.
Приложениям 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
|
Просмотр участников чатов в Google 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, вы можете добавить и эти области действия. Дополнительную информацию об областях действия API Google можно найти в статье Использование OAuth 2.0 для доступа к API Google.
Подробнее о настройке окна запроса доступа OAuth и выборе областей действия…
Типы обязательной аутентификации
Приложения Chat могут выполнять аутентификацию и авторизацию в Chat API двумя способами:
- Аутентификация пользователей
- Аутентификация пользователя позволяет приложению Chat получать доступ к пользовательским данным и выполнять действия от имени пользователя. Области действия OAuth определяют, к каким данным и действиям разрешен доступ. Если приложение 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 для приложений Google Chat…