一、模块启用与示例配置
mail {
server {
listen 143; # IMAP
protocol imap;
auth_http http://auth.local/auth;
# 可选：传递客户端证书给认证服务
auth_http_pass_client_cert on;
auth_http_timeout 5s;
auth_http_header X-Auth-Key "shared_secret";
}
}
-
auth_http URL;
指定后端认证服务地址（可包含域名、IP、端口以及 path）。 -
auth_http_header name value;
自定义 HTTP Header，通常用作 shared‐secret，防止伪造认证请求。 -
auth_http_pass_client_cert on|off;
将客户端 SSL 证书（PEM 格式，URL 编码）通过Auth-SSL-Cert头一并提交。 -
auth_http_timeout time;
与认证服务器通信超时时间，默认 60 秒。
二、认证协议详解
认证请求使用纯 HTTP/1.0 GET 方法，仅关注 请求头 与 响应头，忽略响应体。请求示例：
GET /auth HTTP/1.0
Host: auth.local
Auth-Method: plain # 登录方式：plain/apop/cram-md5/external/none
Auth-User: alice # 用户名
Auth-Pass: secret123 # 密码或摘要
Auth-Protocol: imap # imap/pop3/smtp
Auth-Login-Attempt: 1 # 当前尝试次数
Client-IP: 203.0.113.5 # 客户端 IP
Client-Host: user.example.org # 客户端主机名
认证服务器若成功，应返回：
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1 # 转发给后端的服务器 IP
Auth-Port: 143 # 转发给后端的端口
失败示例：
HTTP/1.0 200 OK
Auth-Status: Invalid password
Auth-Wait: 3 # 建议客户端等 3 秒再试
- 若响应中无
Auth-Wait，NGINX 会断开连接； - 建议同一会话内失败 10–20 次后，认证服务返回无
Auth-Wait，以免占用过多内存。
三、APOP 与 CRAM-MD5 认证
对于挑战-响应方式（APOP、CRAM-MD5），客户端请求会带上服务端盐值（Auth-Salt）和摘要结果：
GET /auth HTTP/1.0
Host: auth.local
Auth-Method: apop
Auth-User: alice
Auth-Salt: <238188073.1163692009@mail.example.com>
Auth-Pass: md5_digest
Auth-Protocol: imap
Auth-Login-Attempt: 1
Client-IP: 203.0.113.5
认证服务器成功应同样返回 Auth-Status: OK，并可额外携带 Auth-Pass（明文密码），用于后续向后端登录。
四、SMTP 专用逻辑
-
无认证（匿名 SMTP 转发）
当Auth-Method: none时，认证请求会附带Auth-SMTP-Helo、Auth-SMTP-From、Auth-SMTP-To，便于后端策略判断。 -
错误码处理
若响应头含Auth-Error-Code: xyz，则返回给 SMTP 客户端的错误代码即为xyz。否则默认535 5.7.0。
五、TLS 客户端证书透传
开启 auth_http_pass_client_cert on; 后，NGINX 会在请求中附加：
Auth-SSL: on
Auth-SSL-Protocol: TLSv1.3
Auth-SSL-Cipher: TLS_AES_256_GCM_SHA384
Auth-SSL-Verify: SUCCESS|FAILED:reason|NONE
Auth-SSL-Subject: /CN=client
Auth-SSL-Issuer: /CN=CA
Auth-SSL-Serial: 1234ABCD
Auth-SSL-Fingerprint: ab:cd:ef:...
Auth-SSL-Cert: <URL-encoded PEM>
后台可据此决策：如仅允许持有特定证书的客户端。
六、PROXY 协议支持
若在邮件代理层部署了 PROXY 协议，ngx_mail_auth_http_module 也能透传源 IP/端口、代理服务器 IP/端口至认证服务：
Proxy-Protocol-Addr: 10.0.0.2
Proxy-Protocol-Port: 12345
Proxy-Protocol-Server-Addr: 198.51.100.1
Proxy-Protocol-Server-Port: 2525
七、最佳实践与注意事项
- 共享密钥：务必通过
auth_http_header加入签名或 token，校验请求来源； - 限次重试：控制
Auth-Login-Attempt，在后端强制 10–20 次后不返回Auth-Wait； - 超时设置：
auth_http_timeout建议 3–10 秒，防网络抖动导致阻塞； - 安全隔离：认证 URL 搭建在内网或加 TLS + 访问控制，避免外网滥用；
- 日志埋点：在认证服务中记录
Auth-Method、Auth-Login-Attempt、返回耗时，方便排查； - APOP/CRAM-MD5：仅在后端支持时开启，对性能影响极小。
通过 ngx_mail_auth_http_module，NGINX 能以极简配置实现灵活的 HTTP 认证后端接入，不仅统一了多种邮件协议（IMAP/POP3/SMTP）的认证逻辑，也方便与现有的 SSO、OAuth 或自研用户中心无缝集成，让邮件代理既可靠又安全。欢迎在评论区交流更多实战经验！
