<!-- review: finished -->

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

# Auth HTTP

O módulo habilita autenticação baseada em subrequisição enviando uma requisição HTTP
adicional antes de processar a requisição principal. Se a subrequisição retornar um
status 2xx, a requisição principal prossegue; se retornar 401 ou 403, o erro
apropriado é enviado ao usuário, enquanto qualquer outra resposta dispara um erro 500. Esta
abordagem é tipicamente usada para delegar autenticação para serviços externos,
unificar autenticação entre aplicações, ou integrar com sistemas de terceiros
como OAuth ou LDAP.

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

## Diretivas

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

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

### auth_http

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http` uri;   |
|-------------------------------------------------------------------------------------------|--------------------|
| Padrão                                                                                    | —                  |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server       |

Define a URL do servidor de autenticação HTTP. O protocolo é descrito [abaixo](#v-m-protocol).

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

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

### auth_http_header

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_header` header value;   |
|-------------------------------------------------------------------------------------------|------------------------------------|
| Padrão                                                                                    | —                                  |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                       |

Anexa o cabeçalho especificado às requisições enviadas ao servidor de autenticação. Este cabeçalho pode ser usado como um segredo compartilhado para verificar que a requisição vem do Angie. Por exemplo:

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

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_pass_client_cert` `on` | `off`;   |
|-------------------------------------------------------------------------------------------|----------------------------------------------|
| Padrão                                                                                    | `auth_http_pass_client_cert off;`            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                                 |

Anexa o cabeçalho `Auth-SSL-Cert` com o [certificado do cliente](https://pt.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client) em formato PEM (urlencoded) às requisições enviadas ao servidor de autenticação.

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

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

### auth_http_timeout

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_timeout` time;   |
|-------------------------------------------------------------------------------------------|-----------------------------|
| Padrão                                                                                    | `auth_http_timeout 60s;`    |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | mail, server                |

Define o timeout para comunicação com o servidor de autenticação.

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

## Protocolo

O protocolo HTTP é usado para comunicar com o servidor de autenticação. Os dados no corpo da resposta são ignorados; informações são passadas apenas nos cabeçalhos.

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

### Exemplos de requisições e respostas:

Requisição:

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

Resposta bem-sucedida:

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

Resposta com erro:

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

Se não houver cabeçalho `Auth-Wait`, um erro será retornado e a conexão será fechada. A implementação atual aloca memória para cada tentativa de autenticação. A memória é liberada apenas no final de uma sessão. Portanto, o número de tentativas de autenticação inválidas em uma única sessão deve ser limitado — o servidor deve responder sem o cabeçalho `Auth-Wait` após 10-20 tentativas (o número da tentativa é passado no cabeçalho `Auth-Login-Attempt`).

Quando APOP ou CRAM-MD5 é usado, a requisição-resposta ficará como segue:

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

Resposta bem-sucedida:

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

Quando XOAUTH2 ou OAUTHBEARER é usado, os cabeçalhos `Auth-User` e `Auth-Pass`
contêm a identidade do usuário e o bearer token extraídos da resposta SASL inicial.

Se o cabeçalho `Auth-User` existir na resposta, ele substitui o nome de usuário usado para autenticar com o backend.

Para SMTP, a resposta adicionalmente leva em conta o cabeçalho `Auth-Error-Code` — se existir, é usado como código de resposta em caso de erro. Caso contrário, o código 535 5.7.0 será adicionado ao cabeçalho `Auth-Status` por padrão.

Para XOAUTH2 e OAUTHBEARER, uma resposta de erro também pode incluir o
cabeçalho `Auth-Error-SASL`. Seu valor é enviado ao cliente como um
desafio SASL adicional (SMTP: 334, IMAP/POP3: +). Após o cliente responder com uma
resposta vazia para XOAUTH2 ou `AQ==` para OAUTHBEARER, o erro de
`Auth-Status` é retornado.

Por exemplo, se a seguinte resposta for recebida do servidor de autenticação:

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

então o cliente SMTP receberá um erro

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

Se o proxy SMTP não requer autenticação, a requisição ficará como segue:

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

Para conexões de cliente SSL/TLS, o cabeçalho `Auth-SSL` é adicionado, e `Auth-SSL-Verify` conterá o resultado da verificação do certificado do cliente, se [habilitado](https://pt.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client): `SUCCESS`, `FAILED:reason`, e `NONE` se um certificado não estava presente.

Quando o certificado do cliente estava presente, seus detalhes são passados nos seguintes cabeçalhos de requisição: `Auth-SSL-Subject`, `Auth-SSL-Issuer`, `Auth-SSL-Serial`, e `Auth-SSL-Fingerprint`. Se [auth_http_pass_client_cert](#m-auth-http-pass-client-cert) estiver habilitado, o certificado em si é passado no cabeçalho `Auth-SSL-Cert`. O protocolo e cifra da conexão estabelecida são passados nos cabeçalhos `Auth-SSL-Protocol` e `Auth-SSL-Cipher`. A requisição ficará como segue:

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

Quando o [protocolo PROXY](https://pt.angie.software//angie/docs/configuration/modules/mail/index.md#m-listen-ssl-proxy) é usado, seus detalhes são passados nos seguintes cabeçalhos de requisição: `Proxy-Protocol-Addr`, `Proxy-Protocol-Port`, `Proxy-Protocol-Server-Addr`, e `Proxy-Protocol-Server-Port`.