Password Databases

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

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 Authentication/MultipleDatabases).

Success/failure databases

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 mechanisms.

Lookup databases

password_noscheme: Like "password", but if a password begins with "{", assume it belongs to the password itself instead of treating it as a scheme 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").

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 extra fields) that are used, unless overwritten by the passdb backend. They are in format key=value key2=value2 .... The values can contain %variables.

override_fields: Same as default_fields, but instead of providing the default values, these values override what the passdb backend returned.

auth_verbose: If this is explicitly set to yes or no, it overrides the global auth_verbose setting. (However, auth_debug=yes overrides the auth_verbose setting.) (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 database. 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.

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

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.