Skip to content

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:

  1. This token is sent in plain text
  2. 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:

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 ❤️. We can pick up the work from where they left off.

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

  1. Literally any webhook ever.

Feature checklist

Make sure these are completed before closing the issue, with a link to the relevant commit.

Edited by 🤖 GitLab Bot 🤖