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

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

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

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

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

  1. Настройте проект Google Cloud, включите Chat API и настройте приложение Chat. Во время разработки вы создаете проект Google Cloud. В проекте Google Cloud вы включаете Chat API, настраиваете приложение Chat и настраиваете аутентификацию. Дополнительную информацию см. в разделах «Разработка в Google Workspace» и «Создание приложения Chat» .

  2. Вызов API чата. Когда ваше приложение вызывает API чата, оно отправляет учетные данные для аутентификации в API чата. Если ваше приложение проверяет подлинность с помощью учетной записи службы, учетные данные отправляются как часть кода вашего приложения. Если ваше приложение требует вызова Chat API с использованием аутентификации пользователя, которая еще не предоставлена, оно предлагает пользователю войти в систему.

  3. Запросить ресурсы . Ваше приложение запрашивает доступ к областям , которые вы указываете при настройке аутентификации.

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

  5. Отправка утвержденного запроса на ресурсы. Если пользователь соглашается на области авторизации, ваше приложение объединяет учетные данные и утвержденные пользователем области в запрос. Запрос отправляется на сервер авторизации Google для получения токена доступа.

  6. Google возвращает токен доступа: токен доступа содержит список предоставленных областей. Если возвращаемый список областей более ограничен, чем запрошенные области, ваше приложение отключает все функции, ограниченные токеном.

  7. Доступ к запрашиваемым ресурсам. Ваше приложение использует токен доступа от Google для вызова Chat API и доступа к ресурсам Chat API.

  8. Получите токен обновления (необязательно). Если вашему приложению необходим доступ к API Google Chat по истечении срока действия одного токена доступа, оно может получить токен обновления. Дополнительную информацию см. в разделе Использование OAuth 2.0 для доступа к API Google .

  9. Запросите дополнительные ресурсы. Если вашему приложению требуется больше доступа, оно просит пользователя предоставить новые области, в результате чего отправляется новый запрос на получение токена доступа (шаги 3–6).

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

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

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

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

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

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

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

  • Пользователь отправляет сообщение в приложение чата.
  • Пользователь @упоминает приложение Chat.
  • Пользователь вызывает одну из косых команд приложения Chat.

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

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

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

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

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

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

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

  • Создайте чат, посвященный расследованию и устранению сбоев.
  • Добавляйте людей в пространство чата.
  • Опубликуйте сообщение в чате, чтобы подробно рассказать об отключении электроэнергии.

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

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

  1. Приложение Chat создает сообщение, вызывая Chat API с помощью метода spaces.messages.create , и включает учетные данные пользователя в HTTP-запрос.
  2. Google Chat проверяет подлинность приложения Chat с помощью учетной записи службы или учетных данных пользователя.
  3. Google Chat отображает сообщение приложения в указанном пространстве чата.

Области API чата

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

Чтобы определить уровень доступа, предоставленный вашему приложению, вам необходимо определить и объявить области авторизации . Область авторизации – это строка URI OAuth 2.0, содержащая имя приложения Google Workspace, тип данных, к которым оно обращается, и уровень доступа.

Нечувствительные области

Код области действия Описание
https://www.googleapis.com/auth/chat.bot

Область действия 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.delete Удалите разговоры и группы, а также закройте доступ к связанным файлам в чате.
https://www.googleapis.com/auth/chat.import Импортируйте группы, сообщения и членство в Chat. Дополнительную информацию см. в разделе Разрешить приложениям чата импортировать данные.
https://www.googleapis.com/auth/chat.messages Просматривайте, составляйте, отправляйте, обновляйте и удаляйте сообщения, а также добавляйте, просматривайте и удаляйте реакции на сообщения.
https://www.googleapis.com/auth/chat.messages.readonly Просматривайте сообщения и реакции в чате.

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

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

Дополнительные сведения об областях действия API Google Workspace см. в разделе Настройка экрана согласия OAuth и выбор областей .

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

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

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

При авторизации приложения приложение Chat обращается к API как приложение, используя учетные данные сервисной учетной записи. Для авторизации приложения всегда используется область авторизации chat.bot .

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

Решая, какой тип учетных данных использовать для конкретного запроса API, имейте в виду, что некоторые методы API поддерживают только определенный тип учетных данных. Если метод API поддерживает оба учетных данных, тип учетных данных, используемых в вызове, влияет на возвращаемый результат:

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

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

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

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

Метод Поддерживается аутентификация пользователя Поддерживается аутентификация приложения Поддерживаемые области авторизации
Пространства
Создайте пространство С аутентификацией пользователя :
  • chat.spaces.create
  • chat.spaces
  • chat.import
Настроить пространство С аутентификацией пользователя :
  • chat.spaces.create
  • chat.spaces
Получите место С аутентификацией пользователя :
  • chat.spaces.readonly
  • chat.spaces
С аутентификацией приложения :
  • chat.bot
Список пространств С аутентификацией пользователя :
  • chat.spaces.readonly
  • chat.spaces
С аутентификацией приложения :
  • chat.bot
Обновить пространство С аутентификацией пользователя :
  • chat.spaces
  • chat.import
Удалить пространство С аутентификацией пользователя :
  • chat.delete
  • chat.import
Завершите процесс импорта пространства С аутентификацией пользователя :
  • chat.import
Найти прямое сообщение С аутентификацией пользователя :
  • chat.spaces.readonly
  • chat.spaces
С аутентификацией приложения :
  • chat.bot
Члены
Создать участника С аутентификацией пользователя :
  • chat.memberships
  • chat.memberships.app
  • chat.import
Получить члена С аутентификацией пользователя :
  • chat.memberships.readonly
  • chat.memberships
С аутентификацией приложения :
  • chat.bot
Список участников С аутентификацией пользователя :
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
С аутентификацией приложения :
  • chat.bot
Удалить участника С аутентификацией пользователя :
  • chat.memberships
  • chat.memberships.app
  • chat.import
Сообщения
Создать сообщение С аутентификацией пользователя :
  • chat.messages.create
  • chat.messages
  • chat.import
С аутентификацией приложения :
  • chat.bot
Получить сообщение С аутентификацией пользователя :
  • chat.messages.readonly
  • chat.messages
С аутентификацией приложения :
  • chat.bot
Список сообщений С аутентификацией пользователя :
  • chat.messages.readonly
  • chat.messages
  • chat.import
Обновить сообщение С аутентификацией пользователя :
  • chat.messages
  • chat.import
С аутентификацией приложения :
  • chat.bot
Удалить сообщение С аутентификацией пользователя :
  • chat.messages
  • chat.import
С аутентификацией приложения :
  • 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.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

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

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

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