Как проверить запросы от Google Chat

В этом разделе рассказывается, как проверить, что запросы к конечной точке приложений Google Chat, созданных на основе конечных точек HTTP, поступают из Chat.

Чтобы отправлять события взаимодействия в конечную точку приложения Chat, Google выполняет HTTPS-запросы к вашему сервису. Чтобы подтвердить, что запрос отправлен Google, Chat включает подписанный Google токен идентификатора OpenID Connect (OIDC) в качестве токена на предъявителя в заголовке Authorization каждого HTTPS-запроса (а также в поле authorizationEventObject.systemIdToken тела запроса). Пример:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

Строка AbCdEf123456 в приведенном выше примере – это токен авторизации носителя. Этот криптографический токен подписывается уникальным аккаунтом сервиса для каждого проекта приложения Chat (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com), а в поле audience задается URL конечной точки HTTP, настроенный для приложения Chat при его конфигурации.

Вы можете скопировать адрес электронной почты сервисного аккаунта приложения Chat из раздела Настройки подключения на вкладке Конфигурация API Chat в консоли Google Cloud:

  1. В консоли Google Cloud нажмите Меню > API и сервисы > Включенные API и сервисы > Google Chat API > Конфигурация:

    Перейти к настройке Google Chat API

  2. В разделе Интерактивные функции > Настройки подключения скопируйте адрес электронной почты сервисного аккаунта (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com).

Если вы реализовали приложение Chat с помощью функций Cloud Run или Cloud Run, Cloud IAM автоматически проверяет токены, когда вы предоставляете сервисному аккаунту приложения Chat роль Cloud Run Invoker (roles/run.invoker). Если в вашем приложении реализован собственный HTTP-сервер, вы можете проверить токен носителя с помощью клиентской библиотеки API Google с открытым исходным кодом:

Если токен не проходит проверку в приложении Chat, ваш сервис должен ответить на запрос кодом ответа HTTPS 401 (Unauthorized).

Как аутентифицировать запросы с помощью функций Cloud Run

Если логика функции реализована с помощью функций Cloud Run или Cloud Run, убедитесь, что URL конечных точек HTTP, настроенные в разделе Триггеры в настройках подключения приложения Chat, соответствуют URL конечной точки функции Cloud Run.

Затем авторизуйте сервисный аккаунт приложения Chat (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com, скопированный из раздела Настройки подключения на вкладке Настройки Chat API) в качестве вызывающего объекта, выполнив следующие действия:

Консоль

После развертывания функции или сервиса в Google Cloud:

  1. В консоли Google Cloud перейдите на страницу Cloud Run:

    Перейти в Cloud Run

  2. В списке сервисов Cloud Run установите флажок рядом с функцией получателя. (не нажимайте на саму функцию).

  3. В верхней части экрана нажмите Разрешения. Откроется панель Разрешения.

  4. Нажмите Добавить субъекта.

  5. В поле Новые субъекты введите адрес электронной почты сервисного аккаунта приложения Chat (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com).

  6. В меню Выберите роль выберите роль Cloud Run.

    Вызывающий Cloud Run.

  7. Нажмите Сохранить.

gcloud

Используйте команду gcloud functions add-invoker-policy-binding:

gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \
  --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-gsuiteaddons.iam.gserviceaccount.com'

Замените следующее:

  • RECEIVING_FUNCTION – название функции приложения Chat.
  • PROJECT_NUMBER – номер проекта из адреса электронной почты сервисного аккаунта приложения Chat.

Как аутентифицировать HTTP-запросы с помощью токена идентификатора

Для конечных точек HTTP токен авторизации носителя в запросе представляет собой токен идентификатора OpenID Connect (OIDC), подписанный Google. В поле email указан адрес электронной почты сервисного аккаунта приложения Chat (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com), а в поле audience – URL конечной точки HTTP, настроенной для получения запроса. Например, если настроенная конечная точка приложения Chat – https://example.com/app/, то поле audience в токене идентификатора будет иметь значение https://example.com/app/.

Этот способ аутентификации рекомендуется, если конечная точка HTTP не размещена в сервисе, поддерживающем аутентификацию на основе IAM (например, Cloud Run).

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

Java

java/chat/secured-app/src/main/java/com/google/chat/app/secured/App.java
/**
 * Determine whether a Google Workspace add-on request is legitimate.
 * 
 * @param event Event sent from Google Workspace add-on
 * @param authorization Authorization header from the request
 * @return {boolean} Whether the request is legitimate
 */
