This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.

Authentication policy support

Dovecot supports (v2.2.25+) external authentication policy server. This server can be used to decide whether the connecting user is permitted, tarpitted or outright rejected. While dovecot can do tarpitting and refusal on it's own, this adds support for making cluster-wide decisions to make it easier to deter and defeat bruteforce attacks.


The auth-policy server is a core feature and does not require plugin(s) to work. To activate this feature, you need to configure it.

Default values

Password hash algorithm

To generate the hash, you concatenate nonce, login name, nil byte, password and run it through the hash algorithm once. The hash is truncated when truncation is set to non-zero. The hash is truncated by first choosing bits from MSB to byte boundary (rounding up), then right-shifting the remainding bits.

hash = H(nonce||user||'\x00'||password)
bytes = round8(bits*8)
hash = HEX(hash[0:bytes] >> (bytes-bits*8))

Request attributes

Auth policy server requests are JSON requests. The JSON format can be specified with auth_policy_request_attributes. The syntax is key=value pairs, and key can contain one or more / to designate that a JSON object should be made. For example:

login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip}




login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip} attrs/cos=%{userdb:cos}


{"login":"john.doe","pwhash":"1234","remote":"", "attrs":{"cos":"premium"}}


{"status":-1,"message":"go away"}

Mode of operation

Auth policy check is done twice during the authentication. First query is done before password and user databases are consulted. This means that any userdb/passdb attributes are left empty. The command used here is 'allow' and will appear on the URL as command=allow. If the result here is negative, the user authentication is failed, if the result is positive, the user is tarpitted for as many seconds.

Second allow lookup is done if authentication succeeds, and if the result here is negative, the authentication is failed. If the result is non-negative, the user authentication succeeds.

Finally, a report lookup is done, and the result is ignored. Here the JSON request is added with two attributes, success and wf_reject. The first is true/false depending whether the overall authentication succeeded, and the second one is whether the failure was due to policy server.