ngx_mail_auth_http_module

Directives

Syntax:  auth_http URL;
Default: —
Context: mail, server

HTTP 인증 서버의 URL을 설정합니다. 이 프로토콜은 아래에서 설명합니다.

Syntax:  auth_http_header header value;
Default: —
Context: mail, server

지정된 헤더를 인증 서버로 보내는 요청에 첨부합니다. 이 헤더는 공유된 시크릿으로 사용하여 해당 요청이 nginx에서 수신되었는지 확인할 수 있습니다. 예:

auth_http_header X-Auth-Key "secret_string";
Syntax:  auth_http_pass_client_cert on | off;
Default: auth_http_pass_client_cert off;
Context: mail, server
This directive appeared in version 1.7.11.

PEM 형식의 (urlencoded) 클라이언트 인증서가 포함된 “Auth-SSL-Cert” 헤더를 인증 서버로 보낸 요청에 첨부합니다.

Syntax:  auth_http_timeout time;
Default: auth_http_timeout 60s;
Context: mail, server

인증 서버와의 통신에 대한 시간제한을 설정합니다.

프로토콜

HTTP 프로토콜은 인증 서버와 통신하는 데 사용합니다. 응답 본문의 데이터는 무시하고, 헤더에서만 정보가 전달됩니다.

요청 및 응답 예제:

요청:

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

정상적인 응답:

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

잘못된 응답:

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

“Auth-Wait” 헤더가 없을 경우, 오류가 반환되고 연결이 종료됩니다. 현재 구현에서는 각 인증 시도에 대해 메모리를 할당합니다. 메모리는 세션이 종료되어야 해제됩니다. 그러므로 한 세션 내에서 잘못된 인증 시도 횟수를 제한해야 합니다. 서버는 10~20회 시도 후 “Auth-Wait” 헤더 없이 응답해야 합니다(시도 횟수는 “Auth-Login-Attempt” 헤더에서 전달해야 합니다).

APOP 또는 CRAM-MD5를 사용할 경우, 요청-응답은 다음과 같습니다.

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

정상적인 응답:

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

“Auth-User” 헤더가 응답에 존재할 경우, 백엔드 인증에 사용한 사용자 이름을 재정의합니다.

SMTP의 경우, 응답은 “Auth-Error-Code” 헤더를 추가적으로 고려합니다. 헤더가 있으면 오류 발생 시 응답 코드로 사용합니다. 그 외에는 535 5.7.0 코드를 “Auth-Status” 헤더에 추가합니다.

예를 들어 인증 서버에서 다음과 같은 응답을 수신할 수 있습니다.

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

그러면 SMTP 클라이언트가 오류를 수신합니다.

451 4.3.0 Temporary server problem, try again later

SMTP를 프록시하는 데 인증이 필요하지 않은 경우, 요청은 다음과 같습니다.

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>

SSL/TLS 클라이언트 연결(1.7.11)에서는 “Auth-SSL” 헤더가 추가됩니다. 클라이언트 인증서 확인이 활성화되어 있다면 “Auth-SSL-Verify”에 그 결과가 포함됩니다. 결과는 “SUCCESS”, “FAILED:reason“, “NONE”(인증서가 없을 경우)로 구분됩니다.

1.11.7버전 이전에는 “FAILED” 결과에 reason 문자열이 포함되지 않았습니다.

클라이언트 인증서가 있으면 세부 정보는 “Auth-SSL-Subject”, “Auth-SSL-Issuer”, “Auth-SSL-Serial”, “Auth-SSL-Fingerprint” 요청 헤더에서 전달됩니다. auth_http_pass_client_cert이 활성화되어 있으면 인증서 자체는 “Auth-SSL-Cert” 헤더에서 전달됩니다. 설정된 연결의 프로토콜과 암호는 “Auth-SSL-Protocol” 및 “Auth-SSL-Cipher” 헤더에서 전달됩니다(1.21.2). 요청은 다음과 같은 형태를 취합니다.

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

PROXY 프로토콜을 사용한 경우 세부 정보는 “Proxy-Protocol-Addr”, “Proxy-Protocol-Port”, “Proxy-Protocol-Server-Addr” 및 “Proxy-Protocol-Server-Port” 요청 헤더에서 전달됩니다(1.19.8).