Auth HTTP#

通过外部 HTTP 服务器(即身份验证服务器)对邮件客户端进行身份验证,该服务器同时为每个会话选择后端。对于邮件代理,Angie 没有其他后端地址来源,因此 mail 块中的每个 server 都需要 auth_http 指令(参见 工作原理)。

配置示例#

Angie 将 IMAP 会话代理到两个后端之一,具体由用户名中的域名决定,并通过自身 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;
        }
    }
}

这个身份验证服务器只负责为客户端选择后端,并不检查客户端的密码:Angie 用客户端发来的密码登录后端,由后端接受或拒绝。如果后端拒绝,proxy_pass_error_message 会把后端的应答传递给客户端,随后 Angie 关闭连接。来自其他任何域名的用户会收到 Invalid login or password 错误。在一个会话的前九次尝试中,Angie 会把该错误延迟三秒再发送,并让客户端重试;从第十次尝试起,Angie 立即发送错误并关闭连接。

指令#

auth_http#

语法

auth_http uri;

默认值

—

上下文

mail, server

设置身份验证服务器的 URL:IP 地址或域名,可附带端口(默认为 80)和 URI;也可以是 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 header value;

默认值

—

上下文

mail, server

将指定的头字段添加到发送给身份验证服务器的请求中。该指令可以指定多次。当且仅当当前级别上没有定义 auth_http_header 指令时,这些指令才会从上一配置级别继承。

使用保密头字段,身份验证服务器可以检查请求是否来自 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 格式、经 URL 编码的客户端证书。仅当启用了 ssl_verify_client 且客户端出示了证书时,Angie 才会发送该头字段。

auth_http_timeout#

语法

auth_http_timeout 时间;

默认值

auth_http_timeout 60s;

上下文

mail, server

设置与身份验证服务器交互的超时时间:Angie 必须在此时间内完成连接、发送请求并接收响应头。

协议#

每次登录尝试时,Angie 都会新建一个到身份验证服务器的连接,并针对 auth_http 所设的 URI 发送 HTTP/1.0 GET 请求;客户端的数据通过请求头传递。未经身份验证就发送邮件的 SMTP 客户端,会在发出 RCPT TO 命令后触发该请求。

身份验证服务器通过响应头作答。Angie 忽略状态码和响应体。状态行、响应头及其后的空行合计必须不超过 1024 字节:超出时,会话按 错误 一节所述失败,客户端甚至可能要等到 auth_http_timeout 到期才会收到错误。

请求头#

Host

auth_http URL 中的主机;对于 UNIX 域套接字为 localhost。

Auth-Method

客户端使用的身份验证方法:plain(AUTH LOGIN、IMAP 的 LOGIN 命令以及 POP3 的 USER 和 PASS 也使用此值)、apop、cram-md5、external、xoauth2 或 oauthbearer;未经身份验证就发送邮件的 SMTP 客户端为 none。

Auth-User

客户端发送的用户名;对于 XOAUTH2 和 OAUTHBEARER,则是初始 SASL 响应中的用户标识。

Auth-Pass

客户端发送的密码;APOP 和 CRAM-MD5 为客户端的摘要;XOAUTH2 和 OAUTHBEARER 为持有者令牌;EXTERNAL 为空。

Auth-Salt

仅用于 APOP 和 CRAM-MD5:Angie 发送给客户端的质询。

Auth-Protocol

imap、pop3 或 smtp。

Auth-Login-Attempt

客户端在会话中的登录尝试序号,从 1 开始。

Client-IP

客户端的 IP 地址。

Client-Host

仅用于 SMTP:由 resolver 找到的客户端主机名;如果未配置解析器、名称不存在,或名称解析出的地址不是客户端的地址,则为 [UNAVAILABLE];发生其他解析错误时为 [TEMPUNAVAIL]。

Auth-SMTP-Helo, Auth-SMTP-From, Auth-SMTP-To

仅当 Auth-Method: none 时:客户端 HELO 或 EHLO 命令的参数,以及客户端完整的 MAIL FROM 和 RCPT TO 命令。

Proxy-Protocol-Addr, Proxy-Protocol-Port, Proxy-Protocol-Server-Addr, Proxy-Protocol-Server-Port

仅当设置了 listen 的 proxy_protocol 参数时:PROXY 协议头中的客户端地址和端口以及服务器地址和端口。

Auth-SSL

客户端连接使用 SSL/TLS(包括通过 STARTTLS 升级后)时为 on。

Auth-SSL-Protocol, Auth-SSL-Cipher

客户端 SSL/TLS 连接的协议和密码套件。

Auth-SSL-Verify

仅当启用了 ssl_verify_client 时:客户端证书的验证结果,为 SUCCESS、FAILED:reason,或客户端未出示证书时的 NONE。FAILED 仅在 ssl_verify_client optional_no_ca 下出现,且仅用于自签名证书或颁发者未知的证书;其他任何验证失败都会在发出请求之前结束会话。

Auth-SSL-Subject, Auth-SSL-Issuer, Auth-SSL-Serial, Auth-SSL-Fingerprint

仅当启用了 ssl_verify_client 且客户端出示了证书时:证书的主题和颁发者 DN(采用 RFC 2253 格式)、序列号和 SHA-1 指纹。

Auth-SSL-Cert

条件同上,并且还启用了 auth_http_pass_client_cert 时:PEM 格式的客户端证书。

