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.

Diretivas#

auth_http#

Sintaxe	`auth_http` uri;
Padrão	—
Contexto	mail, server

Define a URL do servidor de autenticação HTTP. O protocolo é descrito abaixo.

auth_http_header#

Sintaxe	`auth_http_header` header value;
Padrão	—
Contexto	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:

auth_http_header X-Auth-Key "secret_string";

auth_http_pass_client_cert#

Sintaxe	`auth_http_pass_client_cert` `on` \| `off`;
Padrão	`auth_http_pass_client_cert off;`
Contexto	mail, server

Anexa o cabeçalho Auth-SSL-Cert com o certificado do cliente em formato PEM (urlencoded) às requisições enviadas ao servidor de autenticação.

auth_http_timeout#

Sintaxe	`auth_http_timeout` time;
Padrão	`auth_http_timeout 60s;`
Contexto	mail, server

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

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.

Exemplos de requisições e respostas:#

Requisição:

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

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

Resposta ruim:

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:

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 boa:

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

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.

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

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

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:

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

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 é 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.