モジュールngx_mail_auth_http

モジュールngx_mail_auth_http_module

ディレクティブ
     auth_http
     auth_http_header
     auth_http_pass_client_cert
     auth_http_timeout
プロトコル

ディレクティブ

構文	`auth_http URL;`
既定値	—
コンテキスト	`mail`、`server`

HTTP認証サーバーのURLを設定します。プロトコルは以下で説明します。

構文	`auth_http_header header value;`
既定値	—
コンテキスト	`mail`、`server`

認証サーバーに送信されたリクエストに指定されたヘッダーを追加します。このヘッダーは、リクエストがnginxから送信されたことを確認するための共有シークレットとして使用できます。たとえば

auth_http_header X-Auth-Key "secret_string";

構文	`auth_http_pass_client_cert on \| off;`
既定値	auth_http_pass_client_cert off;
コンテキスト	`mail`、`server`

このディレクティブはバージョン1.7.11で導入されました。

PEM形式（URLエンコード）の「Auth-SSL-Cert」ヘッダーと、認証サーバーに送信されたリクエスト内のクライアント証明書を追加します。

構文	`auth_http_timeout time;`
既定値	auth_http_timeout 60s;
コンテキスト	`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:理由」、「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）。