From 16505a47293067375002ccecae09f619a9a4b220 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 12 Jan 2024 12:11:11 +0100 Subject: [PATCH 1/6] V1.2.0 proposal, Add MFA capability and permission This PR is a proposal to add a capability `/mfa-enforcing` as well as a permission `mfa-enforced` to the specification. The version of the specification is bumped to 1.2.0. If an OCM provider has the capability `/mfa-enforcing` it will respond with a boolean on the endpoint /mfa-enforcing to indicate whether or not it will try to comply with a MFA requirement set as a permission on a share. If the sharer OCM provider trusts the sharee OCM provider the sharer MAY set the permission `mfa-enforced` on a share. A complient OCM provider that signals mfa-enforcing `true` MUST not allow access to a resource to a user that has not provided a second factor to establish the identity of the user with greater confidence. Since there is no way to guarantee that the sharee OCM provider will actually enforce the MFA requirement, it is up to the sharer OCM provider to establish a trust with the OCM sharee provider such that it is reasonable to assume that the sharee OCM provider will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted OCM providers. The procedure of establishing trust is out of scope for this specification. --- spec.yaml | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/spec.yaml b/spec.yaml index b58c502..1ee6975 100644 --- a/spec.yaml +++ b/spec.yaml @@ -2,7 +2,7 @@ swagger: "2.0" info: title: Open Cloud Mesh API description: Open Cloud Mesh Open API Specification. - version: 1.1.0 + version: 1.2.0 x-logo: url: logo.png schemes: @@ -108,6 +108,19 @@ paths: type: string schema: $ref: "#/definitions/Error" + /mfa-enforcing: + get: + summary: Inform the sender that the provider will enforce MFA requirements. + description: > + Signal that this OCM provider has the capability to enforce MFA requirements. + A sender MAY set the permission `mfa-enforced` on a share to this provider. + NOTE: There is no guarantee that the provider will actually enforce any MFA + requirements, so a trust must be established before relying on this capability. + responses: + 200: + description: Whether the OCM service is enforcing MFA requirements. + schema: + $ref: "#/definitions/IsMFAEnforcing" /notifications: post: summary: Send a notification to a remote party about a previously known entity @@ -321,9 +334,17 @@ definitions: it is not necessary to expose it as a capability. items: type: string - enum: ["/notifications", "/invite-accepted"] + enum: ["/notifications", "/invite-accepted", "/mfa-enforcing"] example: ["/invite-accepted"] + IsMFAEnforcing: + type: object + required: + - isMFAEnforcing + properties: + isMFAEnforcing: + type: boolean + description: Whether the OCM service is enforcing MFA requirements. NewShare: type: object required: @@ -452,7 +473,9 @@ definitions: - `read` allows read-only access including download of a copy. - `write` allows create, update, and delete rights on the resource. - `share` allows re-share rights on the resource. - enum: ["read", "write", "share"] + - `mfa-enforced`, this permission MAY be used if and only if the + OCM provider has the capability `mfa-enforcing`. + enum: ["read", "write", "share", "mfa-enforced"] uri: type: string description: | @@ -479,7 +502,9 @@ definitions: - `view` allows access to the web app in view-only mode. - `read` allows read and download access via the web app. - `write` allows full editing rights via the web app. - enum: ["view", "read", "write"] + - `mfa-enforced`, this permission MAY be used if and only + if the OCM provider has the capability `mfa-enforcing`. + enum: ["view", "read", "write", "mfa-enforced"] sharedSecret: type: string description: | From 0676b1a9a37f49c9ff87dbdf57ace0231b2844f4 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Sat, 13 Jan 2024 14:23:54 +0100 Subject: [PATCH 2/6] MFA: Address review feedback This patch adds information about MFA to the readme-file and renames `mfa-enforcing` to `mfa-capable`. The respons is simplified from a boolean response on the endpoint to an empty HTTP 200 OK response. Version is reset to 1.1.0 --- README.md | 12 ++++++++++++ spec.yaml | 28 +++++++++++----------------- 2 files changed, 23 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index c2a45ce..f9d8584 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,18 @@ Following this step, both services at `sender.com` and `receiver.com` MAY displa For further details on this concept, see also [#54](https://github.com/cs3org/OCM-API/pull/54) and related issues. For a discussion about trust policies, see [sciencemesh#196](https://github.com/sciencemesh/sciencemesh/issues/196). +### Multi Factor Authentication + + +This specification contains a capability called `/mfa-capable` as well as a permission `mfa-enforced`. + +If an OCM provider has the capability `/mfa-capable` it will respond with a HTTP 200 OK on the endpoint `/mfa-capable` to indicate that it will try to comply with a MFA requirement set as a permission on a share. If the sharer OCM provider trusts the sharee OCM provider the sharer MAY set the permission mfa-enforced on a share. + +A complient OCM provider that signals that it is mfa-capable MUST not allow access to a resource to a user that has not provided a second factor to establish the identity of the user with greater confidence. + +Since there is no way to guarantee that the sharee OCM provider will actually enforce the MFA requirement, it is up to the sharer OCM provider to establish a trust with the OCM sharee provider such that it is reasonable to assume that the sharee OCM provider will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted OCM providers. The procedure of establishing trust is out of scope for this specification. + + ## Changelog diff --git a/spec.yaml b/spec.yaml index 1ee6975..37a0bd4 100644 --- a/spec.yaml +++ b/spec.yaml @@ -2,7 +2,7 @@ swagger: "2.0" info: title: Open Cloud Mesh API description: Open Cloud Mesh Open API Specification. - version: 1.2.0 + version: 1.1.0 x-logo: url: logo.png schemes: @@ -108,7 +108,7 @@ paths: type: string schema: $ref: "#/definitions/Error" - /mfa-enforcing: + /mfa-capable: get: summary: Inform the sender that the provider will enforce MFA requirements. description: > @@ -117,10 +117,12 @@ paths: NOTE: There is no guarantee that the provider will actually enforce any MFA requirements, so a trust must be established before relying on this capability. responses: - 200: - description: Whether the OCM service is enforcing MFA requirements. - schema: - $ref: "#/definitions/IsMFAEnforcing" + "200": + description: | + The OCM service claims that it is capable of enforcing MFA requirements. + "404": + description: | + The OCM service does not have the capability to enforce MFA requirements. /notifications: post: summary: Send a notification to a remote party about a previously known entity @@ -334,17 +336,9 @@ definitions: it is not necessary to expose it as a capability. items: type: string - enum: ["/notifications", "/invite-accepted", "/mfa-enforcing"] + enum: ["/notifications", "/invite-accepted", "/mfa-capable"] example: ["/invite-accepted"] - IsMFAEnforcing: - type: object - required: - - isMFAEnforcing - properties: - isMFAEnforcing: - type: boolean - description: Whether the OCM service is enforcing MFA requirements. NewShare: type: object required: @@ -474,7 +468,7 @@ definitions: - `write` allows create, update, and delete rights on the resource. - `share` allows re-share rights on the resource. - `mfa-enforced`, this permission MAY be used if and only if the - OCM provider has the capability `mfa-enforcing`. + OCM provider has the capability `mfa-capable`. enum: ["read", "write", "share", "mfa-enforced"] uri: type: string @@ -503,7 +497,7 @@ definitions: - `read` allows read and download access via the web app. - `write` allows full editing rights via the web app. - `mfa-enforced`, this permission MAY be used if and only - if the OCM provider has the capability `mfa-enforcing`. + if the OCM provider has the capability `mfa-capable`. enum: ["view", "read", "write", "mfa-enforced"] sharedSecret: type: string From a5d0aeb951f915e75816c062b487316096dd662c Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Wed, 6 Mar 2024 07:56:23 +0000 Subject: [PATCH 3/6] MFA: reworked role of the /mfa-enabled endpoint --- .vscode/settings.json | 5 +++++ README.md | 13 ++++--------- spec.yaml | 40 ++++++++++++++++++++++++++-------------- 3 files changed, 35 insertions(+), 23 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..ef83f48 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "githubPullRequests.ignoredPullRequestBranches": [ + "develop" + ] +} \ No newline at end of file diff --git a/README.md b/README.md index f9d8584..832c4ef 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,8 @@ To access a share, the receiving server MAY use multiple ways, depending on the In both cases, when the share is a folder and the receiver accesses a resource within the share, it SHOULD append its relative path to that URL. +Additionally, if `protocol..permissions` include `mfa-enabled`, the receiver MUST be ready to receive a callback to the `/mfa-enabled` endpoint ([docs](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1mfa-enabled/get)), where it SHOULD confirm that the user accessing the resource has been authenticated with MFA. This implies that the provider MUST have stored the receiver's server address, e.g. via the [Invite](#invite) flow. + ### Share Deletion A `"SHARE_ACCEPTED"` notification followed by a `"SHARE_UNSHARED"` notification is equivalent to a `"SHARE_DECLINED"` notification. @@ -75,16 +77,9 @@ Following this step, both services at `sender.com` and `receiver.com` MAY displa For further details on this concept, see also [#54](https://github.com/cs3org/OCM-API/pull/54) and related issues. For a discussion about trust policies, see [sciencemesh#196](https://github.com/sciencemesh/sciencemesh/issues/196). ### Multi Factor Authentication +If an OCM provider exposes the capability `/mfa-enabled`, it indicates that it will try and comply with a MFA requirement set as a permission on a share. If the sharer OCM provider trusts the receiver OCM provider, the sharer MAY set the permission `mfa-enforced` on a share, which MUST be enforced according to [the endpoint's description](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1mfa-enabled/get). A compliant OCM provider that signals that it is MFA-capable MUST not allow access to a resource to a user that has not provided a second factor to establish their identity with greater confidence. - -This specification contains a capability called `/mfa-capable` as well as a permission `mfa-enforced`. - -If an OCM provider has the capability `/mfa-capable` it will respond with a HTTP 200 OK on the endpoint `/mfa-capable` to indicate that it will try to comply with a MFA requirement set as a permission on a share. If the sharer OCM provider trusts the sharee OCM provider the sharer MAY set the permission mfa-enforced on a share. - -A complient OCM provider that signals that it is mfa-capable MUST not allow access to a resource to a user that has not provided a second factor to establish the identity of the user with greater confidence. - -Since there is no way to guarantee that the sharee OCM provider will actually enforce the MFA requirement, it is up to the sharer OCM provider to establish a trust with the OCM sharee provider such that it is reasonable to assume that the sharee OCM provider will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted OCM providers. The procedure of establishing trust is out of scope for this specification. - +Since there is no way to guarantee that the sharee OCM provider will actually enforce the MFA requirement, it is up to the sharer OCM provider to establish a trust with the OCM sharee provider such that it is reasonable to assume that the sharee OCM provider will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted OCM providers. The procedure of establishing trust is out of scope for this specification: a mechanism similar to the [ScienceMesh](https://sciencemesh.io) integration for the [Invite](#invite) capability may be envisaged. ## Changelog diff --git a/spec.yaml b/spec.yaml index 37a0bd4..70c9bb1 100644 --- a/spec.yaml +++ b/spec.yaml @@ -108,21 +108,31 @@ paths: type: string schema: $ref: "#/definitions/Error" - /mfa-capable: + /mfa-enabled: get: - summary: Inform the sender that the provider will enforce MFA requirements. + summary: Request whether the consumer of a share has been authenticated with MFA. description: > - Signal that this OCM provider has the capability to enforce MFA requirements. - A sender MAY set the permission `mfa-enforced` on a share to this provider. - NOTE: There is no guarantee that the provider will actually enforce any MFA + When a consumer attempts to access a share that was created with the `mfa-enabled` + permission, the provider MUST request to the consumer's server whether the consumer + has been authenticated with MFA. The consumer server SHOULD enforce that a session + exists for the consumer and that it has been authenticated with MFA, or prompt + the consumer in order to elevate their session to MFA. + Note: There is no guarantee that the consumer service actually enforces any MFA requirements, so a trust must be established before relying on this capability. + parameters: + sharedSecret: + type: string + description: | + The secret identifying the share being accessed. responses: "200": description: | - The OCM service claims that it is capable of enforcing MFA requirements. + The user accessing the resource via the given `sharedSecret` has been + authenticated with MFA. "404": description: | - The OCM service does not have the capability to enforce MFA requirements. + There is no user accessing a share with the given `sharedSecret`, or + the endpoint does not have the capability to enforce MFA requirements. /notifications: post: summary: Send a notification to a remote party about a previously known entity @@ -336,7 +346,7 @@ definitions: it is not necessary to expose it as a capability. items: type: string - enum: ["/notifications", "/invite-accepted", "/mfa-capable"] + enum: ["/notifications", "/invite-accepted", "/mfa-enabled"] example: ["/invite-accepted"] NewShare: @@ -467,8 +477,9 @@ definitions: - `read` allows read-only access including download of a copy. - `write` allows create, update, and delete rights on the resource. - `share` allows re-share rights on the resource. - - `mfa-enforced`, this permission MAY be used if and only if the - OCM provider has the capability `mfa-capable`. + - `mfa-enforced` requires the user accessing the resource to be + MFA-authenticated. This permission MAY be used if the + provider exposes the `mfa-enabled` capability. enum: ["read", "write", "share", "mfa-enforced"] uri: type: string @@ -496,8 +507,9 @@ definitions: - `view` allows access to the web app in view-only mode. - `read` allows read and download access via the web app. - `write` allows full editing rights via the web app. - - `mfa-enforced`, this permission MAY be used if and only - if the OCM provider has the capability `mfa-capable`. + - `mfa-enforced` requires the user accessing the resource to be + MFA-authenticated. This permission MAY be used if the + provider exposes the `mfa-enabled` capability. enum: ["view", "read", "write", "mfa-enforced"] sharedSecret: type: string @@ -533,13 +545,13 @@ definitions: sharedSecret: "hfiuhworzwnur98d3wjiwhr" webdav: sharedSecret: "hfiuhworzwnur98d3wjiwhr" - permissions: ["read"] + permissions: ["read", "write"] uri: "https://open-cloud-mesh.org/remote.php/webdav/share-secret/path/to/resource.txt" multipleProtocols: name: "multi" options: webdav: - permissions: ["read"] + permissions: ["read", "mfa-enforced"] uri: "https://open-cloud-mesh.org/remote.php/webdav/share-secret/path/to/resource.txt" webapp: uriTemplate: "https://open-cloud-mesh.org/s/share-hash/{relative-path-to-shared-resource}" From 2b0c7dd7fa2b2ce43c3dc1a282163f0af8301bdf Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Mon, 18 Mar 2024 14:19:16 +0100 Subject: [PATCH 4/6] Partially reverted previous changes, expanded descriptions for more clarity --- README.md | 4 ++-- spec.yaml | 35 +++++++++++++++-------------------- 2 files changed, 17 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 832c4ef..34fc987 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ To access a share, the receiving server MAY use multiple ways, depending on the In both cases, when the share is a folder and the receiver accesses a resource within the share, it SHOULD append its relative path to that URL. -Additionally, if `protocol..permissions` include `mfa-enabled`, the receiver MUST be ready to receive a callback to the `/mfa-enabled` endpoint ([docs](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1mfa-enabled/get)), where it SHOULD confirm that the user accessing the resource has been authenticated with MFA. This implies that the provider MUST have stored the receiver's server address, e.g. via the [Invite](#invite) flow. +Additionally, if `protocol..permissions` include `mfa-enforced`, the receiving host MUST ensure that the user accessing the resource has been authenticated with MFA. ### Share Deletion A `"SHARE_ACCEPTED"` notification followed by a `"SHARE_UNSHARED"` notification is @@ -77,7 +77,7 @@ Following this step, both services at `sender.com` and `receiver.com` MAY displa For further details on this concept, see also [#54](https://github.com/cs3org/OCM-API/pull/54) and related issues. For a discussion about trust policies, see [sciencemesh#196](https://github.com/sciencemesh/sciencemesh/issues/196). ### Multi Factor Authentication -If an OCM provider exposes the capability `/mfa-enabled`, it indicates that it will try and comply with a MFA requirement set as a permission on a share. If the sharer OCM provider trusts the receiver OCM provider, the sharer MAY set the permission `mfa-enforced` on a share, which MUST be enforced according to [the endpoint's description](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1mfa-enabled/get). A compliant OCM provider that signals that it is MFA-capable MUST not allow access to a resource to a user that has not provided a second factor to establish their identity with greater confidence. +If an OCM provider exposes the capability `/mfa-capable`, it indicates that it will try and comply with a MFA requirement set as a permission on a share. If the sharer OCM provider trusts the receiver OCM provider, the sharer MAY set the permission `mfa-enforced` on a share, which SHOULD be honored. A compliant OCM provider that signals that it is MFA-capable MUST not allow access to a resource protected with the `mfa-enforced` permission, if the consumer has not provided a second factor to establish their identity with greater confidence. Since there is no way to guarantee that the sharee OCM provider will actually enforce the MFA requirement, it is up to the sharer OCM provider to establish a trust with the OCM sharee provider such that it is reasonable to assume that the sharee OCM provider will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted OCM providers. The procedure of establishing trust is out of scope for this specification: a mechanism similar to the [ScienceMesh](https://sciencemesh.io) integration for the [Invite](#invite) capability may be envisaged. diff --git a/spec.yaml b/spec.yaml index 70c9bb1..8dc1b52 100644 --- a/spec.yaml +++ b/spec.yaml @@ -108,31 +108,26 @@ paths: type: string schema: $ref: "#/definitions/Error" - /mfa-enabled: + /mfa-capable: get: - summary: Request whether the consumer of a share has been authenticated with MFA. + summary: Inform the sender that the provider will enforce MFA requirements. description: > - When a consumer attempts to access a share that was created with the `mfa-enabled` - permission, the provider MUST request to the consumer's server whether the consumer - has been authenticated with MFA. The consumer server SHOULD enforce that a session - exists for the consumer and that it has been authenticated with MFA, or prompt - the consumer in order to elevate their session to MFA. - Note: There is no guarantee that the consumer service actually enforces any MFA + Signal that this OCM provider has the capability to enforce MFA when accessing + remote shares. + A sender MAY set the permission `mfa-enforced` on a share to this provider: + when a consumer attempts to access such a share, the consumer server SHOULD + enforce, prior to access, that a session exists for the consumer and that + it has been authenticated with MFA, or prompt the consumer in order to + elevate their session to MFA if that is applicable. + Note: there is no guarantee that the consumer service actually enforces any MFA requirements, so a trust must be established before relying on this capability. - parameters: - sharedSecret: - type: string - description: | - The secret identifying the share being accessed. responses: "200": description: | - The user accessing the resource via the given `sharedSecret` has been - authenticated with MFA. + The provider claims that it is capable of enforcing MFA requirements. "404": description: | - There is no user accessing a share with the given `sharedSecret`, or - the endpoint does not have the capability to enforce MFA requirements. + The provider does not have the capability to enforce MFA requirements. /notifications: post: summary: Send a notification to a remote party about a previously known entity @@ -346,7 +341,7 @@ definitions: it is not necessary to expose it as a capability. items: type: string - enum: ["/notifications", "/invite-accepted", "/mfa-enabled"] + enum: ["/notifications", "/invite-accepted", "/mfa-capable"] example: ["/invite-accepted"] NewShare: @@ -479,7 +474,7 @@ definitions: - `share` allows re-share rights on the resource. - `mfa-enforced` requires the user accessing the resource to be MFA-authenticated. This permission MAY be used if the - provider exposes the `mfa-enabled` capability. + provider exposes the `mfa-capable` capability. enum: ["read", "write", "share", "mfa-enforced"] uri: type: string @@ -509,7 +504,7 @@ definitions: - `write` allows full editing rights via the web app. - `mfa-enforced` requires the user accessing the resource to be MFA-authenticated. This permission MAY be used if the - provider exposes the `mfa-enabled` capability. + provider exposes the `mfa-capable` capability. enum: ["view", "read", "write", "mfa-enforced"] sharedSecret: type: string From fd90c3445ef033756747de496d194f23a2e69e70 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Mon, 18 Mar 2024 18:28:30 +0100 Subject: [PATCH 5/6] Update spec.yaml Co-authored-by: Giuseppe Lo Presti --- spec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.yaml b/spec.yaml index 8df71d1..868fbe3 100644 --- a/spec.yaml +++ b/spec.yaml @@ -541,7 +541,7 @@ definitions: webdav: sharedSecret: "hfiuhworzwnur98d3wjiwhr" permissions: ["read", "write"] - uri: "https://open-cloud-mesh.org/remote.php/webdav/share-secret/path/to/resource.txt" + uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt" multipleProtocols: name: "multi" options: From f45f936b257ccca1d965d28b83923aca0318f7e5 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Mon, 18 Mar 2024 18:28:37 +0100 Subject: [PATCH 6/6] Update spec.yaml Co-authored-by: Giuseppe Lo Presti --- spec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.yaml b/spec.yaml index 868fbe3..bc1eadd 100644 --- a/spec.yaml +++ b/spec.yaml @@ -547,7 +547,7 @@ definitions: options: webdav: permissions: ["read", "mfa-enforced"] - uri: "https://open-cloud-mesh.org/remote.php/webdav/share-secret/path/to/resource.txt" + uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt" webapp: uriTemplate: "https://open-cloud-mesh.org/app/ocm/hfiuhworzwnur98d3wjiwhr/{relative-path-to-shared-resource}" viewMode: "read"