nginx

Module ngx_mail_auth_http_module


english
русский

简体中文
עברית
日本語
türkçe
italiano

news
about
download
security advisories
documentation
pgp keys
faq
links
books
support
donation

trac
wiki
twitter
nginx.com
blog
Directives
     auth_http
     auth_http_header
     auth_http_timeout
Protocol

Directives

Syntax: auth_http URL;
Default:
Context: mail, server

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

Syntax: auth_http_header header value;
Default:
Context: mail, server

Appends the specified header to requests sent 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";

Syntax: auth_http_timeout time;
Default:
auth_http_timeout 60s;
Context: mail, server

Sets the timeout for communication with the authentication server.

Protocol

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

Examples of requests and responses:

Request:

GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain # plain/apop/cram-md5
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap # imap/pop3/smtp
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org

Good response:

HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143

Bad response:

HTTP/1.0 200 OK
Auth-Status: Invalid login or password
Auth-Wait: 3

If there is no “Auth-Wait” header, 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 respond 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, request-response will look as follows:

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
Client-IP: 192.0.2.42
Client-Host: client.example.org

Good response:

HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
Auth-Pass: plain-text-pass

If the “Auth-User” header exists in the response, it overrides the username used to authenticate with the backend.

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

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

If proxying SMTP does not require authentication, the request will look as follows:

GET /auth HTTP/1.0
Host: localhost
Auth-Method: none
Auth-User:
Auth-Pass:
Auth-Protocol: smtp
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Client-Host: client.example.org
Auth-SMTP-Helo: client.example.org
Auth-SMTP-From: MAIL FROM: <>
Auth-SMTP-To: RCPT TO: <postmaster@mail.example.com>