Security Requirements for WebHook Consumer

[egekorkan]

Given that a WebHook consumer also acts as a server, what are its security scheme requirements? If there is any flexibility on this, the Consumer needs to communicate these with a certain format, maybe a TD with no affordance but only security information?

[egekorkan]

In the call of 01.02.2022, there was a mention that the Consumer would have the security of the Thing. I don't think this is realistic given that a Consumer can be a cloud service and the Thing is something in the local network. They can use the same one but making it mandatory that they are the same seems a bit off to me. Do we have any examples?

[mmccool]

Will discuss in next Security TF call.

[mmccool]

We put a lot of comments related to webhooks under #224 but want to move that discussion here.

To summarize:

• There are some attempts at standardization but none are especially widespread. The OpenID SSF approach is good and complete, but also quite complicated.
• I (the Security TF is still reviewing and will comment here) suggests that we could adopt the approach outlined for Cloud Events in https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/http-webhook.md, with some modifications:
  • just use bearer tokens in headers, but not in query parameters
  • specify that the token should be provided by the Consumer in the subscription message; this token should then be provided by the Thing when it calls webhooks
• The above scheme is not perfect, in particular it does not prevent replay attacks. To fix this we would need to add both timestamps and signatures (to avoid modification of timestamps). This could be done for devices that need extra security particularly if replay would be a problem, e.g. a door lock. In this case JWT could be used for signatures, but the systems should also use mTLS and use appropriate keys for signing.
• This is still a pretty heavy lift, and the above link has many requirements on handshaking, error codes, and so on, but it's what I think should be done.

[benfrancis]

I (the Security TF is still reviewing and will comment here) suggests that we could adopt the approach outlined for Cloud Events in https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/http-webhook.md, with some modifications

I agree that using Bearer tokens in an Authorization header in event requests sent from a Thing to a Consumer is a reasonable solution.

Some observations:

• I note that this document doesn't deal with the subscription mechanism (i.e. how the token is provided to the "client" (Thing) by the "delivery target" (Consumer)), so a payload would need designing for the subscribe operation
• The document also doesn't say what to do when a token expires, which may occur between a subscribe and unsubscribe operation. Presumably the Thing would receive a 401 response from the Consumer when trying to deliver an event and would need to re-authenticate somehow (e.g. using a refresh token).
• It's notable that there's no way to describe Thing to Consumer authentication like this in a Thing Description, this is another area where the profile would have to go beyond what can be described in a Thing Description alone. This kind of thing could potentially be defined as a default in a Webhook protocol binding, but defining a vocabulary to override the default would be tricky since the metadata would need to describe the Consumer, not the Thing.

[benfrancis]

One solution to this problem might be for a Consumer to provide security credentials in the payload of a subscribeevent operation request (as @mmccool suggested above), but following a similar format to that used in a TD.

Example payload:

POST /things/lamp/events/overheated
Host: mythingserver.com
Content-Type: application/json
{
  callbackURI: "http://myConsumer.com/myEventListener",
  security: {
    "scheme": "bearer",
    "in": "header",
    "name": "Authorization"
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
  }
}

As I mentioned above, there's also the issue of what to do if and when a token expires.

[benfrancis]

Another source of inspiration could be the W3C WebSub specification. That specification is a little different because in WebSub all Webhooks are managed by a "hub" which acts as an intermediary between publishers and subscribers. Such hubs may have more resources than some Things and therefore may be able to process more complex cryptography.

Anyway, the approach they use for "authenticated content distribution" is for a subscriber to supply a "secret" in their subscription request which is used by the hub to create an HMAC signature of each event payload, which is then included in a request header of each event notification. Subscribers can verify event notifications by using the shared secret to recompute the signature for a given payload and check that it matches.

As @mmccool notes above, the signing of individual payloads would provide an additional layer of protection when compared with the simple Bearer authentication token approach (by guarding against man-in-the-middle and replay attacks), but would also be more computationally expensive.

Perhaps signing of payloads could be explored as an optional layer of security at the same time as signing Thing Descriptions.