<!-- review: finished -->

<a id="mail-auth-http"></a>

# Auth HTTP

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

<a id="directives-57"></a>

## 指令

<a id="index-0"></a>

<a id="m-auth-http"></a>

### auth_http

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http` uri;   |
|--------------------------------------------------------------------------------------|--------------------|
| 默认值                                                                                  | —                  |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server       |

设置 HTTP 认证服务器的 URL。协议描述见 [下文](#v-m-protocol)。

<a id="index-1"></a>

<a id="m-auth-http-header"></a>

### auth_http_header

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_header` header value;   |
|--------------------------------------------------------------------------------------|------------------------------------|
| 默认值                                                                                  | —                                  |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                       |

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

```nginx
auth_http_header X-Auth-Key "secret_string";
```

<a id="index-2"></a>

<a id="m-auth-http-pass-client-cert"></a>

### auth_http_pass_client_cert

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_pass_client_cert` `on` | `off`;   |
|--------------------------------------------------------------------------------------|----------------------------------------------|
| 默认值                                                                                  | `auth_http_pass_client_cert off;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                 |

将 `Auth-SSL-Cert` 头部与 PEM 格式(urlencoded)的 [客户端证书](https://cn.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client) 附加到发送给认证服务器的请求中。

<a id="index-3"></a>

<a id="m-auth-http-timeout"></a>

### auth_http_timeout

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_timeout` time;   |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值                                                                                  | `auth_http_timeout 60s;`    |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                |

设置与认证服务器通信的超时时间。

<a id="v-m-protocol"></a>

## 协议

HTTP 协议用于与认证服务器通信。响应体中的数据被忽略,仅在头部传递信息。

<a id="examples-of-requests-and-responses"></a>

### 请求和响应示例:

请求:

```console
GET /auth HTTP/1.0
Host: localhost
Auth-Method: plain # plain/apop/cram-md5/external/xoauth2/oauthbearer/none
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
```

成功响应:

```console
HTTP/1.0 200 OK
Auth-Status: OK
Auth-Server: 198.51.100.1
Auth-Port: 143
```

失败响应:

```console
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 时,请求响应如下所示:

```console
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
```

成功响应:

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

当使用 XOAUTH2 或 OAUTHBEARER 时,:samp:Auth-User 和 `Auth-Pass` 头部包含从初始 SASL 响应中提取的用户身份和持有者令牌。

如果响应中存在 `Auth-User` 头部,它将覆盖用于与后端认证的用户名。

对于 SMTP,响应还会考虑 `Auth-Error-Code` 头部——如果存在,它将在错误情况下用作响应代码。否则,\`535 5.7.0\` 代码将默认添加到 `Auth-Status` 头部。

对于 XOAUTH2 和 OAUTHBEARER,错误响应还可能包含 `Auth-Error-SASL` 头部。其值作为额外的 SASL 质询发送给客户端(SMTP:334,IMAP/POP3:+)。在客户端对 XOAUTH2 响应空响应或对 OAUTHBEARER 响应 `AQ==` 后,返回来自 `Auth-Status` 的错误。

例如,如果从认证服务器收到以下响应:

```console
HTTP/1.0 200 OK
Auth-Status: Temporary server problem, try again later
Auth-Error-Code: 451 4.3.0
Auth-Wait: 3
```

则 SMTP 客户端将收到错误

```console
451 4.3.0 Temporary server problem, try again later
```

如果代理 SMTP 不需要认证,请求将如下所示:

```console
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` 将包含客户端证书验证的结果,如果 [启用](https://cn.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client):`SUCCESS`,:samp:FAILED:reason,以及如果没有证书则为 `NONE`。

当存在客户端证书时,其详细信息将通过以下请求头部传递:`Auth-SSL-Subject`、`Auth-SSL-Issuer`、`Auth-SSL-Serial` 和 `Auth-SSL-Fingerprint`。如果启用了 [auth_http_pass_client_cert](#m-auth-http-pass-client-cert),证书本身将通过 `Auth-SSL-Cert` 头部传递。已建立连接的协议和密码将通过 `Auth-SSL-Protocol` 和 `Auth-SSL-Cipher` 头部传递。请求将如下所示:

```console
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 协议](https://cn.angie.software//angie/docs/configuration/modules/mail/index.md#m-listen-ssl-proxy) 时,其详细信息将通过以下请求头部传递:`Proxy-Protocol-Addr`、`Proxy-Protocol-Port`、`Proxy-Protocol-Server-Addr` 和 `Proxy-Protocol-Server-Port`。