ngx_mail_auth_http_module モジュール日本語訳

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形式(urlencoded)のclient証明書と一緒に"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"ヘッダにt追加されるでしょう。

例えば、次の応答を認証サーバから受け取った場合:

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” ヘッダが追加され、enabledの場合は“Auth-SSL-Verify” はクライアント証明書の検証結果を含むでしょう: “SUCCESS”, “FAILEDreason”。証明書がない場合は “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” ヘッダの中で渡されます。確立された接続のプロトコルとcipherは“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 protocolが使われる場合、詳細は“Proxy-Protocol-Addr”, “Proxy-Protocol-Port”, “Proxy-Protocol-Server-Addr”, “Proxy-Protocol-Server-Port” で渡されます(1.19.8)。