Add config for Webhook Signature

[robotdan]

Add config for Webhook Signature

Description

The smart folks over at ngrok have put together a bunch of great information on webhooks, best practices, and reviewed a bunch of existing webhook producers to identify common behaviors.

Solution

Things we should consider:

• Adding some sort of signature to the request header using HMAC or an asymmetric key
  • https://webhooks.fyi/security/hmac
• Support for key rotation by configuring one to many keys and appending all signatures to the request.
  • https://webhooks.fyi/ops-experience/key-rotation

Additional context

• https://webhooks.fyi/

Once this is complete, submit a PR to add our name to this list:

• https://webhooks.fyi/docs/webhook-directory

Related

• https://github.com/FusionAuth/fusionauth-issues/issues/1543

Community guidelines

All issues filed in this repository must abide by the FusionAuth community guidelines.

How to vote

Please give us a thumbs up or thumbs down as a reaction to help us prioritize this feature. Feel free to comment if you have a particular need or comment on how this feature should work.

Documentation

• [x] Document webhook.signatureConfiguration.enabled and webhook.signatureConfiguration.signingKeyId fields on API
• [x] Document new fields in admin UI
• [x] Document webhook signatures mechanisms, headers, and provide sample code in new doc page under Events & Webhooks
• [x] Update screenshots for admin UI (wait for other webhook features to be merged)
• [x] Add webhook.signatureConfiguration.signingKeyId to Key Rotation page

Release Notes

Add support for signing webhook events with a SHA-256 hash function. This feature will allow consumers of FusionAuth events to verify the message body has not been modified. The signature is contained in a JWT and will be sent using an HTTP request header named X-FusionAuth-Signature-JWT. You may use existing JWT verification strategies including consuming the public key from the JWKS endpoint. ** See the link:/docs/v1/tech/events-webhooks/signing[Signing Webhooks] and link:/docs/v1/tech/apis/webhooks[Webhooks APIs] for signing and verification details.

[attilah]

I was wondering about this specific feature reading through the documentation and did not find it, now happy to see it coming in the next version.

For webhooks it is pretty common to create a HMAC-SHA256 or HMAC-SHA384 or HMAC-SHA512 for the payload and include a timestamp and option to include sensitive headers in the hash as it is summed up at webhooks.fyi.

Configuration options I can think of:

• Hashing algorithm
• Shared Secrets - could be rotated while the old ones have to be available for already sent out webhooks to check against validity, these shared secrets should be available through API to sync in other systems, also sending out a webhook when these are mutated in any way would be useful to trigger a sync?
• HTTP Headers to include in hash
• HTTP Header name for Signature in webhook request
• HTTP Header name for Timestamp in webhook request

Have a tenant level global configuration and overrides at webhook level would be a good option, or have "named configurations" that could be assigned with a simple selection per webhook.

Beside this, JWT based security would be a useful and secure feature: https://webhooks.fyi/security/jwt-jwk-oauth2

[mooreds]

@attilah FYI, pinged the engineer working on this and it is currently in code review.

[attilah]

Thanks for the update @mooreds!

[mooreds]

Actually, I spoke to soon. It is in design review, not code review. Sorry bout that.

[mooreds]

@attilah there's some internal discussion and thought you might weigh in. Can you think of any reason you might want to be able to have webhook messages signed by an RSA/ECC key (instead of HMAC)?

Or will HMAC suit your needs?

[robotdan]

Internal:

• https://github.com/FusionAuth/fusionauth-app/pull/327