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