Webhook Secret Token with HMAC Digest
Description
Currently, when creating a webhook you have the option to set a value that will be sent in the X-Gitlab-Token
HTTP Header.
This is meant for validation that the request did actually come from GitLab.
But, this security feature is very poorly implemented for a two reasons:
- This token is sent in plain text
- No way to verify that the payload is valid and came from GitLab.
This should function more like GitHub's version, where that token (the hook secret) is used as the key for an HMAC SHA1 hex digest, which is then sent as an HTTP Header.
You can then compute your own hash of the payload using the secret that it should be, and compare it to the one sent in the header.
However, with GitLab (as said before), you can not do this, the best that you can do is check the plain text header... Not great.
Some examples of other services that sign their requests:
- Stripe https://stripe.com/docs/webhooks/signatures.
- Slack https://api.slack.com/authentication/verifying-requests-from-slack
Proposal
- Add an additional field when creating a webhook, this field should be explicitly labeled as the key for the hash of the payload. (a new field is needed to ensure backwards compatibility with existing webhooks). This field should be absolutely secret, like a password (even when editing an endpoint).
- When sending a payload to an endpoint, add an additional HTTP Header
X-Gitlab-Signature
, this should contain a HMAC hex digest of the payload, where the field previously mentioned is the key)
If no secret is given, then the key for the X-Gitlab-Signature
digest should be blank, which means the contents of the header is just HMAC digest of the payload.
Technical Proposal
@van.m.anderson
worked on a merge request that was very close to implementing the feature Draft: POC for HMAC webhook signing (!163102 - closed). Thank you Van
The remaining work in that MR is outlined here !163102 (comment 2085734123) which is to split the backend and frontend implementations and then add test coverage.
Links / references
GitLab's Documentation on Webhooks
GitLab's "Secret Token" Documentation
GitHub's Documentation on Webhooks
Documentation blurb
Overview
This feature proposal would allow for more secure endpoints since users could verify that they payload is authentic and actually came from a GitLab server.
This would solve a security flaw in GitLabs current webhook implementation that allows for easy spoofing of requests that could potentially be damaging.
Use cases
- Literally any webhook ever.
Feature checklist
Make sure these are completed before closing the issue, with a link to the relevant commit.
- Feature assurance
- Documentation
- Added to features.yml