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;

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