nginx中文文档-ngx_mail_auth_http_module

auth_http

语法:auth_http URL
默认:—
上下文:mail, server

设置HTTP认证服务器的URL。协议在下面描述。

auth_http_header

语法:auth_http_header header value
默认:—
上下文:mail, server

追加指定的头到发送给认证服务器的请求中。这个头可以用于验证请求来自于nginx的共享秘密。例如:
auth_http_header X-Auth-Key "secret_string";

auth_http_pass_client_cert

语法:auth_http_pass_client_cert on | off
默认:auth_http_pass_client_cert off
版本:1.7.11+

追加含有PEM格式(url编码过的)客户端证书的“Auth-SSL-Cert”头到发送给认证服务器的请求中。

auth_http_timeout

语法:auth_http_timeout time
默认:auth_http_timeout 60s
上下文:mail, server

设置与认证服务器通信的超时时间。

协议

与认证服务器通信采用的是HTTP协议。响应体中的数据将被忽略,信息只通过头部传递。
请求和响应的例子:
请求:

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

好的响应:

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

如果没有“Auth-Wait”头,会返回一个错误并关闭连接。目前的实现是为每一次认证尝试分配内存。只有在会话结束时内存才会释放。因此,一个会话的无效认证尝试次数需要限制-服务器必须在10-20次尝试后返回不带“Auth-Wait”头(尝试次数会在“Auth-Login-Attempt”头中传递)。
当使用APOP或CRAM-MD5时,请求响应看起来如下:

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

如果响应中存在“Auth-User”头,它会覆盖用于与后端认证的用户名。
对于SMPT,响应会考虑“Auth-Error-Code”头-如果存在,就用于在错误的响应码。否则535 5.7.0代码将被添加到“Auth-Status”头中。
例如,如果下面的响应是从认证服务器收到的:

HTTP/1.0 200 OK
Auth-Status: Temporary server problem, try again later
Auth-Error-Code: 451 4.3.0
Auth-Wait: 3

那么SMTP客户端将收到一个错误。
451 4.3.0 Temporary server problem, try again later
如果代理SMTP不需要认证,请求将看起来如下:

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: 

对于SSL/TLS客户端连接(1.7.11+),“Auth-SSL”头会被添加,“Auth-SSL-Verify”会包含客户端证书验证结果,如果启用则可能是“SUCCESS”或“FAILED”,如果证书没有出现则为“NONE”。当客户端证书出现,它的详情会在以下请求头中传递“Auth-SSL-Subject”, “Auth-SSL-Issuer”, “Auth-SSL-Serial” 以及 “Auth-SSL-Fingerprint”。如果auth_http_pass_client_cert启用,证书本身会通过“Auth-SSL-Cert”头传递。
请求看起来如下:

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-Verify: SUCCESS
Auth-SSL-Subject: /CN=example.com
Auth-SSL-Issuer: /CN=example.com
Auth-SSL-Serial: C07AD56B846B5BFF
Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad