Add MFA capability and permission

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
 

spec.yaml

@@ -108,6 +108,21 @@ 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 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: |
+            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
@@ -321,7 +336,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:
@@ -452,7 +467,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-capable`.
+                    enum: ["read", "write", "share", "mfa-enforced"]
                 uri:
                   type: string
                   description: |
@@ -479,7 +496,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-capable`.
+                  enum: ["view", "read", "write", "mfa-enforced"]
                 sharedSecret:
                   type: string
                   description: |