private boolean verifyAddOnRequest(JsonNode event, String authorization) throws Exception {
  JsonFactory factory = JacksonFactory.getDefaultInstance();

  GoogleIdTokenVerifier verifier =
    new GoogleIdTokenVerifier.Builder(new ApacheHttpTransport(), factory)
      .setAudience(Collections.singletonList(HTTP_ENDPOINT))
      .build();

  String bearer = authorization.substring("Bearer ".length(), authorization.length());
  GoogleIdToken idToken = GoogleIdToken.parse(factory, bearer);
  return idToken != null
    && verifier.verify(idToken)
    && idToken.getPayload().getEmailVerified()
    && idToken.getPayload().getEmail().equals(SERVICE_ACCOUNT_EMAIL);
}

Python

python/chat/secured-app/main.py
def verifyAddOnRequest() -> bool:
  """Determine whether a Google Workspace add-on request is legitimate.

  Args:
    request: Request sent from Google Workspace add-on

  Returns:
    Whether the request is legitimate
  """
  try:
    bearer = request.headers.get('Authorization')[len("Bearer "):]
    token = id_token.verify_oauth2_token(bearer, requests.Request(), HTTP_ENDPOINT)
    return token['email'] == SERVICE_ACCOUNT_EMAIL

  except:
    return False

Node.js

node/chat/secured-app/index.js
/**
 * Determine whether a Google Workspace add-on request is legitimate.
 * 
 * @param {Object} req Request sent from Google Workspace add-on
 * @return {boolean} Whether the request is legitimate
 */
async function verifyAddOnRequest(req) {
  try {
    const authorization = req.headers.authorization;
    const idToken = authorization.substring('Bearer '.length, authorization.length);
    const ticket = await new OAuth2Client().verifyIdToken({idToken, audience: HTTP_ENDPOINT});
    return ticket.getPayload().email_verified
        && ticket.getPayload().email === SERVICE_ACCOUNT_EMAIL;
  } catch (unused) {
    return false;
  }
}

Приложения для Chat, которые не являются дополнениями: проверка запросов из Google Chat

Следующая документация относится к приложениям Chat, которые не являются дополнениями Google Workspace. Чтобы перенести приложение Chat, которое не является дополнением, ознакомьтесь со статьей Как преобразовать приложение Google Chat в дополнение Google Workspace.

Для приложений Chat, которые не являются дополнениями, настроенными с помощью URL конечной точки HTTP в разделе Настройки подключения, тип токена носителя и значение поля audience зависят от типа аудитории аутентификации, выбранного при настройке приложения Chat, а запросы подписываются общим сервисным аккаунтом chat@system.gserviceaccount.com.

Как аутентифицировать запросы с помощью функций Cloud Run (для приложений Chat, которые не являются дополнениями)

Если логика функции реализована с помощью функций Cloud Run, в поле Аудитория аутентификации настроек подключения приложения Chat необходимо выбрать URL конечной точки HTTP и убедиться, что URL конечной точки HTTP в конфигурации соответствует URL конечной точки функции Cloud Run.

Затем вам нужно авторизовать сервисный аккаунт Google Chat chat@system.gserviceaccount.com в качестве вызывающего объекта, выполнив следующие действия:

Консоль

После развертывания функции или сервиса в Google Cloud:

  1. В консоли Google Cloud перейдите на страницу Cloud Run:

    Перейти в Cloud Run

  2. В списке сервисов Cloud Run установите флажок рядом с функцией получателя. (не нажимайте на саму функцию).

  3. В верхней части экрана нажмите Разрешения. Откроется панель Разрешения.

  4. Нажмите Добавить субъекта.

  5. В поле Новые субъекты введите chat@system.gserviceaccount.com.

  6. В меню Выберите роль выберите роль Cloud Run.

    Вызывающий Cloud Run.

  7. Нажмите Сохранить.

gcloud

Используйте команду gcloud functions add-invoker-policy-binding:

gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \
  --member='serviceAccount:chat@system.gserviceaccount.com'

Замените RECEIVING_FUNCTION названием функции приложения Chat.

Как аутентифицировать HTTP-запросы с помощью токена идентификатора (для приложений Chat, которые не являются дополнениями)

