<!-- review: finished -->

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

# Auth HTTP

The module enables subrequest-based authentication by sending an additional HTTP
request before processing the main request. If the subrequest returns a 2xx
status, the main request proceeds; if it returns 401 or 403, the appropriate
error is sent to the user, while any other response triggers a 500 error. This
approach is typically used to delegate authentication to external services,
unify authentication across applications, or integrate with third-party systems
like OAuth or LDAP.

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

## Directives

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

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

### auth_http

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http` uri;   |
|------------------------------------------------------------------------------------------|--------------------|
| Default                                                                                  | —                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server       |

Sets the URL of the HTTP authentication server. The protocol is described [below](#v-m-protocol).

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

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

### auth_http_header

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_header` header value;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | —                                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                       |

Appends the specified header to requests sent to the authentication server. This header can be used as a shared secret to verify that the request comes from Angie. For example:

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

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_pass_client_cert` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------------------------|
| Default                                                                                  | `auth_http_pass_client_cert off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                 |

Appends the `Auth-SSL-Cert` header with the [client certificate](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client) in PEM format (urlencoded) to requests sent to the authentication server.

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

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

### auth_http_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_timeout` time;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `auth_http_timeout 60s;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                |

Sets the timeout for communication with the authentication server.

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

## Protocol

The HTTP protocol is used to communicate with the authentication server. The data in the response body is ignored; information is passed only in the headers.

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

### Examples of requests and responses:

Request:

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

Good response:

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

Bad response:

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

If there is no `Auth-Wait` header, an error will be returned and the connection will be closed. The current implementation allocates memory for each authentication attempt. The memory is freed only at the end of a session. Therefore, the number of invalid authentication attempts in a single session must be limited — the server must respond without the `Auth-Wait` header after 10-20 attempts (the attempt number is passed in the `Auth-Login-Attempt` header).

When APOP or CRAM-MD5 is used, the request-response will look as follows:

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

Good response:

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

When XOAUTH2 or OAUTHBEARER is used, the `Auth-User` and `Auth-Pass`
headers contain the user identity and bearer token extracted from the initial
SASL response.

If the `Auth-User` header exists in the response, it overrides the username used to authenticate with the backend.

For SMTP, the response additionally takes into account the `Auth-Error-Code` header — if it exists, it is used as a response code in case of an error. Otherwise, the 535 5.7.0 code will be added to the `Auth-Status` header by default.

For XOAUTH2 and OAUTHBEARER, an error response may also include the
`Auth-Error-SASL` header. Its value is sent to the client as an additional
SASL challenge (SMTP: 334, IMAP/POP3: +). After the client responds with an
empty response for XOAUTH2 or `AQ==` for OAUTHBEARER, the error from
`Auth-Status` is returned.

For example, if the following response is received from the authentication server:

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

then the SMTP client will receive an error

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

If proxying SMTP does not require authentication, the request will look as follows:

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

For SSL/TLS client connections, the `Auth-SSL` header is added, and `Auth-SSL-Verify` will contain the result of client certificate verification, if [enabled](https://en.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client): `SUCCESS`, `FAILED:reason`, and `NONE` if a certificate was not present.

When the client certificate was present, its details are passed in the following request headers: `Auth-SSL-Subject`, `Auth-SSL-Issuer`, `Auth-SSL-Serial`, and `Auth-SSL-Fingerprint`. If [auth_http_pass_client_cert](#m-auth-http-pass-client-cert) is enabled, the certificate itself is passed in the `Auth-SSL-Cert` header. The protocol and cipher of the established connection are passed in the `Auth-SSL-Protocol` and `Auth-SSL-Cipher` headers. The request will look as follows:

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

When the [PROXY protocol](https://en.angie.software//angie/docs/configuration/modules/mail/index.md#m-listen-ssl-proxy) is used, its details are passed in the following request headers: `Proxy-Protocol-Addr`, `Proxy-Protocol-Port`, `Proxy-Protocol-Server-Addr`, and `Proxy-Protocol-Server-Port`.