由 auth_http_header 设置的头字段排在这些请求头之后。在 Auth-User、Auth-Pass 和 Auth-SSL-Cert 中,Angie 会把空格、百分号和控制字符替换为 %XX 转义序列,因此身份验证服务器在使用这些值之前必须先解码。

响应头#

Auth-Status

OK 表示接受客户端。WAIT 使 Angie 在 Auth-Wait 指定的延迟之后重复发送请求。其他任何值都表示拒绝客户端,并成为发送给客户端的错误消息。Angie 区分大小写地匹配 OK 和 WAIT;没有 Auth-Status 的响应同样接受客户端。

Auth-Server

在 OK 响应中:后端的 IP 地址。不接受域名。

Auth-Port

在 OK 响应中:后端的端口。

Auth-User

在 OK 响应中:用于登录后端的用户名,取代客户端发送的用户名。

Auth-Pass

在 OK 响应中:用于登录后端的密码,取代客户端发送的密码。对 APOP、CRAM-MD5 和 EXTERNAL 客户端必须提供:IMAP 和 POP3 始终必须,SMTP 则在启用 proxy_smtp_auth 时必须。

Auth-Wait

以秒为单位的延迟,仅在拒绝客户端或 WAIT 时使用。拒绝客户端时,Angie 等待这么长时间后发送错误,并让客户端重试;没有该头字段时,Angie 立即发送错误并关闭连接。使用 WAIT 时,该值是重复请求之前的延迟。

Auth-Error-Code

仅用于 SMTP,拒绝客户端时:位于错误消息之前的应答码和增强状态码;默认为 535 5.7.0。

Auth-Error-SASL

仅用于 XOAUTH2 和 OAUTHBEARER,拒绝客户端时:Angie 在发送错误之前发给客户端的 SASL 质询。

Angie 忽略其他响应头。但头名称只能包含拉丁字母、数字和连字符:名称中含有任何其他字符(例如下划线)时,Angie 会拒绝整个响应。

请求和响应示例#

登录成功#

IMAP 客户端使用用户名和密码登录:

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

Angie 连接到 198.51.100.1:143,并使用客户端的用户名和密码登录。

登录失败和重试#

身份验证服务器拒绝该客户端:

HTTP/1.0 200 OK
Auth-Status: Invalid login or password
Auth-Wait: 3

三秒后,Angie 以客户端所用协议要求的形式向客户端发送该错误(POP3 中为 -ERR Invalid login or password,IMAP 中为带标签的 NO 应答,SMTP 中为 535 5.7.0 Invalid login or password),并让客户端重试;下一次请求携带递增后的 Auth-Login-Attempt。

Angie 为每次尝试分配内存,并且仅在会话结束时释放,因此身份验证服务器应限制尝试次数:在 10-20 次尝试之后,身份验证服务器应在响应中省去 Auth-Wait,这样 Angie 就会关闭连接。

对于 SMTP,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

会使 SMTP 客户端收到下面的错误:

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#

使用 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: pop3
Auth-Login-Attempt: 1
Client-IP: 192.0.2.42

Angie 登录后端时只使用明文命令,因此身份验证服务器要自己检查摘要,并返回用户的密码:

HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 110
Auth-Pass: plain-text-pass

EXTERNAL 同样要求响应中带有 Auth-Pass,而 EXTERNAL 请求中的 Auth-Pass 为空。

XOAUTH2 和 OAUTHBEARER#

身份验证成功时,Angie 用持有者令牌作为密码登录后端,除非响应中带有 Auth-Pass。

错误响应还可以包含 Auth-Error-SASL。Angie 把该头字段的值作为额外的 SASL 质询发送给客户端(SMTP 使用 334,IMAP 和 POP3 使用 +)。客户端作出响应(XOAUTH2 为空行,OAUTHBEARER 为 AQ==)之后,Angie 返回 Auth-Status 中的错误。

不带身份验证的 SMTP#

如果 smtp_auth 包含 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 客户端连接#

通过 TLS 连接的 IMAP 客户端,并且启用了 ssl_verify_client:

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

错误#

如果与身份验证服务器的交互失败,或者身份验证服务器的响应虽然接受了客户端,却无法使用,Angie 会向客户端发送内部错误并关闭连接:

IMAP

* BAD internal server error

POP3

-ERR internal server error

SMTP

451 4.3.2 Internal server error

原因记录在 error_log 中:

timed out

交互未在 auth_http_timeout 内完成。

sent invalid response

状态行以 CR 结尾,其后没有 LF。

sent invalid header in response

某个响应头格式错误,或头名称中包含拉丁字母、数字和连字符以外的字符。

did not send server or port

响应没有拒绝客户端,但缺少 Auth-Server 或 Auth-Port,为错误 URI 返回的错误页面就属于这种情况。

sent invalid server address

Auth-Server 不是 IP 地址。

sent invalid server port

Auth-Port 不是 1 到 65535 之间的数字。

did not send password

IMAP 或 POP3 的响应接受了 APOP、CRAM-MD5 或 EXTERNAL 客户端,但没有 Auth-Pass。

no password available

SMTP 的响应接受了 CRAM-MD5 或 EXTERNAL 客户端,但没有 Auth-Pass,同时启用了 proxy_smtp_auth。

除 no password available 外,所有这些消息都以 auth http server 和身份验证服务器的地址开头。如果 Angie 无法连接到身份验证服务器,日志中的 connect() to ... failed、send() failed 或 recv() failed 消息会显示系统错误。状态行、响应头和空行合计超过 1024 字节的响应,最多只会被记录为 timed out,也可能完全不记录。