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