Authentication Policy

Dovecot supports interfacing with an 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 its own, this feature adds support for making cluster-wide decisions to make it easier to deter and defeat brute force attacks.

Configuration

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.

auth_policy_check_after_auth

Default	yes
Value	boolean
See Also	auth_policy_server_url

Do policy lookup after authentication is completed?

auth_policy_check_before_auth

Default	yes
Value	boolean
See Also	auth_policy_server_url

Do policy lookup before authentication is started?

auth_policy_hash_mech

Default	sha256
Value	string
Allowed Values	md4md5sha1sha256sha512
See Also	auth_policy_server_url

Hash mechanism to use for password.

auth_policy_hash_nonce

Default	[None]
Value	string
See Also	auth_policy_server_url

Cluster-wide nonce to add to hash.

This should contain a secret randomly generated string, which is the same for each Dovecot server within the cluster.

REQUIRED configuration when you want to use authentication policy.

Example:

auth_policy_hash_nonce = <localized_random_string>

auth_policy_hash_truncate

Default	12
Value	unsigned integer
See Also	auth_policy_server_url
Advanced Setting; this should not normally be changed.

How many bits to use from password hash when reporting to policy server.

auth_policy_log_only

Default	no
Value	boolean
See Also	auth_policy_server_url

Only log what the policy server response would do?

If yes, no request is made to the policy server.

auth_policy_reject_on_fail

Default	no
Value	boolean
See Also	auth_policy_server_url

If policy request fails for some reason, should users be rejected?

auth_policy_report_after_auth

Default	yes
Value	boolean

Report authentication result?

If no, there will be no report for the authentication result.

auth_policy_request_attributes

Default	login=%{requested_username} pwhash=%{hashed_password} remote=%{rip} device_id=%{client_id} protocol=%s session_id=%{session} fail_type=%{fail_type}
Value	string
See Also	auth_policy_server_url
Changes	Changed: 3.0.0 Default has changed.

Request attributes specification.

Variables that can be used for this setting:

• Authentication variables

• %{hashed_password}

  • Truncated auth policy hash of username and password

• %{requested_username}

  • Logged in user. Same as %{user}, except for master user logins the same as %{login_user}.

auth_policy_server_api_header

Default	[None]
Value	string
See Also	auth_policy_server_url

Header and value to add to request (for API authentication).

Note: See https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

This can be used when you are using the weakforced policy server and the web listener password is "super":

$ echo -n wforce:super | base64
d2ZvcmNlOnN1cGVy

Then the correct value for this setting is:

auth_policy_server_api_header = Authorization: Basic d2ZvcmNlOnN1cGVy

auth_policy_server_timeout_msecs

Default	2000
Value	time (milliseconds)

Auth policy server request timeout.

auth_policy_server_url

Default	[None]
Value	URL

URL of the policy server.

URL is appended with ?command=allow/report. If URL ends with &, the ? is not appended.

REQUIRED configuration when you want to use authentication policy.

Example:

auth_policy_server_url = http://example.com:4001/

Required Minimum Configuration

auth_policy_server_url = http://example.com:4001/
auth_policy_hash_nonce = localized_random_string

# OPTIONAL settings
#auth_policy_server_api_header = Authorization: Basic <base64-encoded value>
#auth_policy_server_timeout_msecs = 2000
#auth_policy_hash_mech = sha256
#auth_policy_request_attributes = login=%{requested_username} pwhash=%{hashed_password} remote=%{rip} device_id=%{client_id} protocol=%s
#auth_policy_reject_on_fail = no
#auth_policy_hash_truncate = 12
#auth_policy_check_before_auth = yes
#auth_policy_check_after_auth = yes
#auth_policy_report_after_auth = yes

Password Hash Algorithm

To generate the hash, you concatenate nonce, login name, nil byte, and 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 remaining 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.

Examples:

Configuration

login=%{orig_username} pwhash=%{hashed_password} remote=%{real_rip} attrs/ja3=%{ssl_ja3_hash} attrs/extra=value

JSON Result

{
    "login": "john.doe",
    "pwhash": "1234",
    "remote": "127.0.0.1",
    "attrs": {
      "extra":"value",
      "ja3":"md5 hash"
    }
}

Configuration

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

JSON Result

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

IMAP ID

You can include IMAP ID command result in auth policy requests, by using %{client_id}, which will expand to IMAP ID command arglist.

You must set imap_id_retain = yes for this to work.

List of Fields

All fields supported by Authentication variables can be used.

In addition, you can use following fields:

hashed_password

User's password hashed with password hash algorithm.

requested_username

Username for regular logins.

For master user logins, this is the requested login username (not the master username).

fail_type

Added: 3.0.0

The reason request failed. Results:

Result	Description
internal	Dovecot internal processing error.
credentials	The user's credentials were wrong.
account	Account is not known.
expired	User's password is expired.
disabled	Account was disabled.
policy	Login was rejected by policy server.

tls

TLS protection level.

Always available.

policy_reject

Deprecated: 3.0.0

Obsolete field indicating whether the request was rejected by policy server.

success

Overall indicator whether the request succeeded or not.

Expected Response

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

status values are explained below.

Mode of Operation

Auth Policy check: Authentication 'Before' userdb/passdb

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.

status result values:

• -1: Reject

• 0: Accept

• (Any other positive value): Tarpit for this number of seconds.

Auth Policy Check: Authentication 'After' Successful userdb/passdb Lookup

Second lookup is done after authentication succeeds.

The command used here is allow and will appear on the URL as command=allow.

status result values:

• -1: Authentication fail

• >= 0: Authentication succeed

Auth Policy Check: Reporting After Authentication Succeeds

A report request is sent at end of authentication.

The command used here is report and will appear on the URL as command=report.

The status result value is ignored.

The JSON request is sent with two additional attributes:

success

Boolean true/false depending on whether the overall authentication succeeded

policy_reject

Boolean true/false whether the failure was due to policy server

Compatible Auth Policy Servers

• OX Abuse Shield