Verify requests from Google Chat

For Google Chat apps built on HTTP endpoints, this section explains how to verify that the requests to your endpoint come from Chat.

To dispatch interaction events to your Chat app's endpoint, Google makes requests to your service. To verify that the request is coming from Google, Chat includes a bearer token in the Authorization header of every HTTPS request to your endpoint. For example:

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

The string AbCdEf123456 in the preceding example is the bearer authorization token. This is a cryptographic token produced by Google. The type of the bearer token and the value of the audience field depend on the type of authentication audience you selected when configuring the Chat app.

If you've implemented your Chat app using Cloud Functions or Cloud Run, Cloud IAM handles token verification automatically. You just need to add the Google Chat service account as an authorized invoker. If your app implements its own HTTP server, you can verify your bearer token using an open source Google API client library:

• Java: https://github.com/google/google-api-java-client
• Python: https://github.com/google/google-api-python-client
• Node.js: https://github.com/google/google-api-nodejs-client
• .NET: https://github.com/google/google-api-dotnet-client

If the token doesn't verify for the Chat app, your service should respond to the request with an HTTPS response code 401 (Unauthorized).

Authenticate requests using Cloud Functions or Cloud Run

If your function logic is implemented using Cloud Functions or Cloud Run, you must select App URL in the Authentication Audience field of the Chat app connection setting and make sure that the app URL in the configuration corresponds to the URL of the Cloud Function or Cloud Run endpoint.

Then, you need to authorize the Google Chat service account chat@system.gserviceaccount.com as an invoker.

The following steps shows how to use Cloud Functions (1st gen):

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

The following steps shows how to use Cloud Functions (2nd gen) or Cloud Run services:

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

Authenticate requests with an App URL ID Token

If the Authentication Audience field of the Chat app connection setting is set to App URL, the bearer authorization token in the request is a Google-signed OpenID Connect (OIDC) ID token. The email field is set to chat@system.gserviceaccount.com. The audience field is set to the URL you configured Google Chat to send requests to your Chat app. For example, if the configured endpoint of your Chat app is https://example.com/app/, then the audience field in the ID token is https://example.com/app/.

The following samples show how to verify that the bearer token was issued by Google Chat and targeted at your app using the Google OAuth client library.

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);

# 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

// 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;
}

Authenticate requests with a Project Number JWT

If the Authentication Audience field of the Chat app connection setting is set to Project Number, the bearer authorization token in the request is a self-signed JSON Web Token (JWT), issued and signed by chat@system.gserviceaccount.com. The audience field is set to the Google Cloud project number that you used to build your Chat app. For example, if your Chat app's Cloud project number is 1234567890, then the audience field in the JWT is 1234567890.

The following samples show how to verify that the bearer token was issued by Google Chat and targeted at your project using the Google OAuth client library.

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);

# 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

// 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;
}

Related topics

• For an overview of authentication and authorization in Google Workspace, see Learn about authentication and authorization.
• For an overview of authentication and authorization in Chat, see Authentication overview.
• Set up authentication and authorization with user credentials or a service account.