Auth HTTP#

Autentica a los clientes de correo mediante un servidor HTTP externo, el servidor de autenticación, que además elige el backend de cada sesión. Angie no tiene otra fuente de direcciones de backend para el correo, por lo que cada server del bloque mail necesita la directiva auth_http (consulte Cómo funciona).

Ejemplo de configuración#

Angie envía las sesiones IMAP por proxy a uno de dos backends, elegido según el dominio del nombre de usuario, y actúa como su propio servidor de autenticación mediante un bloque location dentro de su bloque http. El bloque mail va en el nivel superior de angie.conf, y los bloques map y server, dentro del bloque http existente:

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;
        }
    }
}

Este servidor de autenticación enruta a los clientes, pero no comprueba las contraseñas de los clientes: Angie inicia sesión en el backend con la contraseña que envió el cliente, y el backend la acepta o la rechaza. Si el backend la rechaza, proxy_pass_error_message pasa la respuesta del backend al cliente, y Angie cierra la conexión. Un usuario de cualquier otro dominio recibe el error Invalid login or password. En los nueve primeros intentos de una sesión, Angie retrasa ese error tres segundos y deja que el cliente lo intente de nuevo; a partir del décimo intento, envía el error de inmediato y cierra la conexión.

Directivas#

auth_http#

Sintaxis	`auth_http` uri;
Predeterminado	—
Contexto	mail, server

Establece la URL del servidor de autenticación: una dirección IP o un nombre de dominio con un puerto opcional (80 por defecto) y un URI, o la ruta de un socket de dominio UNIX tras el prefijo unix:, como en unix:/run/mail-auth.sock:/mail-auth. El prefijo http:// del esquema es opcional. HTTPS no se admite: una URL https:// falla en la prueba de configuración con el error invalid port in auth_http. Angie resuelve el nombre de dominio al cargar la configuración y envía las solicitudes a la primera dirección encontrada.

La directiva es obligatoria: si ni un server ni el bloque mail la establecen, la prueba de configuración falla con el error no "auth_http" is defined for server. Las solicitudes y respuestas se describen en Protocolo.

auth_http_header#

Sintaxis	`auth_http_header` header value;
Predeterminado	—
Contexto	mail, server

Añade la cabecera a las solicitudes enviadas al servidor de autenticación. La directiva puede especificarse varias veces. Estas directivas se heredan del nivel de configuración anterior si y solo si en el nivel actual no hay directivas auth_http_header.

Una cabecera secreta permite al servidor de autenticación comprobar que una solicitud procede de Angie:

auth_http_header X-Auth-Key "secret_string";

auth_http_pass_client_cert#

Sintaxis	`auth_http_pass_client_cert` `on` \| `off`;
Predeterminado	`auth_http_pass_client_cert off;`
Contexto	mail, server

Añade la cabecera Auth-SSL-Cert con el certificado del cliente en formato PEM, codificado en URL, a las solicitudes enviadas al servidor de autenticación. Angie envía la cabecera solo cuando el cliente presenta un certificado y ssl_verify_client está habilitado.

auth_http_timeout#

Sintaxis	`auth_http_timeout` tiempo;
Predeterminado	`auth_http_timeout 60s;`
Contexto	mail, server

Establece el tiempo de espera para el intercambio con el servidor de autenticación: en ese tiempo, Angie debe conectarse con el servidor, enviar la solicitud y recibir las cabeceras de respuesta.

Protocolo#

En cada intento de inicio de sesión, Angie abre una conexión nueva con el servidor de autenticación y envía una solicitud HTTP/1.0 GET para el URI establecido con auth_http; los datos del cliente viajan en las cabeceras de la solicitud. Un cliente SMTP que envía correo sin autenticarse desencadena la solicitud tras su comando RCPT TO.

El servidor de autenticación responde en las cabeceras de respuesta. Angie ignora el código de estado y el cuerpo de la respuesta. La línea de estado, las cabeceras y la línea vacía que las sigue deben caber en 1024 bytes: con un bloque de cabeceras más largo, la sesión falla como se describe en Errores, y el cliente puede esperar hasta que expire auth_http_timeout antes de recibir el error.

Cabeceras de solicitud#

