Map LDAP/AD groups to Stalwart roles (directory-driven RBAC)

Feature Ideas
1

With an LDAP/Active Directory backend, Stalwart takes authentication and group membership from the directory, but roles and permissions still have to be assigned by hand, account by account, in the Stalwart UI. I’d like the directory to drive authorization as well: membership in an AD group should grant a Stalwart role. Administrators, delegated administration and feature restrictions could then all be managed from AD.

This follows up on Roles from LDAP, where staff confirmed that “there’s no mapping from an LDAP group or attribute to a Stalwart role” and a Feature Idea was suggested.

A companion idea covers hiding accounts from the directory: [link to the second topic].

Current behaviour (checked against main @ af37a23)

  • The LDAP variant of Directory maps class, description, secret, secret-changed, memberOf, email and email alias. No field maps groups or attributes to roles.
  • Roles do not reach users through groups. In crates/common/src/auth/access_token.rs (build_access_token), a user’s effective permissions come only from the user’s own roles (User / Admin / Custom) and permissions, intersected with the tenant. member_group_ids is only used to build ACL access to shared resources. The workaround suggested in the thread above (“model your access groups as Stalwart groups and attach permissions locally”) therefore gives members access to the group’s shared resources, not server permissions.

Proposal

Add an optional mapping to the LDAP (and ideally OIDC) Directory object:

json

{
  "@type": "Ldap",
  "roleMappings": {
    "CN=G_STALWART_ADMINS,OU=Groups,DC=example,DC=org": ["admin"],
    "CN=G_MAIL_HELPDESK,OU=Groups,DC=example,DC=org": ["helpdesk"],
    "CN=G_MAIL_NO_EXTERNAL,OU=Groups,DC=example,DC=org": ["no-external-send"]
  },
  "roleMappingDefault": "defaultRoles"
}

Suggested semantics:

  • Match on the group DN, not the CN, to avoid ambiguity.
  • Roles are additive. A user in several mapped groups gets the union. disabledPermissions keeps precedence as it does today, so “restriction” roles work naturally.
  • Revocation must be timely. Mapped roles are re-evaluated whenever the account’s directory data is refreshed (login, cache expiry), not only when the account is first created. Removing someone from the admin group in AD must remove the admin role within a bounded time.
  • The directory owns mapped roles. With roleMappings set, roles on directory-backed accounts are read-only in the UI (or shown as “mapped” separately from manual roles), so that sync and manual edits do not overwrite each other.
  • Fallback when no group matches (roleMappingDefault): either apply the default user roles (current behaviour), or deny login. The second option is useful for “only members of group X may use mail”.
  • Nested groups follow the existing attrMemberOf / filterMemberOf, so AD’s LDAP_MATCHING_RULE_IN_CHAIN can be used when nesting is wanted.
  • The same mapping for OIDC (a configurable claim such as groups or roles) and for SCIM, which currently drops roles and entitlements.
  • Auditability. With mapping enabled, whoever manages the mapped AD groups effectively manages Stalwart privileges. That is the intent, but role changes that come from the directory should be logged (account, role added or removed, source group), so privilege changes can be traced.

Alternative, or complement: group role inheritance. Let members inherit the roles of the groups they belong to (for example an inheritRoles option on groups or globally). This also works for the internal directory, and combined with memberOf from AD it gives the same result. Either approach solves the problem. Role mapping keeps the logic in one place, while inheritance is more general.

Use cases

  • Stalwart administrators and tenant administrators defined by AD group.
  • Delegated administration: a helpdesk group with a custom role (for example sysAccountQuery, sysAccountGet, sysAccountUpdate, sysQueuedMessageQuery, sysQueuedMessageGet) managed entirely from AD.
  • Feature restrictions per group (no IMAP/POP, no external sending, and so on) through roles with disabledPermissions.
  • Onboarding, offboarding and privilege changes happen only in AD, with no second system to update.

Related

  • “Roles from LDAP” (Questions, linked above): the same need, raised for RBAC driven by Midpoint.
  • “Feature request: LDAP account sync” (Feature Ideas): pre-provisioning LDAP accounts. It is complementary, since timely role re-evaluation benefits from the same sync.