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";
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:
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
HTTP/1.0 200 OK # this line is ignored Auth-Status: OK Auth-Server: 10.1.1.1 Auth-Port: 143
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: <email@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
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