Auth HTTP#
Directives#
auth_http#
Sets the URL of the HTTP authentication server. The protocol is described below.
auth_http_header#
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 Angie. For example:
auth_http_header X-Auth-Key "secret_string";
auth_http_pass_client_cert#
Appends the "Auth-SSL-Cert" header with the client certificate in the PEM format (urlencoded) to requests sent to the authentication server.
auth_http_timeout#
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. Request: Good response: Bad response: 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: Good response: 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: then the SMTP client will receive an error If proxying SMTP does not require authentication, the request will look as follows: For the SSL/TLS client connection, the "Auth-SSL" header is added, and "Auth-SSL-Verify" will contain the result of client certificate verification, if enabled: When the client certificate was present, its details are passed in the following request headers: "Auth-SSL-Subject", "Auth-SSL-Issuer", "Auth-SSL-Serial", and "Auth-SSL-Fingerprint". If auth_http_pass_client_cert is enabled, the certificate itself is passed in the "Auth-SSL-Cert" header. The protocol and cipher of the established connection are passed in the "Auth-SSL-Protocol" and "Auth-SSL-Cipher" headers. The request will look as follows: When the PROXY protocol is used, its details are passed in the following request headers: "Proxy-Protocol-Addr", "Proxy-Protocol-Port", "Proxy-Protocol-Server-Addr", and "Proxy-Protocol-Server-Port".Examples of requests and responses:#
GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain # plain/apop/cram-md5/external
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
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
HTTP/1.0 200 OK
Auth-Status: Invalid login or password
Auth-Wait: 3
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
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
Auth-Pass: plain-text-pass
HTTP/1.0 200 OK
Auth-Status: Temporary server problem, try again later
Auth-Error-Code: 451 4.3.0
Auth-Wait: 3
451 4.3.0 Temporary server problem, try again later
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>
SUCCESS, "FAILED:reason", and NONE if a certificate was not present.GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain
Auth-User: user
Auth-Pass: password
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
Auth-SSL: on
Auth-SSL-Protocol: TLSv1.3
Auth-SSL-Cipher: TLS_AES_256_GCM_SHA384
Auth-SSL-Verify: SUCCESS
Auth-SSL-Subject: /CN=example.com
Auth-SSL-Issuer: /CN=example.com
Auth-SSL-Serial: C07AD56B846B5BFF
Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad