From 31fd256e9617d05967a2feffc0620eca3d4f13a7 Mon Sep 17 00:00:00 2001 From: elf Pavlik Date: Mon, 3 Oct 2022 09:26:16 -0500 Subject: [PATCH 1/2] removed custom webhooks authn --- webhook-subscription-2021.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/webhook-subscription-2021.md b/webhook-subscription-2021.md index b61b6f5..8a72f74 100644 --- a/webhook-subscription-2021.md +++ b/webhook-subscription-2021.md @@ -30,9 +30,7 @@ This document uses terms from the Solid Protocol specification, including "data In addition, the following terms are defined: -**Subscribing Server** -- A server with some HTTP resource that will receive webhook requests from the Pod. For the case of the example, it can also be the server that initiates the subscription. - -**Pod (Private/Public) Key** -- A private public keypair associated with a specific data Pod. +**Subscribing Server** -- A server with some HTTP resource (notifications target) that will receive webhook requests from the Pod. For the case of the example, it can also be the server that initiates the subscription. ### 1.3. Conformance All assertions, diagrams, examples, and notes are non-normative, as are all sections explicitly marked non-normative. Everything else is normative. @@ -132,8 +130,8 @@ The auth server returns the JWKS. If the token is not valid or the user does not have READ access to the resource, the Pod will return 403 to the server client. -#### 6. Receive subscription URL and metadata -The Pod returns a subscription URL to the subscribing server. +#### 6. Receive subscription response +The Pod returns a subscription resopnse the subscribing server. ```http Content-Type: application/ld+json @@ -142,6 +140,7 @@ Content-Type: application/ld+json "@context": "https://www.w3.org/ns/solid/notification/v1", "type": "WebHookSubscription2021", "target": "https://api.liqid.chat/webhook", + "webid": "https://pod.example/notifications/webhook/card.ttl#i", "unsubscribe_endpoint": "https://pod.example/notifications/webhook/subscription/a59e24ba-8231-4b51-b60a-c0e04740f617" } ``` @@ -153,7 +152,7 @@ At this point, the webhook has been successfully registered. #### 7. Action happens on Topic Resource Some action (either an update to the resource or a deletion of that resource) has taken place on the topic resource. -#### 8. Webhook Request (With token signed by the Pod Key) +#### 8. Webhook Request (authorized with WebID from subscription response) A request is made to the subscribing server's registered webhook. ```http @@ -182,7 +181,7 @@ Content-Type: application/ld+json } ``` -The value of `` is a DPoP bound JSON Web Token representing `https://pod.example/webhooks/card.ttl#i`. Both tokens correspond to the authentication method outlined in Solid OIDC. +The value of `` is a DPoP bound JSON Web Token representing `https://pod.example/notifications/webhook/card.ttl#i`. Both tokens correspond to the authentication method outlined in Solid OIDC. `` is a dpop proof containing the claims `{ htu: "https://api.liqid.chat/webhook", htm: "POST" }`. Both tokens correspond to the authentication method outlined in Solid OIDC. @@ -210,6 +209,8 @@ The authenticated user during the subscribe request must have READ access to the The response body of the notification server's subscription url `MUST` include the `target` field, the value of which corresponds to the provided `target` field. +The response body of the notification server's subscription url `MUST` include the `webid` field, the value of which denotes WebID which will be used for the delivery of notifications. + The response body of the notification server's subscription url `MUST` include the `unsubscribe_endpoint` field. The value is a URI that will close the subscription (See Unsubscribe API) ## 4. Webhook API @@ -245,14 +246,10 @@ If a request is received at the unsubscribe endpoint and it does not include an ## 6. Features This section details the additional features built for `WebHookSubscription2021`. -### 6.1 webhook-auth -The `webhook-auth` feature allows subscribing servers to verify that a request came from a certain Pod. - -Pods that implement the `webhook-auth` feature `MUST` create an Access Token and DPoP proof in accordance with the Solid OIDC specification and include those tokens in the headers of all webhook requests. ## Further Considerations - Using DPoP authentication in the webhook request does coincide with the common use case for Solid-OIDC, but it is overkill. There is no need for a security model that has two separate tokens (DPoP Token and the Auth token). Instead, we should consider using one token with the combined features (identity + htm and htu) of the two tokens. - The fact that the Pod allows any URI to be submitted as a `target` might lead to distributed denial of service attacks originating from Pods. A malicious actor could create an app and trick many users to join it. The malicious app would then create a webhook targeting its desired target. It may be a good idea to build in an automated verification process to confirm that the entity sending the subscription request also owns the target webhook endpoint. - The examples in this specification assume that the base domain `https://bob.pod.example` are interchangable with `https://pod.example`. This is not always the case and could lead to security vulnerabilities. - Defining a feature that includes the resource or the delta of the changes in the request are beyond the scope of this document, but it's something that should be considered. - - What is the UUID in the webhook body? \ No newline at end of file + - What is the UUID in the webhook body? From c462051a5a5acfd90d472d561c4aa833d82a7bdd Mon Sep 17 00:00:00 2001 From: elf Pavlik Date: Thu, 1 Dec 2022 07:16:59 -0600 Subject: [PATCH 2/2] mark as version 0.2-rc1 --- webhook-subscription-2021.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/webhook-subscription-2021.md b/webhook-subscription-2021.md index 8a72f74..01c7101 100644 --- a/webhook-subscription-2021.md +++ b/webhook-subscription-2021.md @@ -6,7 +6,8 @@ The [Solid Notification Protocol](https://solid.github.io/notifications/protocol This specification defines a subscription type that applies these patterns to WebHooks. ## Status of This Document -TODO + +Version 0.2-rc2 ## 1. Introduction _This section is non-normative._