`Host`	El host de la URL de auth_http; `localhost` para un socket de dominio UNIX.
`Auth-Method`	El método de autenticación que usó el cliente: `plain` (también para `AUTH LOGIN`, el comando IMAP `LOGIN` y los comandos POP3 `USER` y `PASS`), `apop`, `cram-md5`, `external`, `xoauth2` u `oauthbearer`; `none` para un cliente SMTP que envía correo sin autenticarse.
`Auth-User`	El nombre de usuario que envió el cliente; para XOAUTH2 y OAUTHBEARER, la identidad del usuario de la respuesta SASL inicial.
`Auth-Pass`	La contraseña que envió el cliente; el digest del cliente para APOP y CRAM-MD5; el token de portador para XOAUTH2 y OAUTHBEARER; vacío para EXTERNAL.
`Auth-Salt`	Solo APOP y CRAM-MD5: el desafío que Angie envió al cliente.
`Auth-Protocol`	`imap`, `pop3` o `smtp`.
`Auth-Login-Attempt`	El número del intento de inicio de sesión del cliente en la sesión, empezando por 1.
`Client-IP`	La dirección IP del cliente.
`Client-Host`	Solo SMTP: el nombre de host del cliente encontrado por el resolver; `[UNAVAILABLE]` si el resolver no está configurado, el nombre no existe o no se resuelve de vuelta a la dirección del cliente; `[TEMPUNAVAIL]` en otros errores de resolución.
`Auth-SMTP-Helo`, `Auth-SMTP-From`, `Auth-SMTP-To`	Solo con `Auth-Method: none`: el argumento del comando `HELO` o `EHLO` del cliente y, completos, sus comandos `MAIL FROM` y `RCPT TO`.
`Proxy-Protocol-Addr`, `Proxy-Protocol-Port`, `Proxy-Protocol-Server-Addr`, `Proxy-Protocol-Server-Port`	Solo con el parámetro `proxy_protocol` de listen: la dirección y el puerto del cliente y la dirección y el puerto del servidor, tomados de la cabecera del protocolo PROXY.
`Auth-SSL`	`on` si la conexión del cliente usa SSL/TLS, también tras STARTTLS.
`Auth-SSL-Protocol`, `Auth-SSL-Cipher`	El protocolo y el cifrado de la conexión SSL/TLS del cliente.
`Auth-SSL-Verify`	Solo con ssl_verify_client habilitado: el resultado de la verificación del certificado del cliente: `SUCCESS`, `FAILED:`reason o `NONE` si el cliente no presentó ningún certificado. `FAILED` llega solo con `ssl_verify_client optional_no_ca` y solo para un certificado autofirmado o uno cuyo emisor se desconoce; cualquier otra verificación fallida pone fin a la sesión antes de la solicitud.
`Auth-SSL-Subject`, `Auth-SSL-Issuer`, `Auth-SSL-Serial`, `Auth-SSL-Fingerprint`	Solo con ssl_verify_client habilitado y un certificado de cliente presentado: el DN del sujeto y del emisor del certificado en formato RFC 2253, su número de serie y su huella digital SHA-1.
`Auth-SSL-Cert`	En las mismas condiciones, si auth_http_pass_client_cert también está habilitado: el certificado del cliente en formato PEM.

Las cabeceras establecidas con auth_http_header van después de las de la tabla anterior. En Auth-User, Auth-Pass y Auth-SSL-Cert, Angie sustituye los espacios, los signos de porcentaje y los caracteres de control por secuencias de escape %XX, por lo que el servidor de autenticación tiene que decodificar estos valores antes de usarlos.

Cabeceras de respuesta#

`Auth-Status`	`OK` acepta al cliente. `WAIT` hace que Angie repita la solicitud tras el retraso de `Auth-Wait`. Cualquier otro valor rechaza al cliente y se convierte en el mensaje de error que se le envía. Angie distingue mayúsculas de minúsculas al comparar `OK` y `WAIT`; una respuesta sin `Auth-Status` también acepta al cliente.
`Auth-Server`	Con `OK`: la dirección IP del backend. No se admite un nombre de dominio.
`Auth-Port`	Con `OK`: el puerto del backend.
`Auth-User`	Con `OK`: el nombre de usuario con el que iniciar sesión en el backend, en lugar del que envió el cliente.
`Auth-Pass`	Con `OK`: la contraseña con la que iniciar sesión en el backend, en lugar de la que envió el cliente. Es obligatoria tras una autenticación APOP, CRAM-MD5 o EXTERNAL: siempre para IMAP y POP3, y para SMTP si proxy_smtp_auth está habilitado.
`Auth-Wait`	Un retraso en segundos, que solo se usa con un error o con `WAIT`. Con un error, Angie espera ese tiempo, envía el error y deja que el cliente lo intente de nuevo; sin la cabecera, Angie envía el error de inmediato y cierra la conexión. Con `WAIT`, es el retraso antes de repetir la solicitud.
`Auth-Error-Code`	Solo SMTP, con un error: el código de respuesta y el código de estado mejorado que preceden al mensaje; por defecto, `535 5.7.0`.
`Auth-Error-SASL`	Solo XOAUTH2 y OAUTHBEARER, con un error: un desafío SASL que Angie envía al cliente antes del error.

Angie ignora las demás cabeceras de respuesta. Sin embargo, el nombre de una cabecera solo puede contener letras latinas, dígitos y guiones: un nombre con cualquier otro carácter, como un guion bajo, hace que Angie rechace toda la respuesta.

Ejemplos de solicitudes y respuestas#

Inicio de sesión correcto#

Un cliente IMAP inicia sesión con un nombre de usuario y una contraseña:

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

