模块 ngx_mail_auth_http_module
指令 auth_http auth_http_header auth_http_pass_client_cert auth_http_timeout 协议 |
指令
语法 |
auth_http |
---|---|
默认值 | — |
上下文 |
mail , server |
设置 HTTP 认证服务器的 URL。该协议在下方描述。
语法 |
auth_http_header |
---|---|
默认值 | — |
上下文 |
mail , server |
将指定的头部字段附加到发送给认证服务器的请求中。这个头部字段可以用作共享密钥,以验证请求是否来自 nginx。例如
auth_http_header X-Auth-Key "secret_string";
语法 |
auth_http_pass_client_cert |
---|---|
默认值 |
auth_http_pass_client_cert off; |
上下文 |
mail , server |
该指令出现在 1.7.11 版本中。
将带有 PEM 格式(urlencoded)的客户端证书的“Auth-SSL-Cert”头部字段附加到发送给认证服务器的请求中。
语法 |
auth_http_timeout |
---|---|
默认值 |
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-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”头部字段,它将覆盖用于与后端认证的用户名。
对于 SMTP,响应还会额外考虑“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: <postmaster@mail.example.com>
对于 SSL/TLS 客户端连接(1.7.11),会添加“Auth-SSL”头部字段,“Auth-SSL-Verify”将包含客户端证书验证的结果,如果启用:“SUCCESS
”、“FAILED:
reason
”;如果证书不存在,则为“NONE
”。
在 1.11.7 版本之前,“FAILED
”结果不包含reason
字符串。
当客户端证书存在时,其详细信息将通过以下请求头部字段传递:“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)。