Module ngx_mail_auth_http_module

Directives

Sets the URL of the HTTP authentication server. The protocol is described below.

Allows to append the specified header to requests to the authentication server. Can be used as a shared secret to verify that the request came in from nginx. For example:

auth_http_header X-Auth-Key "secret_string";

auth_http_timeout 60s;

Protocol

The HTTP is used to communicate with the authentication server. The data in the response body is ignored, information is passed only in headers.

Requests and responses examples:

Request:

GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain # plain or apop or cram-md5
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap # imap, pop3 or smtp
Auth-Login-Attempt: 1 # attempt count in a single session
Client-IP: 192.168.1.1

Good response:

HTTP/1.0 200 OK # this line is ignored
Auth-Status: OK
Auth-Server: 10.1.1.1
Auth-Port: 143

Bad response:

HTTP/1.0 200 OK # this line is ignored
Auth-Status: Invalid login or password
Auth-Wait: 3 # wait for 3 seconds before returning an error to the client

If there is no the “Auth-Wait” header, the connection will be closed after returning an error. The current implementation allocates memory per each authentication attempt, which is freed only at the end of a session. Therefore a number of invalid authentication attempts in a single session must be limited — the server must response without the “Auth-Wait” header after 10-20 attempts (see the “Auth-Login-Attempt” header).

When using the APOP or CRAM-MD5 request-response will look like:

GET /auth HTTP/1.0
Host: localhost
Auth-Method: apop
Auth-User: user
Auth-Salt: <238188073.1163692009@mail.example.com>
Auth-Pass: auth_response
Auth-Protocol: imap
Auth-Login-Attempt: 1 # attempt count in a single session
Client-IP: 192.168.1.1

Good response:

HTTP/1.0 200 OK # this line is ignored
Auth-Status: OK
Auth-Server: 10.1.1.1
Auth-Port: 143
Auth-Pass: plain-text-pass

For the SMTP, the response additionally takes into account the “Auth-Error-Code” header — it is used as a response code if exists. Otherwise the code 535 5.7.0 will be added to the “Auth-Status” by default.

For example, if the following response is received from the authentication server:

HTTP/1.0 200 OK
Auth-Status: Temporary server problem, try again later
Auth-Error-Code: 451 4.3.0
Auth-Wait: 3

then the SMTP client will be given an error

451 4.3.0 Temporary server problem, try again later