Password databases (passdb)

Dovecot splits all authentication lookups into two categories:

  • passdb and userdb lookup

passdb lookup most importantly authenticate the user. They also provide any other pre-login information needed for users, such as:

  • Which server user is proxied to.

  • If user should be allowed to log in at all (temporarily or permanently).

Passdb lookups are done by:

Dovecot Director

Dovecot Backend

IMAP & POP3 logins

Yes

Yes

LMTP mail delivery

Yes

Yes

doveadm commands

Yes

Yes

See also User Databases (userdb).

Passwords

The password can be in any format that Dovecot supports, but you need to tell the format to Dovecot because it won’t try to guess it. The SQL and LDAP configuration files have the default_pass_scheme setting for this. If you have passwords in multiple formats, or the passdb doesn’t have such a setting, you’ll need to prefix each password with {<scheme>},

{PLAIN}plaintext-password or {PLAIN-MD5}1a1dc91c907325c69271ddf0c944bc72

Dovecot authenticates users against password databases. It can also be used to configure things like Proxy PasswordDatabase.

You can use multiple databases, so if the password doesn’t match in the first database, Dovecot checks the next one. This can be useful if you want to easily support having both virtual users and also local system users (see Multiple Authentication Databases).

Success/failure database

These databases simply verify if the given password is correct for the user. Dovecot doesn’t get the correct password from the database, it only gets a success or a failure reply. This means that these databases can’t be used with non-plaintext Authentication (SASL) Mechanisms.

Databases that belong to this category are:

Lookup database

Dovecot does a lookup based on the username and possibly other information (e.g. IP address) and verifies the password validity itself. Fields that the lookup can return:

  • password_noscheme: Like password, but if a password begins with {, assume it belongs to the password itself instead of treating it as a Password Schemes prefix. This is usually needed only if you use plaintext passwords.

  • user: Returning a user field can be used to change the username. Typically used only for case changes (e.g. UseR -> user). See User extra field.

  • username: Like user, but doesn’t drop existing domain name (e.g. username=foo for user@domain gives foo@domain).

  • domain: Updates the domain part of the username.

Databases that support looking up only passwords, but no user or extra fields:

  • Passwd-file: /etc/passwd-like file in specified location. See Passwd.

  • Passwd: System users (NSS, /etc/passwd, or similar). See Password Schemes.

  • Shadow: Shadow passwords for system users (NSS, /etc/shadow or similar). See Shadow.

  • Dovecot supports reading all Password Schemes from passwd and shadow databases (if prefix is specified), but that is of course incompatible with all other tools using/modifying the passwords.

  • VPopMail: External software used to handle virtual domains.

Databases that support looking up everything:

See Static Password Database.

Passdb setting

An example passdb passwd-file with its default settings:

passdb {
  driver = passwd-file
  args = scheme=ssha256 /usr/local/etc/passwd.replica
  default_fields =
  override_fields =

  deny = no
  master = no
  pass = no
  skip = never
  mechanisms =
  username_filter =

  result_failure = continue
  result_internalfail = continue
  result_success = return-ok

  # v2.2.24+
  auth_verbose = default
}

First we have the settings that provide content for the passdb lookup:

  • driver: The passdb backend name

  • args: Arguments for the passdb backend. The format of this value depends on the passdb driver. Each one uses different args.

  • default_fields: Passdb fields (and Password database extra fields ) that are used, unless overwritten by the passdb backend. They are in format key=value key2=value2 .... The values can contain %variables. All %variables used here reflect the state BEFORE the passdb lookup.

  • override_fields: Same as default_fields, but instead of providing the default values, these values override what the passdb backend returned. All %variables used here reflect the state AFTER the passdb lookup.

  • auth_verbose: If this is explicitly set to yes or no, it overrides the auth_verbose setting. (However, auth_debug=yes overrides auth_verbose.)

    New in version v2.2.24.

Then we have the settings which specify when the passdb is used:

  • deny: If yes, used to provide denied users database. If the user is found from the passdb, the authentication will fail.

  • master: If yes, used to provide Master users/passwords. The users listed in the master passdb can log in as other users.

  • pass: This is an alias for result_success=continue as described below. This was commonly used together with master passdb to specify that even after a successful master user authentication, the authentication should continue to the actual non-master passdb to lookup the user.

  • skip: Do we sometimes want to skip over this passdb?

  • never

  • authenticated: Skip if an earlier passdb already authenticated the user successfully.

  • unauthenticated: Skip if user hasn’t yet been successfully authenticated by the previous passdbs.

  • mechanisms: Skip, if non-empty and the current auth mechanism is not listed here. Space or comma-separated list of auth mechanisms (e.g. PLAIN LOGIN). Also none can be used to match for a non-authenticating passdb lookup.

    New in version v2.2.30.

  • username_filter: Skip, if non-empty and the username doesn’t match the filter. This is mainly used to assign specific passdbs to specific domains. Space or comma-separated list of username filters that can have * or ? wildcards. If any of the filters matches, the filter succeeds. However, there can also be negative matches preceded by !. If any of the negative filters matches, the filter won’t succeed.

    New in version v2.2.30.

Example:

If the filter is *@example.com *@example2.com !user@example.com, any@example.com or user@example2.com matches but user@example.com won't match.

And finally we can control what happens when we’re finished with this passdb:

  • result_success: What to do if the authentication succeeded (default: return-ok)

  • result_failure: What to do if authentication failed (default: continue)

  • result_internalfail: What to do if the passdb lookup had an internal failure (default: continue). If any of the passdbs had an internal failure and the final passdb also returns continue, the authentication will fail with internal error.

Warning

If multiple passdbs are required (results are merged), it’s important to set result_internalfail=return-fail to them, otherwise the authentication could still succeed but not all the intended extra fields are set.

The result values that can be used:

  • return-ok: Return success, don’t continue to the next passdb.

  • return-fail: Return failure, don’t continue to the next passdb.

  • return: Return earlier passdb’s success or failure, don’t continue to the next passdb. If this was the first passdb, return failure.

  • continue-ok: Set the current authentication state to success, and continue to the next passdb. The following passdbs will skip password verification.

  • continue-fail: Set the current authentication state to failure, and continue to the next passdb. The following passdbs will still verify the password.

  • continue: Continue to the next passdb without changing the authentication state. The initial state is failure. If this was set in result_success, the following passdbs will skip password verification.

Note

when using continue* values on a master passdb (master = yes), execution will jump to the first non-master passdb instead of continuing with the next master passdb (verified at lest up to v2.2.27).