User accounts

A user account represents someone who signs in to the server and owns a mailbox. Usually that is a person, but it can also be a service, such as an application that sends notifications. Creating a user account is what gives a new user an address, a place to store mail and data, and the credentials to reach them.

A user account is the User variant of the Account object (found in the WebUI under Management › Directory › Groups, Management › Directory › Accounts). This page describes the fields that require a decision when an account is created or changed, grouped by what they decide. The reference page lists every field with its type and default, and Accounts explains the model.

Identity and address

The first decision is the account’s address, which is also its identity. name is the local part of the address, and domainId is the domain it belongs to. Both are required. From them the server derives the read-only emailAddress, name@domain, which is also the name the user signs in with. description is the user’s display name, for example the full name.

aliases lists further addresses that deliver to the account. Each alias has these parts:

• A local part (name) and a domainId.
• An optional description.
• An enable flag, which turns the alias off without deleting it.

Every alias must be an address that no other account, group or mailing list uses. Users can also sign in with an alias when they hold the authenticateWithAlias permission, which the default User role includes.

Credentials

credentials is the list of the account’s credentials. The Password credential holds:

• The password, in secret.
• An optional two-factor authentication URL, in otpUrl.
• Optional expiresAt and allowedIps restrictions.

A password can be given in two forms. In clear text, the server hashes it before storing it. As a hash in one of the supported formats, the server stores it as given, which allows accounts to be migrated from another system.

App passwords and API keys appear in the same list, but they cannot be set through it. They are created afterwards, through the AppPassword and ApiKey objects, so that the server can generate their secret. An attempt to include one in credentials fails with Secondary credentials cannot be set directly. Managing accounts describes the procedure. Accounts from an external directory can hold app passwords and API keys like any other account.

Groups

memberGroupIds is the set of groups the user belongs to. Membership gives the user access to the group’s mailboxes and to everything shared with the group.

Mailing lists are a separate concept, and they are not configured on the account. A mailing list is an address that expands to a list of recipients, while a group is an account with its own mailbox.

Roles and permissions

The account’s permissions are decided in two steps. roles first selects the roles that grant the account its permissions. It takes one of three values:

• User, the value new accounts receive, applies the default user role set of the Authentication singleton.
• Admin applies the default administrator role set of the Authentication singleton.
• Custom applies the roles listed in its roleIds (Assigning roles).

permissions then adjusts the result of the roles. It too has three modes:

• Inherit uses the roles alone.
• Merge adds the permissions in enabledPermissions to those of the roles.
• Replace ignores the roles and grants only enabledPermissions.

In Merge and Replace mode, disabledPermissions removes permissions, whatever their source. Permissions describes the computation, and Roles the default roles.

Quotas

quotas limits how much the account may store. It maps a quota type to a limit. maxDiskQuota is given in bytes, and the other types are counts, such as maxEmails, maxMailboxes, maxAppPasswords or maxApiKeys. A type that is not listed is not limited by the account.

The read-only usedDiskQuota reports the space currently in use. Quotas describes how limits are enforced.

Personal settings

Some fields describe the user’s preferences. locale records the user’s language, and timeZone the user’s time zone.

encryptionAtRest decides whether messages are stored encrypted. When it is enabled, the server encrypts the messages stored for the account with one of the user’s OpenPGP or S/MIME public keys. Disabled stores messages as received.

Users can change these settings themselves in the Account Manager.

Enterprise fields

Enterprise feature

This feature is available in the Enterprise edition of Stalwart.

Two fields link the account to features of the Enterprise edition. memberTenantId places the account in a tenant. externalId holds the identifier assigned by a SCIM identity provider, and is set by the provisioning process.

Example

The following object creates the user [email protected]. It gives the user a password, the alias [email protected], membership of one group and a 5 GB disk quota. The domain and the group are referenced by their ids:

{
  "@type": "User",
  "name": "jane",
  "domainId": "b",
  "description": "Jane Doe",
  "credentials": {
    "0": {"@type": "Password", "secret": "correct horse battery staple"}
  },
  "aliases": {
    "0": {"name": "j.doe", "domainId": "b"}
  },
  "memberGroupIds": {"d": true},
  "roles": {"@type": "User"},
  "permissions": {"@type": "Inherit"},
  "quotas": {"maxDiskQuota": 5368709120},
  "encryptionAtRest": {"@type": "Disabled"}
}