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}"