From af29d7565bbbcff07d63a74a9ae1499c19a9901a Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Mon, 18 Mar 2024 18:31:34 +0100 Subject: [PATCH] Add MFA capability and permission (#79) * 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. * 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 * MFA: reworked role of the /mfa-enabled endpoint * Partially reverted previous changes, expanded descriptions for more clarity * Update spec.yaml Co-authored-by: Giuseppe Lo Presti * Update spec.yaml Co-authored-by: Giuseppe Lo Presti --------- Co-authored-by: Giuseppe Lo Presti --- .vscode/settings.json | 5 +++++ README.md | 7 +++++++ spec.yaml | 36 +++++++++++++++++++++++++++++++----- 3 files changed, 43 insertions(+), 5 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 c2a45ce..34fc987 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-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 equivalent to a `"SHARE_DECLINED"` notification. @@ -74,6 +76,11 @@ 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-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. + ## Changelog diff --git a/spec.yaml b/spec.yaml index 2df76bc..c9c99b2 100644 --- a/spec.yaml +++ b/spec.yaml @@ -108,6 +108,26 @@ paths: type: string schema: $ref: "#/definitions/Error" + /mfa-capable: + get: + summary: Inform the sender that the provider will enforce MFA requirements. + description: > + 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. + responses: + "200": + description: | + The provider claims that it is capable of enforcing MFA requirements. + "404": + description: | + 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 @@ -325,7 +345,7 @@ definitions: it is not necessary to expose it as a capability. items: type: string - enum: ["/notifications", "/invite-accepted"] + enum: ["/notifications", "/invite-accepted", "/mfa-capable"] example: ["/invite-accepted"] NewShare: @@ -456,7 +476,10 @@ 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` requires the user accessing the resource to be + MFA-authenticated. This permission MAY be used if the + provider exposes the `mfa-capable` capability. + enum: ["read", "write", "share", "mfa-enforced"] uri: type: string description: | @@ -483,7 +506,10 @@ 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` requires the user accessing the resource to be + MFA-authenticated. This permission MAY be used if the + provider exposes the `mfa-capable` capability. + enum: ["view", "read", "write", "mfa-enforced"] sharedSecret: type: string description: | @@ -518,13 +544,13 @@ definitions: sharedSecret: "hfiuhworzwnur98d3wjiwhr" webdav: sharedSecret: "hfiuhworzwnur98d3wjiwhr" - permissions: ["read"] + permissions: ["read", "write"] uri: "https://open-cloud-mesh.org/remote/dav/ocm/hfiuhworzwnur98d3wjiwhr/path/to/resource.txt" multipleProtocols: name: "multi" options: webdav: - permissions: ["read"] + permissions: ["read", "mfa-enforced"] 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}"