模組 ngx_mail_auth_http_module

指令
     auth_http
     auth_http_header
     auth_http_pass_client_cert
     auth_http_timeout
協定

指令

語法	`auth_http URL;`
預設	—
Context	`mail`, `server`

設定 HTTP 驗證伺服器的 URL。協定描述如下下方。

語法	`auth_http_header header value;`
預設	—
Context	`mail`, `server`

將指定的標頭附加到傳送至驗證伺服器的請求。此標頭可用作共享密碼，以驗證請求來自 nginx。例如

auth_http_header X-Auth-Key "secret_string";

語法	`auth_http_pass_client_cert on \| off;`
預設	auth_http_pass_client_cert off;
Context	`mail`, `server`

此指令出現在 1.7.11 版本中。

將 “Auth-SSL-Cert” 標頭附加到傳送至驗證伺服器的請求，其中包含 PEM 格式（URL 編碼）的用戶端憑證。

語法	`auth_http_timeout time;`
預設	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-Login-Attempt” 標頭中傳遞）回應，而不要包含 “Auth-Wait” 標頭。

當使用 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

如果 Proxy 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:原因”，如果不存在憑證，則為 “NONE”。

在 1.11.7 版本之前，“FAILED” 結果不包含 原因 字串。

當用戶端憑證存在時，其詳細資訊會在以下請求標頭中傳遞：“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)。