Module ngx_mail_auth_http

模块 ngx_mail_auth_http_module

指令
     auth_http
     auth_http_header
     auth_http_pass_client_cert
     auth_http_timeout
协议

指令

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

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

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

将指定的头部添加到发送到认证服务器的请求中。该头部可用作共享密钥，以验证请求是否来自 nginx。例如：

auth_http_header X-Auth-Key "secret_string";

语法:	`auth_http_pass_client_cert on \| off;`
默认值:	auth_http_pass_client_cert off;
上下文:	`mail`, `server`

该指令出现于版本 1.7.11。

将以 PEM 格式（urlencode）的客户端证书附加到发送到认证服务器的请求中，以“Auth-SSL-Cert”头部的形式。

语法:	`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/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

如果没有“Auth-Wait”头部，将返回错误并关闭连接。当前实现为每个认证尝试分配内存。该内存仅在会话结束时释放。因此，单个会话中无效的认证尝试次数必须受到限制 — 服务器必须在 10-20 次尝试后（尝试编号通过“Auth-Login-Attempt”头部传递）在没有“Auth-Wait”头部的情况下响应。

当使用 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”头部，则该头部将覆盖用于与后端进行身份验证的用户名。

对于 SMTP，响应还考虑了“Auth-Error-Code”头 —— 如果存在，则在出现错误时将其用作响应代码。否则，“Auth-Status”头将添加 535 5.7.0 代码。

例如，如果从身份验证服务器收到以下响应：

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: <postmaster@mail.example.com>

对于 SSL/TLS 客户端连接（1.7.11），将添加“Auth-SSL”头，“Auth-SSL-Verify”将包含客户端证书验证结果，如果启用：已启用：“成功”，“失败：原因”，以及如果没有证书，则为“无”。

在版本 1.11.7 之前，“失败”结果不包含 原因 字符串。

当客户端证书存在时，其详细信息将在以下请求头中传递：“Auth-SSL-Subject”、“Auth-SSL-Issuer”、“Auth-SSL-Serial” 和 “Auth-SSL-Fingerprint”。如果启用了 auth_http_pass_client_cert，则证书本身将在 “Auth-SSL-Cert” 头中传递。已建立连接的协议和密码将在 “Auth-SSL-Protocol” 和 “Auth-SSL-Cipher” 头中传递（1.21.2）。请求将如下所示：

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

当使用 PROXY 协议时，其详细信息将在以下请求头中传递：“Proxy-Protocol-Addr”、“Proxy-Protocol-Port”、“Proxy-Protocol-Server-Addr” 和 “Proxy-Protocol-Server-Port”（1.19.8）。