Module Access deprecated

Introduction

Every user carries a set of module access rights. They are the coarse switches set at provisioning time that decide which modules (mail, calendar, address book, tasks, files), which classic interfaces and which groupware features a user may use. They are assigned right by right or as a whole through a named access combination such as groupware_standard, and they are stored as one integer bitmask per user.

Module access predates the capability system. Today the middleware turns the bits into capabilities when a session is created, and clients evaluate capabilities and the settings tree rather than the bits. Module access is therefore best understood as the provisioning-side input to capabilities, not as a separate permission system. New feature switches are capabilities; new module access rights are not added anymore.

This article is the reference for the rights, their names in the different layers, their current status, the named combinations, the defaults and the validation rules.

One right, five names

The same right is spelled differently in every layer it passes through. Take the right to share folders:

Layer Name
Token in ModuleAccessDefinitions.properties, attribute of the UserModuleAccess object in RMI and SOAP readcreatesharedfolders
Command line tools (createuser, changeuser, createcontext, changecontext, changeaccessglobal) and CSV import columns --access-read-create-shared-Folders
Field of userModuleAccess in the HTTP provisioning gateway on top of gRPC readCreateSharedFolders
Capability seen by clients read_create_shared_folders
Config cascade tag, usable in withTags of context sets ucFullSharedFolderAccess

The token is the lower-cased attribute name of the UserModuleAccess provisioning object; the list of valid tokens is derived from that object, which is why it cannot be extended through configuration. The HTTP gateway uses the JSON form of the gRPC UserModuleAccess message, which is the gRPC field name in lower camel case. The capability is the lower-cased constant of the internal Permission enumeration. The tag is uc followed by the internal tag name. The table below lists all five names for every right.

The rights

The bit position refers to the value stored in the database column user_configuration.permissions. The last two rows are not bits at all but folder permissions; they are listed here because they are provisioned through the same tokens and flags. The status column says whether anything in the current product still evaluates the right:

  • live: checked by the middleware or by a shipped extension.
  • live (extension): checked by the USM/EAS extension, not by the core middleware.
  • client-side: the middleware publishes the capability and the settings value but does not check the right itself. The App Suite UI evaluates the capability to show or hide the feature.
  • ignored: accepted for compatibility and stored, without any effect. The capability and settings value may still be emitted, but neither the middleware nor the App Suite UI evaluates them.
  • dormant: an evaluating component exists in the USM/EAS extension but is not part of the shipped images.
  • reserved: the bit belonged to a removed feature and cannot be set anymore.
  • config cascade: the capability is granted from configuration, the bit cannot be provisioned.
Bit Token Command line flag HTTP field Capability Tag Status Effect
0 webmail --access-webmail webmail webmail ucWebMail live Mail module. For the context administrator the capability is removed again unless com.openexchange.mail.adminMailLoginEnabled is true.
1 calendar --access-calendar calendar calendar ucCalendar live Calendar module.
2 contacts --access-contacts contacts contacts ucContacts live Address book module.
3 tasks --access-tasks tasks tasks ucTasks live Tasks module.
4 infostore --access-infostore infostore infostore ucInfostore live Drive (files) module.
5, 6, 7 reserved Former projects, forum and pinboard rights.
8 webdavxml --access-webdav-xml webdavXml webdav_xml ucWebDAVXML ignored WebDAV/XML interface of the first Outlook OXtender. Deprecated since 7.10.0, no consumer left. The capability is still emitted.
9 webdav --access-webdav webdav webdav ucWebDAV live WebDAV access to Drive files. The WebDAV servlet requires it together with infostore.
10 ical --access-ical ical ical ucICal ignored Former read-only iCal interface, removed with 7.10.0 together with the WebDAV/XML API. No consumer left in the middleware or the App Suite UI; the capability and modules/interfaces/ical are still emitted. Unrelated to iCal import and export and to iCal feed subscriptions.
11 vcard --access-vcard vcard vcard ucVCard ignored Former read-only vCard interface, removed with 7.10.0 together with the WebDAV/XML API. No consumer left in the middleware or the App Suite UI; the capability and modules/interfaces/vcard are still emitted. Unrelated to vCard import and export.
12, 13 reserved Former RSS bookmarks and RSS portal rights.
14 syncml --access-syncml syncml mobility ucSyncML dormant SyncML interface. Only the SyncML bundle of the USM/EAS extension evaluates it, and that bundle is not part of the current USM image. Note that the capability is named mobility.
15 editpublicfolders --access-edit-public-folder editPublicFolders edit_public_folders ucFullPublicFolderAccess live Create and edit public folders. Without it existing public folders stay visible, but their permissions are reduced to read-only. Prerequisite for several derived capabilities, see below.
16 readcreatesharedfolders --access-read-create-shared-Folders readCreateSharedFolders read_create_shared_folders ucFullSharedFolderAccess live Share own folders and see folders shared by others. Losing the right does not remove existing folder permissions, it only suppresses the display of shared folders. Also required for sharing and for granting deputy permissions, see Sharing and guest mode and Deputy permissions.
17 delegatetask --access-delegate-tasks delegateTask delegate_tasks ucDelegateTasks client-side Create tasks with other participants. The UI offers the participants section of the task editor only with this capability. Published as modules/tasks/delegate_tasks.
18 editgroup --access-edit-group editGroup edit_group ucEditGroup client-side Group management. The UI loads the group administration plugin and its settings entry only with this capability and gab.
19 editresource --access-edit-resource editResource edit_resource ucEditResource client-side Resource management. The UI loads the resource administration plugin only with this capability.
20 editpassword --access-edit-password editPassword edit_password ucEditPassword live Change the own password. The password change bundle re-checks the capability at runtime.
21 collectemailaddresses --access-collect-email-addresses collectEmailAddresses collect_email_addresses ucCollectEMailAddresses client-side Contact collector for sent and received mails. The UI shows the collector settings only with this capability; the collection itself follows the user's mail settings.
22 multiplemailaccounts --access-multiple-mail-accounts multipleMailAccounts multiple_mail_accounts ucMultipleMailAccounts live Additional (external) mail accounts. The mail account actions of the HTTP API require it.
23 subscription --access-subscription subscription subscription ucSubscription live Subscriptions of external address books through the subscribe framework: Google Contacts, Microsoft contacts, Yahoo contacts and the CardDAV address books of GMX, T-Online and WEB.DE. The capability is only granted when at least one of these sources is available to the user. Calendar subscriptions such as iCal feeds or Google Calendar are calendar providers gated by calendar_<provider> capabilities and do not depend on this right.
24 publication --access-publication publication none none ignored Publications were removed with 7.10.2. The bit is stored, no capability is emitted.
25 activesync --access-active-sync activeSync active_sync ucActiveSync live (extension) Exchange ActiveSync through the USM/EAS extension. EAS rejects a session without it while com.openexchange.usm.eas.access_check is true, which is the default. Client onboarding checks it as well.
26 usm --access-usm usm usm ucUSM live (extension) Universal Sync Module, the base of EAS. USM rejects a session without it. An EAS user needs both usm and activesync.
27 olox20 --access-olox20 olox20 olox20 ucOLOX20 ignored OLOX 2.0 Outlook connector. No consumer left. The capability is still emitted.
28 deniedportal --access-denied-portal deniedPortal none, see portal below ucDeniedPortal client-side Negative right that hides the portal. Clients see the positive capability portal whenever this bit is not set, and the UI loads the portal app only with portal.
29 caldav config cascade Granted by the CalDAV bundle when com.openexchange.caldav.enabled is true for the user, see CalDAV and CardDAV.
30 carddav config cascade Granted by the CardDAV bundle when com.openexchange.carddav.enabled is true for the user, see CalDAV and CardDAV.
none globaladdressbookdisabled --access-global-address-book-disabled globalAddressBookDisabled none, see gab below live Not a bit. Removes the user's permission on the global address book folder, according to the context's global address book mode. Clients see the gab capability only while the address book is enabled. Subject to the validation rule below.
none publicfoldereditable --access-public-folder-editable publicFolderEditable none live, context administrator only Not a bit. Grants folder administrator permission on the public root folders. Silently dropped for every other user, so all and groupware_premium result in identical rights for a regular user.

Derived capabilities

Some capabilities are computed from combinations of bits rather than from a single bit:

Capability Condition
pim calendar and contacts and tasks
groupware readcreatesharedfolders or editpublicfolders
freebusy, conflict_handling, participants_dialog calendar and readcreatesharedfolders and editpublicfolders
portal deniedportal not set
gab global address book not disabled for the user
spam webmail, and spam handling enabled in the user's mail settings

Of these, the App Suite UI evaluates freebusy, portal, gab and spam. pim, groupware, conflict_handling and participants_dialog are not evaluated by the UI.

Capabilities that originate from module access carry the source permissions in the capability debug output, see Debug logging for capabilities. Note the naming trap: the permissions property in permissions.properties is a list of capabilities and has nothing to do with module access.

Module access cannot be set as capabilities

A recurring operator mistake was to grant or revoke a module access right through its capability name, for example --capabilities-to-add infostore, com.openexchange.capability.webmail=false in a properties file, or -calendar in a context set. This never changes the stored rights. The middleware therefore keeps module access rights out of capability handling entirely:

  • Provisioning rejects it. --capabilities-to-add and --capabilities-to-remove on changeuser and changecontext, as well as the RMI, SOAP and HTTP equivalents, fail with The capabilities '...' are in conflict with permissions! Permissions must not be defined as capabilities. when the list contains a capability that belongs to a module access right. Setting config/com.openexchange.capability.<right> as a user attribute fails with Setting the permission(s) '...' via user attributes is not allowed!!
  • Configuration is ignored. A com.openexchange.capability.<right> property anywhere in the configuration and a right named in a context set YAML file are reported as errors at server startup (Permissions must not be defined as properties. Please remove '...'). At evaluation time such entries are skipped, whether they come from the permissions property, from com.openexchange.capability.* properties, or from the reseller, context and user capability tables, and whether they are positive or negated (-webmail). Each skipped entry is logged at most once per hour per user under the logger PermissionConfigurationChecker_capability as Ignoring capability '...' because it's in conflict with a permission.

The protected names are exactly the capabilities in the table above, including caldav and carddav. The derived capabilities pim, groupware, freebusy, conflict_handling, participants_dialog, portal, gab and spam are not protected; they can still be added or removed as ordinary capabilities.

Named access combinations

A named access combination is a shorthand for a set of tokens. Names are accepted by createcontext, changecontext, createuser, changeuser and changeaccessglobal (--access-combination-name), by the corresponding RMI and SOAP operations (create and changeModuleAccess with an access_combination_name argument), by the HTTP provisioning gateway on top of gRPC (accessCombinationName next to userModuleAccess in the bodies of POST /prov/v1/contexts, POST /prov/v1/contexts/{id}/users and the PATCH .../module-access operations; GET /prov/v1/access-combinations/{name}/module-access resolves a name to its rights), and by OX Cloud provisioning, which resolves them through the same cache as the admin daemon.

Where the definitions come from

  • A definition is a property com.openexchange.moduleaccessdefinitions.<name> whose value is a comma-separated list of tokens. The traditional place is /opt/open-xchange/etc/ModuleAccessDefinitions.properties. Inside that file the bare name (groupware_standard=...) is still honored as legacy key and reported once in the log as deprecated, see Property changes.
  • The shipped combinations listed below are also built into the server. A deployment without the file knows them, a configured entry with the same name replaces the built-in one, and additional names can be added.
  • Tokens are lower case; whitespace around the commas is ignored. A token that does not exist is a hard error when the definitions are loaded: Predefined combination "<name>" contains invalid module "<token>" is logged and the definitions are rejected, so a typo shows up at startup of the admin daemon rather than at provisioning time.

Shipped combinations

Token webmail_plus pim_plus groupware_plus premium groupware webmail pim pim_infostore pim_mobility groupware_standard groupware_premium drive all
webmail x x x x x x x x x x x x
calendar x x x x x x x x x x
contacts x x x x x x x x x x x x x
tasks x x x x x x x x x x
infostore x x x x x x x x
webdav x x x x x x
ical x x x x x
vcard x x x x x
webdavxml x x x x
syncml x x x
usm x x x
activesync x x x
olox20 x x
readcreatesharedfolders x x x x x x
editpublicfolders x x x x x x
delegatetask x x x x x x
editgroup x x x x
editresource x x x x
editpassword x x x x x x x x
collectemailaddresses x x x x x x x x x
multiplemailaccounts x x x x x x x
subscription x x x x x x x
publication x x x x x x x
deniedportal x
globaladdressbookdisabled x x x x
publicfoldereditable x x x x

Notes on the shipped set:

  • webmail_plus, pim_plus, groupware_plus and premium are the package names of the original product editions. The file marks them deprecated, but they are still valid, and webmail_plus is still the default for new contexts.
  • groupware is groupware_standard plus webdavxml and publicfoldereditable.
  • webmail, pim, pim_infostore and pim_mobility disable the global address book.
  • all differs from groupware_premium only by publicfoldereditable. Because that right is dropped for regular users, both produce identical rights for everyone except the context administrator.
  • The deprecated tokens webdavxml, olox20 and publication stay in the shipped combinations on purpose: removing them would change the bitmask of newly provisioned users, and users provisioned earlier would no longer resolve to a name (see reverse lookup).

How a name is applied

