Mail authentication often looks like a password check followed by a mailbox lookup. Dovecot places username normalization between those steps. The login name a client sends can be transformed before passdb, userdb, and mailbox lookup. A normalization mistake can make two apparent identities resolve to one mailbox or make one identity fail after a password succeeds.

Dovecot's auth_username_format setting changes the username used for authentication lookups. The documentation describes %Ln as lowercasing the username and dropping the domain. It also notes that the same setting can be applied for a passwd-file lookup and that users with multiple domains need a format that preserves the identity they intend to authorize.

Choose the identity you mean

For a system that accepts only local usernames, a normalized local login may be correct.

auth_username_format = %Ln

For a virtual mail environment, domain preservation is usually part of the identity. A lowercased domain and local part may be appropriate, but the resulting value must still map to one account. Do not silently strip a domain if alice@example.net and alice@example.org have separate mailboxes.

The format should be selected from the directory model. If the passdb looks up a full address, send a full address. If the userdb path uses a domain and local part, validate the post-normalization components separately. The storage path must not accept / or parent-directory tokens merely because the authentication directory returned a string.

Keep authorization separate

Successful authentication does not establish that a person should receive a mailbox. Use the directory group or account status as an authorization decision, and test it for disabled, suspended, and departed users. If proxy or master-user modes are present, give them a distinct inventory and logging label. A shared master credential can reach many accounts even when ordinary password checks look normal.

Check the passdb and userdb order. A cached success from an earlier username form can hide a current normalization error. Clear the auth cache during a controlled test, then repeat with mixed case, trailing whitespace, a second domain, an internationalized local part, and a username containing characters the storage layer treats specially.

Log the submitted form only after redaction, the normalized lookup key, the selected directory entry, and the authorization result. Do not log passwords. A mismatch should produce a specific configuration error rather than a generic password failure.

Validate the mailbox mapping

For each test user, inspect the actual mail path, quota scope, aliases, and shared-folder grants. If a normalization change modifies any of those, treat it as a migration. Back up metadata, test a small cohort, and compare message counts and folder names before broad rollout.

The core question is simple: after normalization, which directory identity owns which mailbox, and who is allowed to use it? A clear answer prevents a convenient username transform from becoming an account-alias bug.

References