Deputy permissions deprecated

Introduction

Since version v7.10.6 the Open-Xchange Middleware offers the feature to grant deputy permissions to one ore more users from the same context that are supposed to act as representatives (e.g. vacation replacement).

A deputy has configurable access to granting user's primary mail account's Inbox and/or standard Calendar folder. Moreover, a deputy might get the "send on behalf of" permission granted, which allows him to send E-Mails on behalf of the granting user.

A deputy can also be appointed across context boundaries, subject to the deployment-wide trust-zone policy. See Cross-Context Collaboration.

Configuration

To enable the deputy permission feature, the open-xchange-deputy package needs to be enabled in your chart's values.yaml:

core-mw:
  packages:
    status:
      open-xchange-deputy: enabled

Enable deputy permissions

To enable deputy permission management the com.openexchange.deputy.enabled property needs to be set to true, which is false by default. That property is fully config-cascade-aware. After the feature is enabled, the user will gain access to a new deputy permission management menu in the App Suite UI.

Behavior

Deputy permissions do overwrite possibly existent permissions. Moreover, granted deputy permissions cannot be changed/deleted via regular permission dialogue, but only via deputy permission management by the granting user.

The setting com.openexchange.deputy.simplePermissionMode controls whether deputy permissions may only be assigned to users (not groups) and may only contain such permission rights for viewer, editor and author as App Suite UI would grant those permission rights.

Currently, deputy permissions for the following modules can be granted:

  • Mail
  • Calendar

Furthermore for the mail module, the granting user of the deputy permission can decide whether the deputy can sent mails using the granting user's mail account. If granted, mails can be send by the deputy "on behalf of" the granting user. To indicate that a deputy and not the granting user responded, the Sender header filled with the deputy's mail address will be set within the mail. Whereby the From header will be set to granting user's default sender address. E.g.:

From: Granting user <grantinguser@example.org>
Sender: Deputy <deputy@example.org>

In case the deputy has been given write permissions to the granting user's calendar, outgoing notification and/or iTIP mails (see also the iTIP article) will automatically be decorated with the "on behalf" relationship. This applies to the outgoing mails as well as for the generated iCAL files sent along the mails. E.g.:

ORGANIZER;CN=Granting user;SENT-BY="mailto:deputy@example.org";EMAIL=grantinguser@example.org:mailto:grantinguser@example.org

Incoming scheduling mails from the shared inbox can be managed by the deputy as well in case author permissions are available for the granting user's default calendar folder. However, in order to analyze them properly, full iMIP emails are required - the context-internally used notification mails are not sufficient to discover the "on behalf" relationship correctly. Therefore, it is recommended to configure the property com.openexchange.calendar.useIMipForInternalUsers to true if this delegation feature is being used.

Requirements

To grant deputy permission to the primary mail account's Inbox folder, the mail account is required to be an IMAP account that supports the RFC 2086 ACL and RFC 5464 METADATA extensions, and supports the /shared/vendor/vendor.open-xchange/deputy METADATA key.

For further reading on METADATA and METADATA keys, read for example the Dovecot IMAP METADATA documentation

Provisioning

With v8.29 of the Open-Xchange Server, deputy permissions can also be managed through the "http://soap.admin.openexchange.com/OXDeputyPermissionsService" SOAP end-point.

To set module permissions of the calendar module, the module id calendar can be used within respective modulePermissions element. For the mail module, this would be identifier mail.

However, using that SOAP API requires that primary mail server is a Dovecot IMAP server with DoveAdm REST API enabled. Hence, the Middleware's connector for that DoveAdm REST API needs to be enabled.

Example doveadm.properties file:

# Enable
com.openexchange.dovecot.doveadm.enabled=true

# Connection settings
com.openexchange.dovecot.doveadm.endpoints=https://127.0.0.1:8080/doveadm/v1
com.openexchange.dovecot.doveadm.endpoints.totalConnections=100
com.openexchange.dovecot.doveadm.endpoints.maxConnectionsPerRoute=0 (max. connections per route is then determined automatically by specified end-points)
com.openexchange.dovecot.doveadm.endpoints.readTimeout=20000
com.openexchange.dovecot.doveadm.endpoints.connectTimeout=5000

# Secret
com.openexchange.dovecot.doveadm.apiSecret=secret

Since DoveAdm REST API does not provide querying the namespace information for the folder prefixes for personal, shared/user and public namespaces, those prefixes need to be manually specified through following properties to leverage additional features such as auto-subscription/auto-unsubscription of shared/unshared folders for the target user:

  • com.openexchange.deputy.provider.imap.doveadm.personalNamespace
  • com.openexchange.deputy.provider.imap.doveadm.sharedNamespace
  • com.openexchange.deputy.provider.imap.doveadm.publicNamespace

Example for such a section in deputy.properties file:

com.openexchange.deputy.provider.imap.doveadm.personalNamespace=/
com.openexchange.deputy.provider.imap.doveadm.sharedNamespace=shared/
com.openexchange.deputy.provider.imap.doveadm.publicNamespace=public/

Granting a Cross-Context Deputy via SOAP

A deputy can also be appointed when the deputy resides in a different context than the granting user, subject to the deployment-wide trust-zone policy. This uses the very same grant operation of the OXDeputyPermissionsService as a regular deputy - the only difference is that the deputy's context is supplied explicitly:

  • the context and user elements identify the granting user, whose calendar and/or inbox is delegated;
  • the deputyPermission identifies the deputy by userId, and - for a cross-context deputy - additionally by contextId, the context the deputy resides in.

A positive contextId that differs from the granting user's context marks the deputy as cross-context; omitting it (or supplying 0) keeps the regular same-context behavior. Such a grant is admitted only if the trust zones of the granting user's context and the deputy's context intersect, otherwise it is rejected by the cross-context authority.

The following request lets user 4 in context 1 appoint user 7 from context 5 as a deputy, with read-write access to the calendar and read access to the inbox plus "send on behalf of". The per-module values are the standard App Suite folder/object permission bits (e.g. 2 = read, 4 = read/write/delete all, 8 = create subfolders, 128 = admin):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.admin.openexchange.com" xmlns:xsd="http://dataobjects.soap.admin.openexchange.com/xsd" xmlns:xsd1="http://dataobjects.rmi.admin.openexchange.com/xsd">
  <soapenv:Header/>
  <soapenv:Body>
    <soap:grant>
      <soap:deputyPermission>
        <xsd:userId>7</xsd:userId>
        <xsd:contextId>5</xsd:contextId>
        <xsd:sendOnBehalfOf>true</xsd:sendOnBehalfOf>
        <xsd:modulePermissions>
          <xsd:moduleId>calendar</xsd:moduleId>
          <xsd:folderPermission>4</xsd:folderPermission>
          <xsd:readPermission>4</xsd:readPermission>
          <xsd:writePermission>4</xsd:writePermission>
          <xsd:deletePermission>4</xsd:deletePermission>
          <xsd:admin>false</xsd:admin>
        </xsd:modulePermissions>
        <xsd:modulePermissions>
          <xsd:moduleId>mail</xsd:moduleId>
          <xsd:folderPermission>2</xsd:folderPermission>
          <xsd:readPermission>4</xsd:readPermission>
          <xsd:writePermission>0</xsd:writePermission>
          <xsd:deletePermission>0</xsd:deletePermission>
          <xsd:admin>false</xsd:admin>
        </xsd:modulePermissions>
      </soap:deputyPermission>
      <soap:context>
        <xsd:id>1</xsd:id>
      </soap:context>
      <soap:user>
        <xsd:id>4</xsd:id>
      </soap:user>
      <soap:auth>
        <xsd1:login>oxadmin</xsd1:login>
        <xsd1:password>secret</xsd1:password>
      </soap:auth>
    </soap:grant>
  </soapenv:Body>
</soapenv:Envelope>

The call returns the identifier of the newly granted deputy permission. The auth credentials are the administrative credentials for the granting user's context (or the master admin). A regular, same-context deputy is granted with the identical request, simply leaving out the contextId element.

Entity information in deputy listings

The deputy HTTP API listing endpoints enrich every returned permission with an entityInfo block — the same server-resolved display information (identifier, type, display_name, contact.email1, …) that the Shared Accounts API provides — so a client can render a deputy (and, in the reverse listing, the grantor) without resolving the user itself.

This is primarily aimed at cross-context entities: when a deputy or grantor lives in a different context, its bare numeric user id (userId / grantorId, reported as 0) is meaningless in the requesting user's context and the client has no directory to resolve it against. For such a foreign entity the qualified identifier (<id>@<contextId>) is the stable key, and the bare numeric entity is omitted from entityInfo. For a group deputy no entityInfo is emitted, as a group is always context-local and thus resolvable by the client itself.

  • GET /deputy?action=all (the deputies granted by the session user) — each entry carries an entityInfo block describing the deputy entity (the user appointed as deputy).
  • GET /deputy?action=reverse (who appointed the session user as a deputy) — each entry additionally carries a grantorEntityInfo block describing the granting user; the entry's own entityInfo continues to describe the deputy entity (here: the requesting user).

Example action=reverse entry for a cross-context grantor — the bare grantorId is masked to 0, and the grantor is identified and rendered solely from the qualified grantorIdentifier and the resolved grantorEntityInfo:

{
  "deputyId": "d3a1b2c4-…",
  "grantorId": 0,
  "grantorIdentifier": "4@1",
  "grantorEntityInfo": {
    "identifier": "4@1",
    "type": "user",
    "display_name": "Granting User",
    "contact": { "email1": "grantinguser@example.org" }
  },
  "sendOnBehalfOf": true
}