Если в поле Аудитория аутентификации настройки подключения приложения Chat, которое не является дополнением, задано значение URL конечной точки HTTP, токен авторизации носителя в запросе представляет собой токен идентификатора OpenID Connect (OIDC), подписанный Google. В поле email задано значение chat@system.gserviceaccount.com. В поле Аудитория аутентификации указан URL, который вы настроили в Google Chat для отправки запросов в приложение для Chat, не являющееся дополнением. Например, если настроенная конечная точка приложения Chat – https://example.com/app/, то поле Аудитория аутентификации в токене идентификатора будет иметь значение https://example.com/app/.

В примерах ниже показано, как с помощью клиентской библиотеки Google OAuth проверить, что токен на предъявителя был выдан Google Chat и предназначен для вашего приложения Chat, которое не является дополнением.

Java

java/basic-app/src/main/java/com/google/chat/app/basic/App.java
String CHAT_ISSUER = "chat@system.gserviceaccount.com";
JsonFactory factory = JacksonFactory.getDefaultInstance();

GoogleIdTokenVerifier verifier =
    new GoogleIdTokenVerifier.Builder(new ApacheHttpTransport(), factory)
        .setAudience(Collections.singletonList(AUDIENCE))
        .build();

GoogleIdToken idToken = GoogleIdToken.parse(factory, bearer);
return idToken != null
    && verifier.verify(idToken)
    && idToken.getPayload().getEmailVerified()
    && idToken.getPayload().getEmail().equals(CHAT_ISSUER);

Python

python/basic-app/main.py
# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

try:
    # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
    request = requests.Request()
    token = id_token.verify_oauth2_token(bearer, request, AUDIENCE)
    return token['email'] == CHAT_ISSUER

except:
    return False

Node.js

node/basic-app/index.js
// Bearer Tokens received by apps will always specify this issuer.
const chatIssuer = 'chat@system.gserviceaccount.com';

// Verify valid token, signed by chatIssuer, intended for a third party.
try {
  const ticket = await client.verifyIdToken({
    idToken: bearer,
    audience: audience
  });
  return ticket.getPayload().email_verified
      && ticket.getPayload().email === chatIssuer;
} catch (unused) {
  return false;
}

Аутентификация запросов с помощью JWT номера проекта (для приложений Chat, которые не являются дополнениями)

Если в поле Аудитория аутентификации настройки подключения приложения Chat, которое не является дополнением, задано значение Project Number, то токен авторизации носителя в запросе представляет собой JSON Web Token (JWT) с самозаверяющей подписью, выпущенный и подписанный chat@system.gserviceaccount.com. Поле audience содержит номер облачного проекта Google Cloud, который вы использовали для создания приложения Chat, не являющегося дополнением. Например, если номер облачного проекта для приложения Chat – 1234567890, то поле audience в JWT будет иметь значение 1234567890.

В приведенных ниже примерах показано, как проверить, что токен был выдан Google Chat и предназначен для вашего проекта, с помощью клиентской библиотеки Google OAuth.

Java

java/basic-app/src/main/java/com/google/chat/app/basic/App.java
String CHAT_ISSUER = "chat@system.gserviceaccount.com";
JsonFactory factory = JacksonFactory.getDefaultInstance();

GooglePublicKeysManager keyManagerBuilder =
    new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory)
        .setPublicCertsEncodedUrl(
            "https://www.googleapis.com/service_accounts/v1/metadata/x509/" + CHAT_ISSUER)
        .build();

GoogleIdTokenVerifier verifier =
    new GoogleIdTokenVerifier.Builder(keyManagerBuilder).setIssuer(CHAT_ISSUER).build();

GoogleIdToken idToken = GoogleIdToken.parse(factory, bearer);
return idToken != null
    && verifier.verify(idToken)
    && idToken.verifyAudience(Collections.singletonList(AUDIENCE))
    && idToken.verifyIssuer(CHAT_ISSUER);

Python

python/basic-app/main.py
# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

try:
    # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
    request = requests.Request()
    certs_url = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/' + CHAT_ISSUER
    token = id_token.verify_token(bearer, request, AUDIENCE, certs_url)
    return token['iss'] == CHAT_ISSUER

except:
    return False

Node.js

node/basic-app/index.js
// Bearer Tokens received by apps will always specify this issuer.
const chatIssuer = 'chat@system.gserviceaccount.com';

// Verify valid token, signed by CHAT_ISSUER, intended for a third party.
try {
  const response = await fetch('https://www.googleapis.com/service_accounts/v1/metadata/x509/' + chatIssuer);
  const certs = await response.json();
  await client.verifySignedJwtWithCertsAsync(
    bearer, certs, audience, [chatIssuer]);
  return true;
} catch (unused) {
  return false;
}