Auth HTTP#

该模块通过在处理主请求之前发送额外的 HTTP 请求来实现基于子请求的认证。如果子请求返回 2xx 状态，主请求将继续处理；如果返回 401 或 403，相应的错误将发送给用户，而任何其他响应都会触发 500 错误。这种方法通常用于将认证委托给外部服务，统一跨应用程序的认证，或与 OAuth 或 LDAP 等第三方系统集成。

指令#

auth_http#

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

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

auth_http_header#

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

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

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;`
上下文	mail, server

将 Auth-SSL-Cert 头部与 PEM 格式（urlencoded）的客户端证书附加到发送给认证服务器的请求中。

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/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 客户端连接，添加 Auth-SSL 头部，并且 Auth-SSL-Verify 将包含客户端证书验证的结果，如果启用：SUCCESS，FAILED:reason，以及如果没有证书则为 NONE。

当存在客户端证书时，其详细信息将通过以下请求头部传递：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 头部传递。请求将如下所示：

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。