Аутентификация и авторизация приложений Chat и запросов API Google Chat. (original) (raw)

Аутентификация и авторизация — это механизмы, используемые для проверки личности и доступа к ресурсам соответственно. В этом документе описывается, как работают аутентификация и авторизация для приложений чата и запросов к API чата.

Обзор процесса

На следующей диаграмме показаны основные этапы аутентификации и авторизации для Google Chat:

Основные этапы аутентификации и авторизации в Google Chat.

Рисунок 1. Основные этапы аутентификации и авторизации в Google Chat.

  1. Настройте проект Google Cloud, включите Chat API и настройте приложение чата: В процессе разработки вы создадите проект Google Cloud. В этом проекте вы включите Chat API, настроите приложение чата и установите аутентификацию. Для получения дополнительной информации см. разделы «Разработка в Google Workspace» и «Создание приложения чата» .
  2. Вызов API чата: Когда ваше приложение вызывает API чата, оно отправляет в API чата учетные данные для аутентификации. Если ваше приложение аутентифицируется с помощью сервисной учетной записи, учетные данные отправляются как часть кода вашего приложения. Если вашему приложению требуется вызывать API чата, используя аутентификацию пользователя, которая еще не была предоставлена, оно запрашивает у пользователя вход в систему.
  3. Запрос ресурсов : Ваше приложение запрашивает доступ с областями действия , которые вы указываете при настройке аутентификации.
  4. Запрос согласия: если ваше приложение проходит аутентификацию как пользователь, Google отображает экран согласия OAuth, чтобы пользователь мог решить, предоставлять ли вашему приложению доступ к запрашиваемым данным. Аутентификация с помощью служебной учетной записи не требует согласия пользователя.
  5. Отправка одобренного запроса на доступ к ресурсам: если пользователь соглашается с областями авторизации, ваше приложение объединяет учетные данные и одобренные пользователем области авторизации в запрос. Запрос отправляется на сервер авторизации Google для получения токена доступа.
  6. Google возвращает токен доступа: токен доступа содержит список предоставленных областей действия. Если возвращенный список областей действия более ограничен, чем запрошенные, ваше приложение отключает все функции, ограниченные токеном.
  7. Доступ к запрошенным ресурсам: Ваше приложение использует токен доступа от Google для вызова API чата и доступа к ресурсам API чата.
  8. Получите токен обновления (необязательно): если вашему приложению необходимо получить доступ к API Google Chat после истечения срока действия одного токена доступа, оно может получить токен обновления. Дополнительную информацию см. в разделе «Использование OAuth 2.0 для доступа к API Google» .
  9. Запрос дополнительных ресурсов: Если вашему приложению требуется расширенный доступ, оно запрашивает у пользователя предоставление новых областей действия, что приводит к новому запросу на получение токена доступа (шаги 3-6).

Когда приложения для чата требуют аутентификации

Приложения для чата могут отправлять сообщения в ответ на взаимодействие с пользователем или асинхронно. Они также могут выполнять задачи от имени пользователя, например, создавать чат-пространство или получать список участников чат-пространства.

Приложения для чата не требуют аутентификации для ответа на взаимодействие с пользователем, за исключением случаев, когда приложение для чата обращается к API чата или другому API Google при обработке ответа.

Для отправки асинхронных сообщений или выполнения задач от имени пользователя приложения чата отправляют RESTful-запросы к API чата , которые требуют аутентификации и авторизации.

Ответы на действия пользователя не требуют аутентификации.

Приложениям Google Chat не требуется аутентификация пользователя или самого приложения для чата, чтобы синхронно получать и обрабатывать события взаимодействия .

Приложения Google Chat получают события взаимодействия всякий раз, когда пользователь взаимодействует с приложением чата или вызывает его, включая следующие:

На следующей диаграмме показана последовательность запросов и ответов между пользователем чата и приложением чата:

Для взаимодействия в чате авторизация не требуется.

Рисунок 2. События взаимодействия в чат-приложении не требуют аутентификации.

  1. Пользователь отправляет сообщение в приложение «Чат» в Google Chat.
  2. Google Chat пересылает сообщение в приложение.
  3. Приложение получает сообщение, обрабатывает его и отправляет ответ в Google Chat.
  4. Google Chat отображает ответ пользователю в определенном месте.

Эта последовательность повторяется для каждого события взаимодействия в приложении «Чат».

Асинхронные сообщения требуют аутентификации.

Асинхронные сообщения возникают, когда приложение чата отправляет запрос к API чата , что требует аутентификации и авторизации.

Вызывая API чата, приложения чата могут отправлять сообщения в Google Chat или выполнять задачи и получать доступ к данным от имени пользователя. Например, после обнаружения сбоя сервера приложение чата может вызвать API чата, чтобы:

На следующей диаграмме показана асинхронная последовательность сообщений между приложением чата и пространством чата:

Для асинхронных сообщений требуется аутентификация.

Рисунок 3. Асинхронные сообщения требуют аутентификации.

  1. Приложение чата создает сообщение, вызывая API чата с помощью метода spaces.messages.create , и включает учетные данные пользователя в HTTP-запрос.
  2. Google Chat аутентифицирует приложение чата с помощью учетных данных сервисной учетной записи или пользователя.
  3. 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.readonly Просмотр метаданных (включая настройки истории) в чате как в приложении чата. Требуется одобрение администратора . Данная область действия поддерживает аутентификацию только приложений с использованием учетных записей служб. Аутентификация с использованием учетных данных пользователей или делегирование полномочий в масштабе домена с помощью данной области действия невозможна.
https://www.googleapis.com/auth/chat.app.spaces.create Создавайте новые беседы и пространства в чате как в приложении для чата. Требуется одобрение администратора . Данная область действия поддерживает аутентификацию только приложений с использованием учетных записей служб. Аутентификация с использованием учетных данных пользователей или делегирование полномочий в масштабе домена с помощью данной области действия невозможна.
https://www.googleapis.com/auth/chat.app.memberships Просматривайте, добавляйте, обновляйте и удаляйте участников из бесед и пространств в чате как в приложении для чата. Требуется одобрение администратора . Данная область действия поддерживает аутентификацию только приложений с использованием учетных записей служб. Аутентификация с использованием учетных данных пользователей или делегирование полномочий в масштабе домена с помощью данной области действия невозможна.
https://www.googleapis.com/auth/chat.app.memberships.readonly Просматривайте участников из бесед и пространств в чате как в приложении для чата. Требуется одобрение администратора . Данная область действия поддерживает аутентификацию только приложений с использованием учетных записей служб. Аутентификация с использованием учетных данных пользователей или делегирование полномочий в масштабе домена с помощью данной области действия невозможна.
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 Удаление переписок и пространств, а также ограничение доступа к связанным файлам в чате как в приложении для чата. Требуется одобрение администратора . Данная область действия поддерживает аутентификацию только приложений с использованием учетных записей служб. Аутентификация с использованием учетных данных пользователей или делегирование полномочий в масштабе домена с помощью данной области действия невозможна.

В таблицах выше указаны области их чувствительности в соответствии со следующими определениями:

Если вашему приложению требуется доступ к другим API Google, вы также можете добавить соответствующие области действия. Дополнительную информацию об областях действия API Google см. в разделе «Использование OAuth 2.0 для доступа к API Google» .

Чтобы узнать больше о областях действия API Google Workspace, см. раздел «Настройка экрана согласия OAuth» и выберите «Области действия» .

Типы необходимой аутентификации

Существует два способа аутентификации и авторизации чат-приложений с помощью API чата:

Аутентификация пользователя

Аутентификация пользователя позволяет приложению чата получать доступ к данным пользователя и выполнять действия от его имени. Области действия OAuth определяют разрешенные данные и действия. Если приложение чата не было установлено администратором или ему не было предоставлено делегирование в масштабе домена , то при первом выполнении приложением чата действия от имени пользователя пользователь должен авторизовать приложение чата с помощью экрана согласия OAuth .

аутентификация приложения

Аутентификация приложения позволяет приложению чата использовать учетные данные сервисной учетной записи и получать доступ к данным и выполнять действия от своего имени. Поскольку приложение чата использует свои собственные учетные данные для доступа к ресурсам и работы с ними, конечным пользователям не нужно подтверждать вызовы API приложения чата, и вы не можете добавить области авторизации OAuth, поддерживающие авторизацию приложения, на экран согласия OAuth.

Для аутентификации приложений используются два типа областей авторизации OAuth:

Если метод поддерживает как аутентификацию пользователя, так и аутентификацию приложения, API чата вернет разные результаты в зависимости от используемого типа аутентификации:

Например, вызов метода spaces.list() с авторизацией приложения возвращает список пространств, в которых состоит приложение чата. Вызов spaces.list() с авторизацией пользователя возвращает список пространств, в которых состоит пользователь. На практике, в зависимости от архитектуры и возможностей вашего приложения чата, при вызове API чата могут использоваться оба типа аутентификации.

Для асинхронных вызовов API чата

В таблице ниже перечислены методы API чата и поддерживаемые ими области авторизации:

Метод Поддерживается аутентификация пользователя Поддерживается аутентификация приложения Поддерживаемые области авторизации
Пространства
Создайте пространство При аутентификации пользователя : chat.spaces.create chat.spaces chat.import С аутентификацией приложения и подтверждением администратора : chat.app.spaces.create chat.app.spaces
Обустройте пространство При аутентификации пользователя : chat.spaces.create chat.spaces
Найдите место При аутентификации пользователя : chat.spaces.readonly chat.spaces При аутентификации пользователя с использованием прав администратора : chat.admin.spaces.readonly С аутентификацией приложения : chat.bot С аутентификацией приложения и подтверждением администратора : chat.app.spaces
Пространства списка При аутентификации пользователя : chat.spaces.readonly chat.spaces С аутентификацией приложения : chat.bot
Поисковые пространства При аутентификации пользователя с использованием прав администратора : chat.admin.spaces.readonly
Обновить пространство При аутентификации пользователя : chat.spaces chat.import При аутентификации пользователя с использованием прав администратора : chat.admin.spaces С аутентификацией приложения и подтверждением администратора : chat.app.spaces
Удалите пробел При аутентификации пользователя : chat.delete chat.import При аутентификации пользователя с использованием прав администратора : chat.admin.delete С аутентификацией приложения и подтверждением администратора : chat.app.delete
Завершите процесс импорта пространства. При аутентификации пользователя : chat.import
Найти личное сообщение При аутентификации пользователя : chat.spaces.readonly chat.spaces С аутентификацией приложения : chat.bot
Члены
Создать участника При аутентификации пользователя : chat.memberships chat.memberships.app chat.import При аутентификации пользователя с использованием прав администратора : chat.admin.memberships С аутентификацией приложения и подтверждением администратора : chat.app.memberships
Стать участником При аутентификации пользователя : chat.memberships.readonly chat.memberships С аутентификацией приложения : chat.bot При аутентификации пользователя с использованием прав администратора : chat.admin.memberships.readonly
Участники списка При аутентификации пользователя : chat.memberships.readonly chat.memberships chat.import С аутентификацией приложения : chat.bot При аутентификации пользователя с использованием прав администратора : chat.admin.memberships.readonly
Удалить участника При аутентификации пользователя : chat.memberships chat.memberships.app chat.import При аутентификации пользователя с использованием прав администратора : chat.admin.memberships С аутентификацией приложения и подтверждением администратора : chat.app.memberships
Обновить данные участника При аутентификации пользователя : chat.memberships chat.import При аутентификации пользователя с использованием прав администратора : chat.admin.memberships С аутентификацией приложения и подтверждением администратора : chat.app.memberships
Сообщения
Создать сообщение При аутентификации пользователя : chat.messages.create chat.messages chat.import С аутентификацией приложения : chat.bot
Получить сообщение При аутентификации пользователя : chat.messages.readonly chat.messages С аутентификацией приложения : chat.bot С аутентификацией приложения и подтверждением администратора : chat.app.messages.readonly
Список сообщений При аутентификации пользователя : chat.messages.readonly chat.messages chat.import С аутентификацией приложения и подтверждением администратора : chat.app.messages.readonly
Обновить сообщение При аутентификации пользователя : chat.messages chat.import С аутентификацией приложения : chat.bot
Удалить сообщение При аутентификации пользователя : chat.messages chat.import С аутентификацией приложения : chat.bot
Обновить карточки в сообщении С аутентификацией приложения : chat.bot
Реакции
Создайте реакцию При аутентификации пользователя : chat.messages.reactions.create chat.messages.reactions chat.messages chat.import
Список реакций При аутентификации пользователя : chat.messages.reactions.readonly chat.messages.reactions chat.messages.readonly chat.messages
Удалить реакцию При аутентификации пользователя : chat.messages.reactions chat.messages chat.import
Пользовательские эмодзи
Создайте собственный эмодзи При аутентификации пользователя : chat.customemojis
Удалить пользовательский эмодзи При аутентификации пользователя : chat.customemojis
Получите собственный эмодзи При аутентификации пользователя : chat.customemojis chat.customemojis.readonly
Список пользовательских эмодзи При аутентификации пользователя : chat.customemojis chat.customemojis.readonly
Медиафайлы и вложения
Загрузите медиафайл в качестве вложения. При аутентификации пользователя : chat.messages.create chat.messages chat.import
Скачать медиафайл При аутентификации пользователя : chat.messages.readonly chat.messages С аутентификацией приложения : chat.bot
Прикрепить сообщение С аутентификацией приложения : chat.bot
Состояния чтения пользователя
Получить состояние чтения пользовательского пространства При аутентификации пользователя : chat.users.readstate chat.users.readstate.readonly
Обновить состояние чтения пользовательского пространства При аутентификации пользователя : chat.users.readstate
Получить состояние чтения потока пользователя При аутентификации пользователя : chat.users.readstate chat.users.readstate.readonly
Настройки пользовательского пространства
Получить настройки уведомлений пользователя в личном кабинете При аутентификации пользователя : chat.users.spacesettings
Обновить настройки уведомлений пользователя о состоянии рабочего пространства. При аутентификации пользователя : chat.users.spacesettings
Космические события
Получайте информацию о космических событиях При аутентификации пользователя необходимо использовать область действия, основанную на типе события : Информация о мероприятиях, связанных с сообщениями: chat.messages chat.messages.readonly Информация о мероприятиях, связанных с реакциями: chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly Информация о мероприятиях, связанных с членством: chat.memberships chat.memberships.readonly Информация о мероприятиях, связанных с этим пространством: chat.spaces chat.spaces.readonly
Список космических событий При аутентификации пользователя необходимо использовать область действия (scope) для каждого типа события , включенного в запрос: Информация о мероприятиях, связанных с сообщениями: chat.messages chat.messages.readonly Информация о мероприятиях, связанных с реакциями: chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly Информация о мероприятиях, связанных с членством: chat.memberships chat.memberships.readonly Информация о мероприятиях, связанных с этим пространством: chat.spaces chat.spaces.readonly
Разделы
Создать раздел При аутентификации пользователя : chat.users.sections
Удалить раздел При аутентификации пользователя : chat.users.sections
Список разделов При аутентификации пользователя : chat.users.sections chat.users.sections.readonly
Обновить раздел При аутентификации пользователя : chat.users.sections
Разместите раздел При аутентификации пользователя : chat.users.sections
Разделы
Переместить элемент раздела При аутентификации пользователя : chat.users.sections
Список элементов раздела При аутентификации пользователя : chat.users.sections chat.users.sections.readonly

Для событий взаимодействия в чат-приложении

В таблице ниже перечислены распространенные способы взаимодействия пользователей с чат-приложениями, а также указано, требуется ли аутентификация или поддерживается ли она:

Сценарий Аутентификация не требуется Поддерживается аутентификация пользователя Поддерживается аутентификация приложения
Получайте сообщения от: События взаимодействия в чат-приложении — — Обратные вызовы в Apps Script — — Google Cloud Pub/Sub — —
Отвечать на сообщения: Синхронно, используя событие взаимодействия в чат-приложении. — — Синхронно, используя возвращаемое значение функции обратного вызова Apps Script. — —
Отправить новые сообщения: С входящими веб-хуками — —