Auth HTTP#
通过外部 HTTP 服务器(即身份验证服务器)对邮件客户端进行身份验证,该服务器同时为每个会话选择后端。对于邮件代理,Angie 没有其他后端地址来源,因此 Angie 将 IMAP 会话代理到两个后端之一,具体由用户名中的域名决定,并通过自身 这个身份验证服务器只负责为客户端选择后端,并不检查客户端的密码:Angie 用客户端发来的密码登录后端,由后端接受或拒绝。如果后端拒绝,proxy_pass_error_message 会把后端的应答传递给客户端,随后 Angie 关闭连接。来自其他任何域名的用户会收到 设置身份验证服务器的 URL:IP 地址或域名,可附带端口(默认为 80)和 URI;也可以是 该指令是必需的:如果 将指定的头字段添加到发送给身份验证服务器的请求中。该指令可以指定多次。当且仅当当前级别上没有定义 使用保密头字段,身份验证服务器可以检查请求是否来自 Angie: 将 设置与身份验证服务器交互的超时时间:Angie 必须在此时间内完成连接、发送请求并接收响应头。 每次登录尝试时,Angie 都会新建一个到身份验证服务器的连接,并针对 auth_http 所设的 URI 发送 HTTP/1.0 身份验证服务器通过响应头作答。Angie 忽略状态码和响应体。状态行、响应头及其后的空行合计必须不超过 1024 字节:超出时,会话按 错误 一节所述失败,客户端甚至可能要等到 auth_http_timeout 到期才会收到错误。 auth_http URL 中的主机;对于 UNIX 域套接字为 客户端使用的身份验证方法: 客户端发送的用户名;对于 XOAUTH2 和 OAUTHBEARER,则是初始 SASL 响应中的用户标识。 客户端发送的密码;APOP 和 CRAM-MD5 为客户端的摘要;XOAUTH2 和 OAUTHBEARER 为持有者令牌;EXTERNAL 为空。 仅用于 APOP 和 CRAM-MD5:Angie 发送给客户端的质询。 客户端在会话中的登录尝试序号,从 1 开始。 客户端的 IP 地址。 仅用于 SMTP:由 resolver 找到的客户端主机名;如果未配置解析器、名称不存在,或名称解析出的地址不是客户端的地址,则为 仅当 仅当设置了 listen 的 客户端连接使用 SSL/TLS(包括通过 STARTTLS 升级后)时为 客户端 SSL/TLS 连接的协议和密码套件。 仅当启用了 ssl_verify_client 时:客户端证书的验证结果,为 仅当启用了 ssl_verify_client 且客户端出示了证书时:证书的主题和颁发者 DN(采用 RFC 2253 格式)、序列号和 SHA-1 指纹。 条件同上,并且还启用了 auth_http_pass_client_cert 时:PEM 格式的客户端证书。 由 auth_http_header 设置的头字段排在这些请求头之后。在 在 在 在 在 以秒为单位的延迟,仅在拒绝客户端或 仅用于 SMTP,拒绝客户端时:位于错误消息之前的应答码和增强状态码;默认为 仅用于 XOAUTH2 和 OAUTHBEARER,拒绝客户端时:Angie 在发送错误之前发给客户端的 SASL 质询。 Angie 忽略其他响应头。但头名称只能包含拉丁字母、数字和连字符:名称中含有任何其他字符(例如下划线)时,Angie 会拒绝整个响应。 IMAP 客户端使用用户名和密码登录: 身份验证服务器接受该客户端并指定后端: Angie 连接到 身份验证服务器拒绝该客户端: 三秒后,Angie 以客户端所用协议要求的形式向客户端发送该错误(POP3 中为 Angie 为每次尝试分配内存,并且仅在会话结束时释放,因此身份验证服务器应限制尝试次数:在 10-20 次尝试之后,身份验证服务器应在响应中省去 对于 SMTP, 会使 SMTP 客户端收到下面的错误: 如果身份验证服务器暂时无法决定,它可以响应 警告 每个 使用 APOP 或 CRAM-MD5 时,客户端无需发送密码即可证明自己知道密码,请求中携带质询和客户端的摘要: Angie 登录后端时只使用明文命令,因此身份验证服务器要自己检查摘要,并返回用户的密码: EXTERNAL 同样要求响应中带有 身份验证成功时,Angie 用持有者令牌作为密码登录后端,除非响应中带有 错误响应还可以包含 如果 smtp_auth 包含 身份验证服务器仍然必须在 通过 TLS 连接的 IMAP 客户端,并且启用了 ssl_verify_client: 如果与身份验证服务器的交互失败,或者身份验证服务器的响应虽然接受了客户端,却无法使用,Angie 会向客户端发送内部错误并关闭连接: IMAP POP3 SMTP 原因记录在 error_log 中: 交互未在 auth_http_timeout 内完成。 状态行以 CR 结尾,其后没有 LF。 某个响应头格式错误,或头名称中包含拉丁字母、数字和连字符以外的字符。 响应没有拒绝客户端,但缺少 IMAP 或 POP3 的响应接受了 APOP、CRAM-MD5 或 EXTERNAL 客户端,但没有 SMTP 的响应接受了 CRAM-MD5 或 EXTERNAL 客户端,但没有 除 mail 块中的每个 server 都需要 auth_http 指令(参见 工作原理)。配置示例#
http 块中的一个 location 充当自己的身份验证服务器。请将 mail 块放在 angie.conf 的顶层,将 map 和 server 块放在现有的 http 块内:mail {
auth_http 127.0.0.1:9000/mail-auth;
proxy_pass_error_message on;
server {
listen 143;
protocol imap;
}
}
http {
map $http_auth_user $mail_backend {
~@example\.com$ 192.0.2.10;
~@example\.org$ 192.0.2.20;
}
map $mail_backend $mail_auth_status {
"" "Invalid login or password";
default OK;
}
map $http_auth_login_attempt $mail_auth_wait {
~^[1-9]$ 3;
default "";
}
server {
listen 127.0.0.1:9000;
location = /mail-auth {
add_header Auth-Status $mail_auth_status;
add_header Auth-Server $mail_backend;
add_header Auth-Port 143;
add_header Auth-Wait $mail_auth_wait;
return 204;
}
}
}
Invalid login or password 错误。在一个会话的前九次尝试中,Angie 会把该错误延迟三秒再发送,并让客户端重试;从第十次尝试起,Angie 立即发送错误并关闭连接。指令#
auth_http#
unix: 前缀之后的 UNIX 域套接字路径,例如 unix:/run/mail-auth.sock:/mail-auth。http:// 协议前缀可以省略。不支持 HTTPS:https:// URL 无法通过配置测试,会报 invalid port in auth_http 错误。Angie 在加载配置时解析域名,并向找到的第一个地址发送请求。server 块和 mail 块都没有设置它,配置测试会失败,并报 no "auth_http" is defined for server 错误。请求和响应见 协议。auth_http_header#
auth_http_header 指令时,这些指令才会从上一配置级别继承。auth_http_header X-Auth-Key "secret_string";
auth_http_pass_client_cert#
Auth-SSL-Cert 头字段添加到发送给身份验证服务器的请求中,该头字段的值是 PEM 格式、经 URL 编码的客户端证书。仅当启用了 ssl_verify_client 且客户端出示了证书时,Angie 才会发送该头字段。auth_http_timeout#
协议#
GET 请求;客户端的数据通过请求头传递。未经身份验证就发送邮件的 SMTP 客户端,会在发出 RCPT TO 命令后触发该请求。请求头#
Hostlocalhost。Auth-Methodplain(AUTH LOGIN、IMAP 的 LOGIN 命令以及 POP3 的 USER 和 PASS 也使用此值)、apop、cram-md5、external、xoauth2 或 oauthbearer;未经身份验证就发送邮件的 SMTP 客户端为 none。Auth-UserAuth-PassAuth-SaltAuth-Protocolimap、pop3 或 smtp。Auth-Login-AttemptClient-IPClient-Host[UNAVAILABLE];发生其他解析错误时为 [TEMPUNAVAIL]。Auth-SMTP-Helo,
Auth-SMTP-From,
Auth-SMTP-ToAuth-Method: none 时:客户端 HELO 或 EHLO 命令的参数,以及客户端完整的 MAIL FROM 和 RCPT TO 命令。Proxy-Protocol-Addr,
Proxy-Protocol-Port,
Proxy-Protocol-Server-Addr,
Proxy-Protocol-Server-Portproxy_protocol 参数时:PROXY 协议头中的客户端地址和端口以及服务器地址和端口。Auth-SSLon。Auth-SSL-Protocol,
Auth-SSL-CipherAuth-SSL-VerifySUCCESS、FAILED:reason,或客户端未出示证书时的 NONE。FAILED 仅在 ssl_verify_client optional_no_ca 下出现,且仅用于自签名证书或颁发者未知的证书;其他任何验证失败都会在发出请求之前结束会话。Auth-SSL-Subject,
Auth-SSL-Issuer,
Auth-SSL-Serial,
Auth-SSL-FingerprintAuth-SSL-CertAuth-User、Auth-Pass 和 Auth-SSL-Cert 中,Angie 会把空格、百分号和控制字符替换为 %XX 转义序列,因此身份验证服务器在使用这些值之前必须先解码。响应头#
Auth-StatusOK 表示接受客户端。WAIT 使 Angie 在 Auth-Wait 指定的延迟之后重复发送请求。其他任何值都表示拒绝客户端,并成为发送给客户端的错误消息。Angie 区分大小写地匹配 OK 和 WAIT;没有 Auth-Status 的响应同样接受客户端。Auth-ServerOK 响应中:后端的 IP 地址。不接受域名。Auth-PortOK 响应中:后端的端口。Auth-UserOK 响应中:用于登录后端的用户名,取代客户端发送的用户名。Auth-PassOK 响应中:用于登录后端的密码,取代客户端发送的密码。对 APOP、CRAM-MD5 和 EXTERNAL 客户端必须提供:IMAP 和 POP3 始终必须,SMTP 则在启用 proxy_smtp_auth 时必须。Auth-WaitWAIT 时使用。拒绝客户端时,Angie 等待这么长时间后发送错误,并让客户端重试;没有该头字段时,Angie 立即发送错误并关闭连接。使用 WAIT 时,该值是重复请求之前的延迟。Auth-Error-Code535 5.7.0。Auth-Error-SASL请求和响应示例#
登录成功#
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
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
198.51.100.1:143,并使用客户端的用户名和密码登录。登录失败和重试#
HTTP/1.0 200 OK
Auth-Status: Invalid login or password
Auth-Wait: 3
-ERR Invalid login or password,IMAP 中为带标签的 NO 应答,SMTP 中为 535 5.7.0 Invalid login or password),并让客户端重试;下一次请求携带递增后的 Auth-Login-Attempt。Auth-Wait,这样 Angie 就会关闭连接。Auth-Error-Code 会替换默认的应答码。下面的响应:HTTP/1.0 200 OK
Auth-Status: Temporary server problem, try again later
Auth-Error-Code: 451 4.3.0
Auth-Wait: 3
451 4.3.0 Temporary server problem, try again later
Auth-Status: WAIT。此后,Angie 会在 Auth-Wait 指定的延迟之后再次发送请求,不会告知客户端,且 Auth-Login-Attempt 保持不变。对于 APOP 和 CRAM-MD5,重复的请求携带空的 Auth-Pass,因此身份验证服务器必须在第一次请求时检查摘要并记住结果。只要应答是 WAIT,Angie 就会一直重复请求,即使客户端已经断开连接,所以身份验证服务器应在合理的时间之后不再回答 WAIT。WAIT 响应都必须携带 Auth-Wait。没有它,Angie 会立即重复请求,并在紧凑循环中持续进行,即使身份验证服务器之后回答 OK 也不会停止。APOP、CRAM-MD5 和 EXTERNAL#
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: pop3
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 110
Auth-Pass: plain-text-pass
Auth-Pass,而 EXTERNAL 请求中的 Auth-Pass 为空。XOAUTH2 和 OAUTHBEARER#
Auth-Pass。Auth-Error-SASL。Angie 把该头字段的值作为额外的 SASL 质询发送给客户端(SMTP 使用 334,IMAP 和 POP3 使用 +)。客户端作出响应(XOAUTH2 为空行,OAUTHBEARER 为 AQ==)之后,Angie 返回 Auth-Status 中的错误。不带身份验证的 SMTP#
none,并且客户端未经身份验证就发送邮件,则请求中携带客户端的 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>
Auth-Server 和 Auth-Port 中指定后端;随后 Angie 向该后端重复客户端的 MAIL FROM 和 RCPT TO 命令。SSL/TLS 客户端连接#
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
错误#
* BAD internal server error-ERR internal server error451 4.3.2 Internal server errortimed outsent invalid responsesent invalid header in responsedid not send server or portAuth-Server 或 Auth-Port,为错误 URI 返回的错误页面就属于这种情况。sent invalid server addressAuth-Server 不是 IP 地址。sent invalid server portAuth-Port 不是 1 到 65535 之间的数字。did not send passwordAuth-Pass。no password availableAuth-Pass,同时启用了 proxy_smtp_auth。no password available 外,所有这些消息都以 auth http server 和身份验证服务器的地址开头。如果 Angie 无法连接到身份验证服务器,日志中的 connect() to ... failed、send() failed 或 recv() failed 消息会显示系统错误。状态行、响应头和空行合计超过 1024 字节的响应,最多只会被记录为 timed out,也可能完全不记录。