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