El servidor de autenticación acepta al cliente e indica el backend:

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

Angie se conecta a 198.51.100.1:143 e inicia sesión con el nombre de usuario y la contraseña del cliente.

Inicio de sesión fallido y reintentos#

El servidor de autenticación rechaza al cliente:

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

Pasados tres segundos, Angie envía al cliente el error en el formato que exige el protocolo correspondiente (-ERR Invalid login or password en POP3, una respuesta NO con etiqueta en IMAP, 535 5.7.0 Invalid login or password en SMTP) y deja que el cliente lo intente de nuevo; la siguiente solicitud lleva el valor incrementado de Auth-Login-Attempt.

Angie reserva memoria para cada intento y la libera solo cuando termina la sesión, por lo que el servidor de autenticación debe limitar los intentos: tras 10-20 de ellos, debe responder sin Auth-Wait, para que Angie cierre la conexión.

En SMTP, Auth-Error-Code sustituye el código de respuesta predeterminado. Esta respuesta:

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

hace que el cliente SMTP reciba este error:

451 4.3.0 Temporary server problem, try again later

Si el servidor de autenticación aún no puede decidir, puede responder con Auth-Status: WAIT. Entonces Angie vuelve a enviar la solicitud tras el retraso de Auth-Wait, sin avisar al cliente, y Auth-Login-Attempt no cambia. Con APOP y CRAM-MD5, la solicitud repetida lleva un Auth-Pass vacío, por lo que el servidor de autenticación tiene que comprobar el digest en la primera solicitud y recordar el resultado. Angie sigue repitiendo la solicitud mientras la respuesta sea WAIT, incluso después de que el cliente se desconecte, de modo que el servidor de autenticación debe dejar de responder WAIT pasado un tiempo razonable.

Advertencia

Toda respuesta WAIT debe llevar Auth-Wait. Sin esa cabecera, Angie repite la solicitud de inmediato, en un bucle continuo, y sigue haciéndolo incluso cuando el servidor de autenticación responde después OK.

APOP, CRAM-MD5 y EXTERNAL#

Con APOP o CRAM-MD5, el cliente demuestra que conoce la contraseña sin enviarla, y la solicitud lleva el desafío y el digest del cliente:

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 inicia sesión en el backend solo con comandos de texto plano, por lo que el servidor de autenticación comprueba el digest por sí mismo y devuelve la contraseña del usuario:

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

EXTERNAL necesita Auth-Pass en la respuesta de la misma manera; su solicitud lleva un Auth-Pass vacío.

XOAUTH2 y OAUTHBEARER#

En caso de éxito, Angie inicia sesión en el backend con el token de portador como contraseña, a menos que la respuesta lleve Auth-Pass.

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

SMTP sin autenticación#

Si smtp_auth incluye none y el cliente envía correo sin autenticarse, la solicitud lleva los comandos SMTP del cliente:

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>

El servidor de autenticación sigue teniendo que indicar el backend en Auth-Server y Auth-Port; Angie entonces repite al backend los comandos MAIL FROM y RCPT TO del cliente.

Conexiones de cliente SSL/TLS#

Un cliente IMAP conectado mediante TLS, con ssl_verify_client habilitado:

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

Errores#

Si falla el intercambio con el servidor de autenticación, o si la respuesta del servidor acepta al cliente pero no puede usarse, Angie envía al cliente un error interno y cierra la conexión:

IMAP	`* BAD internal server error`
POP3	`-ERR internal server error`
SMTP	`451 4.3.2 Internal server error`

El error_log indica la causa:

`timed out`	El intercambio no se completó dentro del plazo de auth_http_timeout.
`sent invalid response`	La línea de estado termina con un CR que no va seguido de LF.
`sent invalid header in response`	Una cabecera de la respuesta está mal formada, o su nombre contiene un carácter que no es una letra latina, un dígito ni un guion.
`did not send server or port`	La respuesta no rechaza al cliente, pero carece de `Auth-Server` o `Auth-Port`, como ocurre con una página de error devuelta para un URI incorrecto.
`sent invalid server address`	`Auth-Server` no es una dirección IP.
`sent invalid server port`	`Auth-Port` no es un número del 1 al 65535.
`did not send password`	Una respuesta IMAP o POP3 acepta a un cliente APOP, CRAM-MD5 o EXTERNAL sin `Auth-Pass`.
`no password available`	Una respuesta SMTP acepta a un cliente CRAM-MD5 o EXTERNAL sin `Auth-Pass` mientras proxy_smtp_auth está habilitado.

Todos estos mensajes, salvo no password available, empiezan con auth http server y la dirección del servidor de autenticación. Si Angie no puede conectarse con el servidor de autenticación, el registro muestra el error del sistema en un mensaje connect() to ... failed, send() failed o recv() failed. Una respuesta cuyo bloque de cabeceras supera los 1024 bytes se registra como timed out, si es que se registra.