Модуль ngx_mail_auth_http_module

• Директивы
• auth_http
• auth_http_header
• auth_http_pass_client_cert
• auth_http_timeout
• Протокол

Директивы

Устанавливает URL HTTP-сервера аутентификации. Протокол описан ниже.

Добавляет указанный заголовок к запросам, отправленным на сервер аутентификации. Этот заголовок может использоваться в качестве общего секрета для проверки того, что запрос исходит от nginx. Например:

auth_http_header X-Auth-Key "secret_string";

Добавляет заголовок «Auth-SSL-Cert» с клиентом сертификатом в формате PEM (urlencoded) к запросам, отправленным на сервер аутентификации.

Устанавливает таймаут для связи с сервером аутентификации.

Протокол

Для связи с сервером аутентификации используется 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», будет возвращена ошибка, и соединение закроется. В текущей реализации память выделяется для каждой попытки аутентификации. Память освобождается только в конце сессии. Поэтому количество неудачных попыток аутентификации в одной сессии должно быть ограничено — сервер должен отвечать без заголовка «Auth-Wait» после 10-20 попыток (номер попытки передаётся в заголовке «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).