Resolving a name yields a complete set of rights: every token in the list is switched on, every other right is switched off. Nothing is inherited from the context administrator or from the user's current rights. Two rules are applied on top:

  • publicfoldereditable is removed unless the target user is the context administrator.
  • With changeaccessglobal -a <name>, globaladdressbookdisabled is ignored; that tool refuses to change the global address book.

Reverse lookup

getaccesscombinationnameforuser, getaccesscombinationnameforcontext, the RMI and SOAP operation getAccessCombinationName and the gateway's GET /prov/v1/contexts/{id}/access-combination-name and GET /prov/v1/contexts/{id}/users/{userId}/access-combination-name compare the user's rights with every definition and return the name of the first exact match. A user whose rights match no definition, for instance after a single right was toggled with changeuser, has no name. Because a regular user never keeps publicfoldereditable, a user provisioned with all resolves to groupware_premium. getmoduleaccessforcontext and the gateway's GET .../module-access operations return the individual rights instead.

The report client decodes a raw bitmask into flags with report -b <bitmask> (--showaccesscombination), and its reports count users per combination. The names also surface outside provisioning: OX Display uses them as package names and the advertisement configuration can key on them. Renaming or removing a definition therefore affects more than provisioning.

Defaults

Situation Resulting rights
createcontext without any access option The combination named by com.openexchange.admin.hosting.NEW_CONTEXT_DEFAULT_ACCESS_COMBINATION_NAME, by default webmail_plus. If that name is unknown, webmail and contacts.
createuser without any access option The context administrator's rights minus publicfoldereditable.
createuser with individual --access-* flags The context administrator's rights with the given flags applied on top. A flag that is not given is inherited, not "off", regardless of the default quoted in the help text.
changeuser with individual flags The user's current rights with the given flags applied.
createuser --csv-import with access columns All rights off, then the columns applied. A row without any access column inherits from the context administrator.
Shared accounts A fixed set: webmail, calendar and contacts, with the global address book disabled and the portal denied. It cannot be changed per account, and the shared account tools accept no access options, see Shared accounts.
Guest users Assigned automatically when the guest is created: deniedportal, editpublicfolders, readcreatesharedfolders, the module rights of the shared items, and editpassword for guests with a password. See Sharing and guest mode.

Validation rules

  • globaladdressbookdisabled together with editpublicfolders, readcreatesharedfolders, delegatetask or webdavxml is rejected with Global address book cannot be disabled for non-PIM users unless com.openexchange.admin.bypassAccessCombinationChecks is true. The property can be set through the config cascade up to context scope.
  • publicfoldereditable is only honored for the context administrator.
  • changeaccessglobal refuses to change globaladdressbookdisabled.
  • Capabilities that correspond to a module access right are rejected by provisioning and ignored in configuration, see above.
  • Reducing rights does not delete data. Data of modules a context can no longer reach is removed with deleteinvisible.

Where clients see module access

  1. Capabilities: the capabilities module of the HTTP API, source permissions. This is what the App Suite UI evaluates. The effective set of a user or context can be listed with getusercapabilities and getcontextcapabilities.
  2. Settings tree: the config module publishes modules/<module>/module for mail, calendar, contacts, tasks and infostore, modules/interfaces/ical, modules/interfaces/vcard and modules/interfaces/syncml, modules/folder/public_folders and modules/folder/read_create_shared_folders, modules/tasks/delegate_tasks, modules/calendar/calendar_conflict and modules/portal/module. The USM/EAS extension adds modules/com.openexchange.usm/active and modules/com.openexchange.usm.eas/module and evaluates exactly these nodes to admit or reject a synchronization session.
  3. Config cascade tags: every set bit contributes a uc<Tag> tag (ucWebMail, ucFullSharedFolderAccess, ...), so context sets can select configuration by module access, see Config cascade.
  4. Database: the bitmask in user_configuration.permissions; the two folder-permission rights live in the folder permission tables.

Deprecated and reserved rights

Bits are never renumbered or reused. The mask is stored per user, the name lookup is an exact match, the report client and OX Display interpret the names, and OX Cloud provisioning passes them through. Deprecated tokens therefore remain accepted, and the table above records which of them still do something. Do not add module access rights for new features; use capabilities (com.openexchange.capability.* properties, --capabilities-to-add, or the capability tables) instead.

Related

Articles:

Command line tools: createuser, changeuser, changeaccessglobal, createcontext, changecontext, getaccesscombinationnameforuser, getaccesscombinationnameforcontext, getmoduleaccessforcontext, getusercapabilities, getcontextcapabilities, deleteinvisible.