Аутентификация и авторизация — это механизмы, используемые для проверки личности и доступа к ресурсам соответственно. В этом документе описывается, как работают аутентификация и авторизация для приложений чата и запросов к API чата.
Обзор процесса
На следующей диаграмме показаны основные этапы аутентификации и авторизации для Google Chat:
Настройте проект Google Cloud, включите Chat API и настройте приложение чата: В процессе разработки вы создадите проект Google Cloud. В этом проекте вы включите Chat API, настроите приложение чата и установите аутентификацию. Для получения дополнительной информации см. разделы «Разработка в Google Workspace» и «Создание приложения чата» .
Вызов API чата: Когда ваше приложение вызывает API чата, оно отправляет в API чата учетные данные для аутентификации. Если ваше приложение аутентифицируется с помощью сервисной учетной записи, учетные данные отправляются как часть кода вашего приложения. Если вашему приложению требуется вызывать API чата, используя аутентификацию пользователя, которая еще не была предоставлена, оно запрашивает у пользователя вход в систему.
Запрос ресурсов : Ваше приложение запрашивает доступ с областями действия , которые вы указываете при настройке аутентификации.
Запрос согласия: если ваше приложение проходит аутентификацию как пользователь, Google отображает экран согласия OAuth, чтобы пользователь мог решить, предоставлять ли вашему приложению доступ к запрашиваемым данным. Аутентификация с помощью служебной учетной записи не требует согласия пользователя.
Отправка одобренного запроса на доступ к ресурсам: если пользователь соглашается с областями авторизации, ваше приложение объединяет учетные данные и одобренные пользователем области авторизации в запрос. Запрос отправляется на сервер авторизации Google для получения токена доступа.
Google возвращает токен доступа: токен доступа содержит список предоставленных областей действия. Если возвращенный список областей действия более ограничен, чем запрошенные, ваше приложение отключает все функции, ограниченные токеном.
Доступ к запрошенным ресурсам: Ваше приложение использует токен доступа от Google для вызова API чата и доступа к ресурсам API чата.
Получите токен обновления (необязательно): если вашему приложению необходимо получить доступ к API Google Chat после истечения срока действия одного токена доступа, оно может получить токен обновления. Дополнительную информацию см. в разделе «Использование OAuth 2.0 для доступа к API Google» .
Запрос дополнительных ресурсов: Если вашему приложению требуется расширенный доступ, оно запрашивает у пользователя предоставление новых областей действия, что приводит к новому запросу на получение токена доступа (шаги 3-6).
Когда приложения для чата требуют аутентификации
Приложения для чата могут отправлять сообщения в ответ на взаимодействие с пользователем или асинхронно. Они также могут выполнять задачи от имени пользователя, например, создавать чат-пространство или получать список участников чат-пространства.
Приложения для чата не требуют аутентификации для ответа на взаимодействие с пользователем, за исключением случаев, когда приложение для чата обращается к API чата или другому API Google при обработке ответа.
Для отправки асинхронных сообщений или выполнения задач от имени пользователя приложения чата отправляют RESTful-запросы к API чата , которые требуют аутентификации и авторизации.
Ответы на действия пользователя не требуют аутентификации.
Google Chat apps don't need to authenticate as a user or Chat app to receive and respond synchronously to interaction events .
Приложения Google Chat получают события взаимодействия всякий раз, когда пользователь взаимодействует с приложением чата или вызывает его, включая следующие:
- Пользователь отправляет сообщение в приложение для чата.
- Пользователь упоминает приложение для чата с помощью символа @.
- Пользователь вызывает одну из команд приложения «Чат».
The following diagram shows a request-response sequence between a Chat user and Chat app:
- Пользователь отправляет сообщение в приложение «Чат» в Google Chat.
- Google Chat пересылает сообщение в приложение.
- Приложение получает сообщение, обрабатывает его и отправляет ответ в Google Chat.
- Google Chat отображает ответ пользователю в определенном месте.
Эта последовательность повторяется для каждого события взаимодействия в приложении «Чат».
Асинхронные сообщения требуют аутентификации.
Asynchronous messages occur when a Chat app makes a request to the Chat API , which requires authentication and authorization.
Вызывая API чата, приложения чата могут отправлять сообщения в Google Chat или выполнять задачи и получать доступ к данным от имени пользователя. Например, после обнаружения сбоя сервера приложение чата может вызвать API чата, чтобы:
- Create a Chat space dedicated to investigating and fixing the outage.
- Добавляйте пользователей в чат.
- Оставьте сообщение в чате, чтобы подробно описать проблему.
На следующей диаграмме показана асинхронная последовательность сообщений между приложением чата и пространством чата:
- Приложение чата создает сообщение, вызывая API чата с помощью метода
spaces.messages.create, и включает учетные данные пользователя в HTTP-запрос. - Google Chat authenticates the Chat app with service account or user credentials.
- Google Chat renders the app's message to a specified Chat space.
Области действия API чата
Configure the OAuth consent screen and choose scopes to define what information is displayed to users and app reviewers, and register your app so that you can publish it later.
Для определения уровня доступа, предоставляемого вашему приложению, необходимо идентифицировать и объявить области авторизации . Область авторизации — это строка URI OAuth 2.0, содержащая имя приложения Google Workspace, тип данных, к которым оно получает доступ, и уровень доступа.
Неконфиденциальные прицелы
| Scope code | Описание |
|---|---|
https://www.googleapis.com/auth/chat.bot | Приложения Let's Chat позволяют просматривать чаты и отправлять сообщения. Данная область действия поддерживает аутентификацию только приложений с использованием учетных записей служб. Аутентификация с использованием учетных данных пользователей или делегирования полномочий в масштабе домена с помощью данной области действия невозможна. |
Прицелы повышенной чувствительности
| Код области действия | Описание |
|---|---|
https://www.googleapis.com/auth/chat.spaces | Создавайте беседы и пространства, а также просматривайте или редактируйте метаданные (включая настройки истории и доступа) в чате. |
https://www.googleapis.com/auth/chat.spaces.create | Создавайте новые диалоги в чате. |
https://www.googleapis.com/auth/chat.spaces.readonly | Просматривайте чат и пространства в чате. |
https://www.googleapis.com/auth/chat.memberships | View, add, update, and remove members from conversations in Chat. |
https://www.googleapis.com/auth/chat.memberships.app | Add and remove itself from conversations in 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 | View, add, and delete reactions to messages in Chat. |
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 | View and modify last read time for Chat conversations. |
https://www.googleapis.com/auth/chat.users.readstate.readonly | Посмотреть время последнего прочтения сообщений в чате. |
https://www.googleapis.com/auth/chat.admin.spaces.readonly | View chat and spaces owned by the administrator's domain in Chat. |
https://www.googleapis.com/auth/chat.admin.spaces | View or edit chat and spaces owned by the administrator's domain in Chat. |
https://www.googleapis.com/auth/chat.admin.memberships.readonly | View members and managers in conversations owned by the administrator's domain in Chat. |
https://www.googleapis.com/auth/chat.admin.memberships | В чате можно просматривать, добавлять, обновлять и удалять участников и менеджеров в беседах, принадлежащих домену администратора. |
https://www.googleapis.com/auth/chat.app.spaces | Create conversations and spaces and see or update metadata (including history settings and access settings) in Chat as a Chat app. Requires administrator approval . This scope only supports app authentication with service accounts. You can't authenticate with user credentials or with domain-wide delegation using this scope. |
https://www.googleapis.com/auth/chat.app.spaces.readonly | View metadata (including history settings) in Chat as a Chat app. Requires administrator approval . Данная область действия поддерживает аутентификацию только приложений с использованием учетных записей служб. Аутентификация с использованием учетных данных пользователей или делегирования полномочий в масштабе домена с помощью данной области действия невозможна. |
https://www.googleapis.com/auth/chat.app.spaces.create | Create new conversations and spaces in Chat as a Chat app. Requires administrator approval . This scope only supports app authentication with service accounts. You can't authenticate with user credentials or with domain-wide delegation using this scope. |
https://www.googleapis.com/auth/chat.app.memberships | See, add, update, and remove members from conversations and spaces in Chat as a Chat app. Requires administrator approval . This scope only supports app authentication with service accounts. You can't authenticate with user credentials or with domain-wide delegation using this scope. |
https://www.googleapis.com/auth/chat.app.memberships.readonly | See members from conversations and spaces in Chat as a Chat app. Requires administrator approval . This scope only supports app authentication with service accounts. You can't authenticate with user credentials or with domain-wide delegation using this scope. |
https://www.googleapis.com/auth/chat.customemojis | View, create, and delete custom emoji in Chat. |
https://www.googleapis.com/auth/chat.customemojis.readonly | Просматривайте пользовательские эмодзи в чате. |
https://www.googleapis.com/auth/chat.users.spacesettings | Просмотр и обновление настроек пользовательского пространства чата. |
https://www.googleapis.com/auth/chat.users.sections | View, create, update, and delete your sections in Chat; move and list your section items in Chat. |
https://www.googleapis.com/auth/chat.users.sections.readonly | View your sections and their section items in Chat. |
Ограниченные области применения
| Код области действия | Описание |
|---|---|
https://www.googleapis.com/auth/chat.delete | Удаляйте беседы и пространства, а также блокируйте доступ к связанным файлам в чате. |
https://www.googleapis.com/auth/chat.import | Import spaces, messages, and memberships into Chat. For more information, see Authorize Chat apps to import data |
https://www.googleapis.com/auth/chat.messages | View, compose, send, update, and delete messages, and add, view, and delete reactions to messages. |
https://www.googleapis.com/auth/chat.messages.readonly | Просматривайте сообщения и реакции в чате. |
https://www.googleapis.com/auth/chat.app.messages.readonly | View messages and reactions in Chat as a Chat app. Requires administrator approval . This scope only supports app authentication with service accounts. You can't authenticate with user credentials or with domain-wide delegation using this scope. |
https://www.googleapis.com/auth/chat.admin.delete | Delete conversations and spaces owned by the administrator's domain, and remove access to associated files in Chat. |
https://www.googleapis.com/auth/chat.app.delete | Delete conversations and spaces and remove access to associated files in Chat as a Chat app. Requires administrator approval . This scope only supports app authentication with service accounts. You can't authenticate with user credentials or with domain-wide delegation using this scope. |
The scopes in the preceding tables indicate their sensitivity, according to the following definitions:
Неконфиденциальная информация — Эти области действия обеспечивают наименьший объем авторизационного доступа и требуют лишь базовой проверки приложения. Для получения информации об этом требовании см. Шаги по подготовке к проверке .
Конфиденциальные — Эти области доступа предоставляют вашему приложению доступ к данным Google конкретного пользователя после получения от него разрешения. Это требует дополнительной проверки приложения. Для получения информации об этом требовании см. раздел «Шаги для приложений, запрашивающих конфиденциальные области доступа» .
Ограниченный доступ — Эти области доступа предоставляют широкий доступ к данным пользователей Google и требуют прохождения процедуры подтверждения ограниченного доступа. Для получения информации об этом требовании см. Google API Services: Политика в отношении данных пользователей и Дополнительные требования к конкретным областям доступа API . См. также Шаги для приложений, запрашивающих ограниченный доступ .
If your app requires access to any other Google APIs, you can add those scopes as well. For more information about Google API scopes, see Using OAuth 2.0 to Access Google APIs .
To learn more about scopes for Google Workspace APIs, see Configure the OAuth consent screen and choose scopes .
Типы необходимой аутентификации
There are two ways Chat apps can authenticate and authorize with the Chat API:
- Аутентификация пользователя
- Аутентификация пользователя позволяет приложению чата получать доступ к данным пользователя и выполнять действия от его имени. Области действия OAuth определяют разрешенные данные и действия. Если приложение чата не было установлено администратором или ему не было предоставлено делегирование в масштабе домена , то при первом выполнении приложением чата действия от имени пользователя пользователь должен авторизовать приложение чата с помощью экрана согласия OAuth .
- аутентификация приложения
Аутентификация приложения позволяет приложению чата использовать учетные данные сервисной учетной записи и получать доступ к данным и выполнять действия от своего имени. Поскольку приложение чата использует свои собственные учетные данные для доступа к ресурсам и работы с ними, конечным пользователям не нужно подтверждать вызовы API приложения чата, и вы не можете добавить области авторизации OAuth, поддерживающие авторизацию приложения, на экран согласия OAuth.
Two types of OAuth authorization scopes support app authentication:
-
https://www.googleapis.com/auth/chat.bot: Ваше приложение для чата может вызывать методы API Google Chat, поддерживающие эту область авторизации, для создания, обновления, получения, перечисления или удаления ресурсов, к которым оно имеет доступ, например, сообщений в пространствах, куда конечные пользователи добавляют ваше приложение для чата. Ваше приложение для чата может самостоятельно предоставить эту область авторизации, авторизация администратора или конечного пользователя не требуется. -
https://www.googleapis.com/auth/chat.app.*: Использование этих областей действия требует однократного подтверждения администратора. Для получения подтверждения администратора необходимо подготовить учетную запись службы приложения «Чат» для получения подтверждения администратора, создав клиент OAuth, совместимый с Google Workspace Marketplace, и настроив приложение в SDK Google Workspace Marketplace. Эти области действия позволяют вашему приложению «Чат» вызывать определенные методы API Google Chat. Например,chat.app.spaces.createпозволяет приложениям создавать пространства чата.
-
If a method supports both user or app authentication, the Chat API returns different results based on the authentication type that you use:
- With app authentication, the methods only return resources that the Chat app can access.
- With user authentication, the methods only return resources that the user can access.
Например, вызов метода spaces.list() с авторизацией приложения возвращает список пространств, в которых состоит приложение чата. Вызов spaces.list() с авторизацией пользователя возвращает список пространств, в которых состоит пользователь. На практике, в зависимости от архитектуры и возможностей вашего приложения чата, при вызове API чата могут использоваться оба типа аутентификации.
Для асинхронных вызовов API чата
The following table lists the Chat API methods and their supported authorization scopes:
| Метод | Поддерживается аутентификация пользователя | Поддерживается аутентификация приложения | Поддерживаемые области авторизации | |
|---|---|---|---|---|
| Пространства | ||||
| Создайте пространство | With User authentication :
| |||
| Обустройте пространство | — | При аутентификации пользователя :
| ||
| Найдите место | При аутентификации пользователя :
| |||
| Пространства списка | При аутентификации пользователя :
| |||
| Поисковые пространства | — | With User authentication using administrator privileges :
| ||
| Обновить пространство | При аутентификации пользователя :
| |||
| Удалите пробел | При аутентификации пользователя :
| |||
| Завершите процесс импорта пространства. | — | При аутентификации пользователя :
| ||
| Найти личное сообщение | При аутентификации пользователя :
| |||
| Члены | ||||
| Создать участника | При аутентификации пользователя :
| |||
| Стать участником | При аутентификации пользователя :
| |||
| Участники списка | При аутентификации пользователя :
| |||
| Удалить участника | При аутентификации пользователя :
| |||
| Обновить данные участника | При аутентификации пользователя :
| |||
| Сообщения | ||||
| Создать сообщение | При аутентификации пользователя :
| |||
| Получить сообщение | При аутентификации пользователя :
| |||
| Список сообщений | При аутентификации пользователя :
| |||
| Поиск сообщений | — | При аутентификации пользователя :
| ||
| Обновить сообщение | При аутентификации пользователя :
| |||
| Удалить сообщение | При аутентификации пользователя :
| |||
| Закрепить сообщение | — | При аутентификации пользователя :
| ||
| Открепить сообщение | — | При аутентификации пользователя :
| ||
| List pinned messages | — | При аутентификации пользователя :
| ||
| Обновить карточки в сообщении | — | With App authentication :
| ||
| Реакции | ||||
| Создайте реакцию | — | With User authentication :
| ||
| Список реакций | — | При аутентификации пользователя :
| ||
| Delete a reaction | — | При аутентификации пользователя :
| ||
| Пользовательские эмодзи | ||||
| Создайте собственный эмодзи | — | With User authentication :
| ||
| Удалить пользовательский эмодзи | — | With User authentication :
| ||
| Get a custom emoji | — | With User authentication :
| ||
| Список пользовательских эмодзи | — | With User authentication :
| ||
| Media & attachments | ||||
| Upload media as a file attachment | — | При аутентификации пользователя :
| ||
| Скачать медиафайл | With User authentication :
| |||
| Get a message attachment | — | С аутентификацией приложения :
| ||
| User read states | ||||
| Get a user's space read state | — | With User authentication :
| ||
| Update a user's space read state | — | With User authentication :
| ||
| Get a user's thread read state | — | При аутентификации пользователя :
| ||
| User space settings | ||||
| Get a user's space notification setting | — | При аутентификации пользователя :
| ||
| Обновить настройки уведомлений пользователя о состоянии рабочего пространства. | — | With User authentication :
| ||
| Космические события | ||||
| Get space events | — | With User authentication , you must use a scope based on the event type :
| ||
| Список космических событий | — | With User authentication , you must use a scope for each event type included in the request:
| ||
| Разделы | ||||
| Создать раздел | — | При аутентификации пользователя :
| ||
| Delete a section | — | При аутентификации пользователя :
| ||
| Список разделов | — | При аутентификации пользователя :
| ||
| Обновить раздел | — | При аутентификации пользователя :
| ||
| Разместите раздел | — | При аутентификации пользователя :
| ||
| Разделы | ||||
| Переместить элемент раздела | — | При аутентификации пользователя :
| ||
| Список элементов раздела | — | При аутентификации пользователя :
| ||
Для событий взаимодействия в чат-приложении
В таблице ниже перечислены распространенные способы взаимодействия пользователей с чат-приложениями, а также указано, требуется ли аутентификация или поддерживается ли она:
| Сценарий | Аутентификация не требуется | Поддерживается аутентификация пользователя | Поддерживается аутентификация приложения | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Получайте сообщения от: |
| |||||||||||||||
| Отвечать на сообщения: |
| |||||||||||||||
| Отправить новые сообщения: |
| |||||||||||||||
Связанные темы
- Для получения общего обзора аутентификации и авторизации в Google Workspace см. раздел «Узнайте больше об аутентификации и авторизации» .
- Обзор аутентификации и авторизации в Google Cloud см. в разделе «Обзор аутентификации» .
- To learn more about service accounts, see Service accounts .
- Чтобы узнать больше о том, как API Google используют OAuth 2.0, см. раздел «Использование OAuth 2.0 для доступа к API Google» .
- Настройте аутентификацию и авторизацию с использованием учетных данных пользователя или служебной учетной записи .
- Для управления детализированными разрешениями OAuth см. раздел «Управление детализированными разрешениями OAuth для приложений Google Chat» .