<!-- review: finished -->

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

# Auth HTTP

El módulo permite la autenticación basada en sub-peticiones enviando una petición HTTP
adicional antes de procesar la petición principal. Si la sub-petición devuelve un
estado 2xx, la petición principal continúa; si devuelve 401 o 403, se envía el
error correspondiente al usuario, mientras que cualquier otra respuesta desencadena un
error 500. Este enfoque se utiliza típicamente para delegar la autenticación a servicios externos,
unificar la autenticación entre aplicaciones o integrarse con sistemas de terceros
como OAuth o LDAP.

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

## Directivas

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

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

### auth_http

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http` uri;   |
|--------------------------------------------------------------------------------------------|--------------------|
| Predeterminado                                                                             | —                  |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server       |

Establece la URL del servidor de autenticación HTTP. El protocolo se describe [a continuación](#v-m-protocol).

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

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

### auth_http_header

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_header` header value;   |
|--------------------------------------------------------------------------------------------|------------------------------------|
| Predeterminado                                                                             | —                                  |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                       |

Añade la cabecera especificada a las peticiones enviadas al servidor de autenticación. Esta cabecera puede utilizarse como secreto compartido para verificar que la petición proviene de Angie. Por ejemplo:

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

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_pass_client_cert` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|----------------------------------------------|
| Predeterminado                                                                             | `auth_http_pass_client_cert off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                                 |

Añade la cabecera `Auth-SSL-Cert` con el [certificado del cliente](https://es.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client) en formato PEM (codificado en URL) a las peticiones enviadas al servidor de autenticación.

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

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

### auth_http_timeout

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `auth_http_timeout` time;   |
|--------------------------------------------------------------------------------------------|-----------------------------|
| Predeterminado                                                                             | `auth_http_timeout 60s;`    |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | mail, server                |

Establece el tiempo de espera para la comunicación con el servidor de autenticación.

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

## Protocolo

El protocolo HTTP se utiliza para comunicarse con el servidor de autenticación. Los datos en el cuerpo de la respuesta se ignoran; la información se transmite solo en las cabeceras.

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

### Ejemplos de peticiones y respuestas:

Petición:

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

Respuesta correcta:

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

Respuesta incorrecta:

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

Si no hay cabecera `Auth-Wait`, se devolverá un error y se cerrará la conexión. La implementación actual asigna memoria para cada intento de autenticación. La memoria se libera solo al final de una sesión. Por lo tanto, el número de intentos de autenticación inválidos en una sola sesión debe ser limitado — el servidor debe responder sin la cabecera `Auth-Wait` después de 10-20 intentos (el número de intento se pasa en la cabecera `Auth-Login-Attempt`).

Cuando se utiliza APOP o CRAM-MD5, la petición-respuesta se verá así:

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

Respuesta correcta:

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

Cuando se utiliza XOAUTH2 o OAUTHBEARER, las cabeceras `Auth-User` y `Auth-Pass`
contienen la identidad del usuario y el token de portador extraídos de la
respuesta SASL inicial.

Si la cabecera `Auth-User` existe en la respuesta, anula el nombre de usuario utilizado para autenticarse con el backend.

Para SMTP, la respuesta tiene en cuenta adicionalmente la cabecera `Auth-Error-Code` — si existe, se utiliza como código de respuesta en caso de error. De lo contrario, el código 535 5.7.0 se añadirá a la cabecera `Auth-Status` por defecto.

Para XOAUTH2 y OAUTHBEARER, una respuesta de error también puede incluir la
cabecera `Auth-Error-SASL`. Su valor se envía al cliente como un desafío
SASL adicional (SMTP: 334, IMAP/POP3: +). Después de que el cliente responda con una
respuesta vacía para XOAUTH2 o `AQ==` para OAUTHBEARER, se devuelve el error de
`Auth-Status`.

Por ejemplo, si se recibe la siguiente respuesta del servidor de autenticación:

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

entonces el cliente SMTP recibirá un error

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

Si el proxy SMTP no requiere autenticación, la petición se verá así:

```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 conexiones de cliente SSL/TLS, se añade la cabecera `Auth-SSL`, y `Auth-SSL-Verify` contendrá el resultado de la verificación del certificado del cliente, si está [habilitada](https://es.angie.software//angie/docs/configuration/modules/mail/mail_ssl.md#m-ssl-verify-client): `SUCCESS`, `FAILED:reason`, y `NONE` si no se presentó un certificado.

Cuando el certificado del cliente está presente, sus detalles se pasan en las siguientes cabeceras de petición: `Auth-SSL-Subject`, `Auth-SSL-Issuer`, `Auth-SSL-Serial`, y `Auth-SSL-Fingerprint`. Si [auth_http_pass_client_cert](#m-auth-http-pass-client-cert) está habilitado, el certificado mismo se pasa en la cabecera `Auth-SSL-Cert`. El protocolo y cifrado de la conexión establecida se pasan en las cabeceras `Auth-SSL-Protocol` y `Auth-SSL-Cipher`. La petición se verá así:

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

Cuando se utiliza el [protocolo PROXY](https://es.angie.software//angie/docs/configuration/modules/mail/index.md#m-listen-ssl-proxy), sus detalles se pasan en las siguientes cabeceras de petición: `Proxy-Protocol-Addr`, `Proxy-Protocol-Port`, `Proxy-Protocol-Server-Addr`, y `Proxy-Protocol-Server-Port`.