You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by rc...@apache.org on 2022/12/01 05:05:15 UTC
[james-project] branch master updated: JAMES-3756 JMAP Delegation extension specification (#1332)
This is an automated email from the ASF dual-hosted git repository.
rcordier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
The following commit(s) were added to refs/heads/master by this push:
new e8ff974754 JAMES-3756 JMAP Delegation extension specification (#1332)
e8ff974754 is described below
commit e8ff9747540afe1c2ee12dc83997c70c1532067a
Author: Trần Hồng Quân <55...@users.noreply.github.com>
AuthorDate: Thu Dec 1 12:05:10 2022 +0700
JAMES-3756 JMAP Delegation extension specification (#1332)
---
.../doc/specs/spec/mail/delegation.mdown | 167 +++++++++++++++++++++
.../doc/specs/spec/mail/identity.mdown | 3 -
.../jmap-rfc-8621/doc/specs/spec/mail/intro.mdown | 11 ++
3 files changed, 178 insertions(+), 3 deletions(-)
diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/delegation.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/delegation.mdown
new file mode 100644
index 0000000000..38fb2d4400
--- /dev/null
+++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/delegation.mdown
@@ -0,0 +1,167 @@
+# Delegations extension
+
+> :information_source:
+> Not Implemented
+
+## Context
+This extension is specific to the Apache James server which defines methods to manage users' JMAP delegation settings.
+
+This extension to the JMAP specification enables to:
+
+- Manage accounts that a user delegates access to.
+- Manage accounts that a user is allowed access.
+
+## Addition capability
+The URN `urn:apache:james:params:jmap:delegation` represents support for the Delegation data type and associated API methods.
+
+Servers supporting this specification MUST add this property to the capabilities object.
+
+## Addition to the Session object
+Servers supporting this specification MUST add the delegated accounts to the `accounts` property of the Session object.
+
+## Behavioral changes
+When `urn:apache:james:params:jmap:delegation` is specified, access to a delegated account is enabled through standard JMAP API calls
+but MUST except API calls to manage delegated account's delegation setting to avoid privilege escalation.
+
+## Delegation methods
+A **Delegation** object stores information about an email address that either has access to the user's account or delegates access
+to the user. The semantics for this object depends on the context of usage methods: either manage delegate accounts or delegated accounts.
+
+The delegation object MUST have the following properties:
+- **id**: `Id` (immutable; server-set)
+ The id of the Delegation.
+- **username**: `String` (immutable)
+ The email address of the user that either delegates or is delegated to this user account.
+
+The **Delegate** object follows the structure of **Delegation** and represents delegations accessing this account (allowing the listed user to connect as the current account owner).
+
+The **DelegatedAccount** object follows the structure of **Delegation** and represents delegations active for this account (allowing the current account owner to connect as the listed user).
+
+A user can delegate his account to multiple users as well as be allowed to access other accounts.
+
+A user can manage his delegations to other users to access his account by creating, deleting and retrieving **Delegate** objects.
+Meanwhile, a user can only retrieve and delete **DelegatedAccount** objects.
+
+A server MUST not allow a delegated user to access and manage the owner user's delegation setting to avoid privilege escalation.
+
+The following JMAP methods are supported:
+
+### Delegate/get
+This method returns **Delegate** objects of the user.
+
+This is a standard "/get" method as described in [@!RFC8620], Section 5.1. The *ids* argument may be `null` to fetch all at once.
+
+A server MUST return the *SetError* type `forbidden` when a delegated user accesses the owner user's delegation setting.
+
+### Delegate/set
+This method allows the user to manage (create and delete) his **Delegate** objects.
+
+This is a standard "/set" method as described in [@!RFC8620], Section 5.3, except the update part because of its limited usage.
+
+A server MUST return the *SetError* type `forbidden` when a delegated user accesses the owner user's delegation setting.
+
+### DelegatedAccount/get
+This method returns **DelegatedAccount** objects of the user.
+
+This is a standard "/get" method as described in [@!RFC8620], Section 5.1. The *ids* argument may be `null` to fetch all at once.
+
+A server MUST return the *SetError* type `forbidden` when a delegated user accesses the owner user's delegation setting.
+
+### DelegatedAccount/set
+This method allows the user to delete his **DelegatedAccount** objects.
+
+This method implements only destroy part of the standard "/set" method as described in [@!RFC8620], Section 5.3.
+
+A server MUST return the *SetError* type `forbidden` when a delegated user accesses the owner user's delegation setting.
+
+## Examples
+
+### Fetching delegate accounts
+Request fetching all delegate accounts of the account:
+
+ [[ "Delegate/get", {
+ "accountId": "u33084183",
+ "ids": null
+ }, "0" ]]
+
+Response:
+
+ [[ "Delegate/get", {
+ "accountId": "u33084183",
+ "list": [{
+ "id": "e50b2c1d-9553-41a3-b0a7-a7d26b599ee1",
+ "username": "bob@test.org"
+ }, {
+ "id": "f2d0aab5-e976-4e8b-ad4b-b380a5b987e4",
+ "username": "alice@test.org"
+ }],
+ "notFound": []
+ }, "0" ]]
+
+### Create a delegate account
+Request creating a delegate account of the account:
+
+ [[ "Delegate/set", {
+ "accountId": "u33084183",
+ "create": {
+ "4f29": {
+ "username": "bob@test.org"
+ }
+ }
+ }, "0" ]]
+
+Response:
+
+ [[ "Delegate/set", {
+ "created": {
+ "4f29": {
+ "id": "abdfe762l"
+ }
+ }
+ }, "0" ]]
+
+### Delete a delegate account
+Request deleting a delegate account of the account:
+
+ [[ "Delegate/set", {
+ "destroy": ["P43dcfa4-1dd4-41ef-9156-2c89b3b19c60"]
+ }, "0" ]]
+
+Response:
+
+ [[ "DelegatedAccount/set", {
+ "destroyed":["P43dcfa4-1dd4-41ef-9156-2c89b3b19c60"]
+ }, "0" ]]
+
+
+### Fetching delegated accounts
+Request fetching all delegated accounts of the account:
+
+ [[ "DelegatedAccount/get", {
+ "accountId": "u33084183",
+ "ids": null
+ }, "0" ]]
+
+Response:
+
+ [[ "DelegatedAccount/get", {
+ "accountId": "u33084183",
+ "list": [{
+ "id": "e50b2c1d-9553-41a3-b0a7-a7d26b599ee1",
+ "username": "andre@test.org"
+ }],
+ "notFound": []
+ }, "0" ]]
+
+### Delete a delegated account
+Request deleting a delegated account of the account:
+
+ [[ "DelegatedAccount/set", {
+ "destroy": ["P43dcfa4-1dd4-41ef-9156-2c89b3b19c60"]
+ }, "0" ]]
+
+Response:
+
+ [[ "DelegatedAccount/set", {
+ "destroyed":["P43dcfa4-1dd4-41ef-9156-2c89b3b19c60"]
+ }, "0" ]]
\ No newline at end of file
diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/identity.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/identity.mdown
index e9f9a6f225..484c038f2c 100644
--- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/identity.mdown
+++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/identity.mdown
@@ -41,9 +41,6 @@ This is a standard "/changes" method as described in [@!RFC8620], Section 5.2.
## Identity/set
-> :warning:
-> Not implemented.
-
This is a standard "/set" method as described in [@!RFC8620], Section 5.3. The following extra *SetError* types are defined:
For **create**:
diff --git a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/intro.mdown b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/intro.mdown
index 87283c35de..d6659794b6 100644
--- a/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/intro.mdown
+++ b/server/protocols/jmap-rfc-8621/doc/specs/spec/mail/intro.mdown
@@ -153,6 +153,17 @@ This extension is specific to the Apache James server and enables to:
* read quotas usage and limits on mailboxes.
+### urn:apache:james:params:jmap:delegation
+
+> :information_source:
+> Not implemented
+
+This represents support for the Delegation data type and associated API methods. Servers supporting this specification MUST add this property to the capabilities object.
+
+This extension is specific to the Apache James server and enables to:
+
+* manage accounts that a user delegates access to, and accounts that a user is allowed to access.
+
## Data Type Support in Different Accounts
The server MUST include the appropriate capability strings as keys in the *accountCapabilities* property of any account with which the user may use the data types represented by that URI. Supported data types may differ between accounts the user has access to. For example, in the user's personal account, they may have access to all three sets of data, but in a shared account, they may only have data for `urn:ietf:params:jmap:mail`. This means they can access Mailbox/Thread/Email data in [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org