Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

use-code as new requirement + cleaned up superseded references to mfa-capable #156

Merged
merged 3 commits into from
Nov 14, 2024
Merged

use-code as new requirement + cleaned up superseded references to mfa-capable #156

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1a1c9ef
HTTP signature as requirement
glpatcern Sep 30, 2024
4ed613a
Renamed new requirement to `use-code` following review
glpatcern Nov 14, 2024
2902b60
Cleaned remaining references to `mfa-capable` as capability
glpatcern Nov 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions IETF-RFC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -402,9 +402,13 @@ If `multi` is given, one or more protocol
- `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` requires the user accessing the resource to be
MFA-authenticated. This permission MAY be used if the
provider exposes the `mfa-capable` capability.
* OPTIONAL requirements (array of strings) -
The requirements that the sharee MUST fulfill to access the resource. A subset of:
- `mfa-enforced` requires the consumer to be MFA-authenticated. This
MAY be used if the recipient provider exposes the `enforce-mfa` capability.
- `use-code` requires the consumer to exchange the given `code` via a
signed HTTPS request. This MAY be used if the recipient provider exposes
the `receive-code` capability.
* OPTIONAL uri (string)
An URI to access the remote resource. The URI MAY be relative,
in which case the prefix exposed by the `/ocm-provider` endpoint MUST
Expand All @@ -423,9 +427,6 @@ If `multi` is given, one or more protocol
- `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` requires the user accessing the resource to be
MFA-authenticated. This permission MAY be used if the
provider exposes the `mfa-capable` capability.
* OPTIONAL sharedSecret (string)
An optional secret to be used to access the remote web app,
for example in the form of a bearer token.
Expand Down Expand Up @@ -496,7 +497,7 @@ To access the Resource, the Receiving Server MAY use multiple ways, depending on

In all cases, in case the Shared Resource is a folder and the Receiving Server accesses a resource within that shared folder, it SHOULD append its relative path to that URL. In other words, the Sending Server SHOULD support requests to URLs such as `https://<sender-host><sender-ocm-path>/path/to/resource.txt`.

Additionally, if `protocol.<protocolname>.requirements` includes `mfa-enforced`, the Receiving Server MUST ensure that the Receiving Party has been authenticated with MFA.
Additionally, if `protocol.<protocolname>.requirements` includes `mfa-enforced`, the Receiving Server MUST ensure that the Receiving Party has been authenticated with MFA, or prompt the consmer in order to elevate their session, if applicable.

# Share Deletion
A `"SHARE_ACCEPTED"` notification followed by a `"SHARE_UNSHARED"` notification is
Expand All @@ -514,7 +515,7 @@ TODO: document how the Receiving Party can know if the Sending Party understood
reshare request.

# Appendix A: Multi Factor Authentication
If a Receiving Server exposes the capability `/mfa-capable`, it indicates that it will try and comply with a MFA requirement set on a Share. If the Sending Server trusts the Receiving Server, the Sending Server MAY set the requirement `mfa-enforced` on a Share, which the Receiving Server MUST honor. A compliant Receiving Server that signals that it is MFA-capable MUST not allow access to a resource protected with the `mfa-enforced` requirement, if the Receiving Party has not provided a second factor to establish their identity with greater confidence.
If a Receiving Server exposes the capability `enforce-mfa`, it indicates that it will try and comply with a MFA requirement set on a Share. If the Sending Server trusts the Receiving Server, the Sending Server MAY set the requirement `mfa-enforced` on a Share, which the Receiving Server MUST honor. A compliant Receiving Server that signals that it is MFA-capable MUST not allow access to a resource protected with the `mfa-enforced` requirement, if the Receiving Party has not provided a second factor to establish their identity with greater confidence.

Since there is no way to guarantee that the Receiving Server will actually enforce the MFA requirement, it is up to the Sending Server to establish a trust with the Receiving Server such that it is reasonable to assume that the Receiving Server 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 Receiving Servers. 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-flow) capability may be envisaged.

Expand Down
38 changes: 10 additions & 28 deletions spec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,26 +117,6 @@ 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
Expand Down Expand Up @@ -564,12 +544,17 @@ definitions:
A list of requirements that the recipient provider MUST fulfill
to access the resource. Requirements are optional, but if it is
present it MUST NOT be empty. A recipient provider MUST reject
a share whose requirements it does not understand. Currently,
the only requirement supported is:
a share whose requirements it does not understand.
The following requirements are currently supported:
- `mfa-enforced` requires the user accessing the resource to be
MFA-authenticated. This requirement MAY be used if the
provider exposes the `mfa-capable` capability.
enum: ["mfa-enforced"]
recipient provider exposes the `enforce-mfa` capability.
- `use-code` requires the recipient to exchange the given
`code` via a signed HTTPS request to `/token` at the Sending
Server, in order to get a short-lived token to be used for
subsequent access. This requirement MAY be used if the
recipient provider exposes the `receive-code` capability.
enum: ["mfa-enforced", "use-code"]
webapp:
type: object
properties:
Expand All @@ -592,10 +577,7 @@ 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` 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"]
enum: ["view", "read", "write"]
sharedSecret:
type: string
description: |
Expand Down