4

When building a Conversational Action with the new Actions SDK or Action Builder, you can define a webhook to handle business logic. This webhook then receives fulfillment requests with the following headers, among others:

Google-Actions-API-Version: "3"
Google-Assistant-Signature: "eyJhbGciOiJSUzI1NiIsImtpZC..."

How should that signature be verified? It's a JWT claim, but the key ID with which it was signed does not exist in the GCP account linked with the Action, and is not mentioned in the new Actions SDK documentation or in the Node.js fulfillment library documentation.

Prisoner
  • 49,922
  • 7
  • 53
  • 105
Egal
  • 1,374
  • 12
  • 22

1 Answers1

3

The signature is a JSON Web Token, which is an encoded way of transmitting some assertions that have been signed in a verifiable way. There are libraries that will both decode and verify JWTs. The general steps (some of which you can cache or shortcut) are:

  1. Decode the header to get the kid (key id) and the payload to get the iss (issuer) fields. You'll also want the nbf (not before) and exp (expiration) fields to verify this was set recently and the aud field to verify that it matches your Google Cloud project ID.
  2. Based on the issuer, access the well known openid configuration. Since the issuer is "https://accounts.google.com" you can access this at "https://accounts.google.com/.well-known/openid-configuration"
  3. From the configuration document, you want the jwks_uri field, which is the URL to get the current JWT certificates. For Google, this is probably "https://www.googleapis.com/oauth2/v3/certs"
  4. The certificate document should contain an array of keys. You want a key with the kid that matches the kid from the JWT. Note that these keys change frequently, but as long as you're within the window of the nbf and exp fields from the signature header, the key should exist in the certificate document.
  5. With all this, you can then verify the signature portion of the JWT.
Prisoner
  • 49,922
  • 7
  • 53
  • 105
  • 1
    Didn't know about the well known openid configuration, thanks for the detailed explanation. I also found it in the meantime in the nodejs google-auth library: https://github.com/googleapis/google-auth-library-nodejs/blob/35ef9fef2ad83e08abdcf853b977bf8bb626bd06/src/auth/oauth2client.ts#L1055 – Egal Jul 02 '20 at 15:54
  • Good posts ... a question ... it isn't 100% clear to me ... is the background to this question that a Webhook implementation should perform validation on the signature to prove that it came from who we expect? – Kolban Jan 01 '21 at 17:40
  • Well, it is that "something" should perform validation on the signature to prove it is legitimate, yes. Having that in the webapp is one such place, yes. – Prisoner Jan 01 '21 at 19:09