Sets the URL of the HTTP authentication server. The protocol is described below.
Appends the specified header to requests to the authentication server. This header can be used as the shared secret to verify that the request comes 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, and the information is passed only in the headers.
Examples of requests and responses:
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 “Auth-Wait” header in a request, an error will be returned and the connection will be closed. The current implementation allocates memory for each authentication attempt. The memory is freed only at the end of a session. Therefore, the 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 (the attempt number is passed in the “Auth-Login-Attempt” header).
When the APOP or CRAM-MD5 are used, a request-response will look as follows.
GET /auth HTTP/1.0 Host: localhost Auth-Method: apop Auth-User: user Auth-Salt: <firstname.lastname@example.org> 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 — if exists, it is used as a response code. Otherwise, the 535 5.7.0 code will be added to the “Auth-Status”.
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 receive an error
451 4.3.0 Temporary server problem, try again later