From 8ee700939bf1802f04e364b185a73cc0e03a7515 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 26 Aug 2024 12:53:11 +0200 Subject: [PATCH 1/8] OAuth code as alternative to sharedSecret This would allow for some more modern security best practices like pre-registering clients and making the access token short-lived and client-bound --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9e4437d7..1b0b0b49 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,11 @@ In response to a share creation, the receiving server MAY send back a [notificat ### Share Access To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property: -* If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. +* If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. +If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. +Othewise, if `protocol.webdav.code` and `protocol.webdav.token_endpoint` are not empty, the receiver SHOULD call the token endpoint to exchange +the code for a short-lived access token, using an [Access Token Request](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3) +like in the OAuth 2.0 Authorization Code Flow, and then use that OAuth access token to access the remote share. * If `protocol.name` = `webdav`, the receiver SHOULD inspect the `protocol.options` property. If it contains a `sharedSecret`, as in the [legacy example](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1shares/post), then the receiver SHOULD make a HTTP PROPFIND request to `https://:@`, where `` is the remote server, and `` is obtained by querying the [Discovery](#discovery) endpoint at the remote server and getting `resourceTypes[0].protocols.webdav`. Note that this access method is _deprecated_ and may be removed in a future release of the Protocol. From 11160b19178700e76b70081e75d62c9572657c4d Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 26 Aug 2024 12:55:03 +0200 Subject: [PATCH 2/8] whitespace --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 1b0b0b49..efc0cdfd 100644 --- a/README.md +++ b/README.md @@ -49,8 +49,7 @@ In response to a share creation, the receiving server MAY send back a [notificat ### Share Access To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property: -* If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. -If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. +* If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. Othewise, if `protocol.webdav.code` and `protocol.webdav.token_endpoint` are not empty, the receiver SHOULD call the token endpoint to exchange the code for a short-lived access token, using an [Access Token Request](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3) like in the OAuth 2.0 Authorization Code Flow, and then use that OAuth access token to access the remote share. From edde0b90d851fe29848cbb0e904d7ff3b6187311 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Mon, 26 Aug 2024 12:55:44 +0200 Subject: [PATCH 3/8] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index efc0cdfd..af097448 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ In response to a share creation, the receiving server MAY send back a [notificat To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property: * If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. -Othewise, if `protocol.webdav.code` and `protocol.webdav.token_endpoint` are not empty, the receiver SHOULD call the token endpoint to exchange +Otherwise, if `protocol.webdav.code` and `protocol.webdav.token_endpoint` are not empty, the receiver SHOULD call the token endpoint to exchange the code for a short-lived access token, using an [Access Token Request](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3) like in the OAuth 2.0 Authorization Code Flow, and then use that OAuth access token to access the remote share. From 36a3e15bf79a6da24e7fd77288c7d6600a7a9302 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 27 Aug 2024 09:23:20 +0200 Subject: [PATCH 4/8] GNAP instead of OAuth 2.0 Authorization Code flow GNAP is more appropriate here because it makes way less assumptions about the interaction (in particular it doesn't assume the use of browser redirects) --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index af097448..138c8102 100644 --- a/README.md +++ b/README.md @@ -50,9 +50,9 @@ In response to a share creation, the receiving server MAY send back a [notificat To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property: * If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. -Otherwise, if `protocol.webdav.code` and `protocol.webdav.token_endpoint` are not empty, the receiver SHOULD call the token endpoint to exchange -the code for a short-lived access token, using an [Access Token Request](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3) -like in the OAuth 2.0 Authorization Code Flow, and then use that OAuth access token to access the remote share. +Otherwise, if `protocol.webdav.nonce` and `protocol.webdav.gnap_as_uri` are not empty, the receiver SHOULD call the token endpoint to exchange +the nonce for a short-lived access token, using [GNAP](https://datatracker.ietf.org/doc/draft-ietf-gnap-core-protocol/), +and then use that GNAP access token to access the remote share. * If `protocol.name` = `webdav`, the receiver SHOULD inspect the `protocol.options` property. If it contains a `sharedSecret`, as in the [legacy example](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1shares/post), then the receiver SHOULD make a HTTP PROPFIND request to `https://:@`, where `` is the remote server, and `` is obtained by querying the [Discovery](#discovery) endpoint at the remote server and getting `resourceTypes[0].protocols.webdav`. Note that this access method is _deprecated_ and may be removed in a future release of the Protocol. From 82db97d4323553f837ad561c29d41280464904c1 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 27 Aug 2024 09:26:47 +0200 Subject: [PATCH 5/8] camel case --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 138c8102..c63070bc 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ In response to a share creation, the receiving server MAY send back a [notificat To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property: * If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. -Otherwise, if `protocol.webdav.nonce` and `protocol.webdav.gnap_as_uri` are not empty, the receiver SHOULD call the token endpoint to exchange +Otherwise, if `protocol.webdav.nonce` and `protocol.webdav.gnapAuthorizationServer` are not empty, the receiver SHOULD call the token endpoint to exchange the nonce for a short-lived access token, using [GNAP](https://datatracker.ietf.org/doc/draft-ietf-gnap-core-protocol/), and then use that GNAP access token to access the remote share. From 98d01868dac8989045d96146193ccad20bbbfc87 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 3 Sep 2024 10:54:15 +0200 Subject: [PATCH 6/8] simplify from GNAP to httpsig+bearer --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c63070bc..4a278e5e 100644 --- a/README.md +++ b/README.md @@ -50,9 +50,9 @@ In response to a share creation, the receiving server MAY send back a [notificat To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property: * If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. -Otherwise, if `protocol.webdav.nonce` and `protocol.webdav.gnapAuthorizationServer` are not empty, the receiver SHOULD call the token endpoint to exchange -the nonce for a short-lived access token, using [GNAP](https://datatracker.ietf.org/doc/draft-ietf-gnap-core-protocol/), -and then use that GNAP access token to access the remote share. +Otherwise, if `protocol.webdav.code` is not empty, the receiver SHOULD make a signed POST request to the `tokenEndpoint` from discovery to exchange +the code for a short-lived bearer token, +and then use that bearer token to access the remote share. * If `protocol.name` = `webdav`, the receiver SHOULD inspect the `protocol.options` property. If it contains a `sharedSecret`, as in the [legacy example](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1shares/post), then the receiver SHOULD make a HTTP PROPFIND request to `https://:@`, where `` is the remote server, and `` is obtained by querying the [Discovery](#discovery) endpoint at the remote server and getting `resourceTypes[0].protocols.webdav`. Note that this access method is _deprecated_ and may be removed in a future release of the Protocol. From 17a5e25d73d8b0b28fd81f1b56fc451558239a62 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 3 Sep 2024 10:55:13 +0200 Subject: [PATCH 7/8] clarify language --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4a278e5e..b51ae6e1 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ In response to a share creation, the receiving server MAY send back a [notificat To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property: * If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. -Otherwise, if `protocol.webdav.code` is not empty, the receiver SHOULD make a signed POST request to the `tokenEndpoint` from discovery to exchange +Otherwise, if `protocol.webdav.code` is not empty, the receiver SHOULD discover the sender's `tokenEndpoint` and make a signed POST request to it, to exchange the code for a short-lived bearer token, and then use that bearer token to access the remote share. From 72349f184f3aee5926b97c6c03ab48a42aeaee92 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Tue, 3 Sep 2024 14:43:45 +0200 Subject: [PATCH 8/8] `/token` --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b51ae6e1..f38ea776 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ In response to a share creation, the receiving server MAY send back a [notificat To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property: * If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share. If `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header. -Otherwise, if `protocol.webdav.code` is not empty, the receiver SHOULD discover the sender's `tokenEndpoint` and make a signed POST request to it, to exchange +Otherwise, if `protocol.webdav.code` is not empty, the receiver SHOULD discover the sender's OCM endpoint and make a signed POST request to `/token`, to exchange the code for a short-lived bearer token, and then use that bearer token to access the remote share.