====== Директивы модуля ngx_mail_auth_http_module ======

===== Директивы =====

==== auth_http ====
**syntax**: auth_http //**URL**//\\
**default**: нет\\
**context**: mail, server

Директива указывает URL http-сервера авторизации. Протокол описан ниже.

==== auth_http_header ====
**syntax**: auth_http_header //**заголовок значение**//\\
**default**: нет\\
**context**: mail, server

Позволяет добавить указанный заголовок к запросам на сервер авторизации. Можно использовать в качестве shared secret для проверки, что запрос пришел от nginx.

Например:

    auth_http_header X-Auth-Key "secret_string";

==== auth_http_timeout ====
**syntax**: auth_http_timeout //**время**//\\
**default**: 60\\
**context**: mail, server

===== Протокол =====

Для общения с сервером авторизации используется http. Данные в теле ответов игнорируются, информация передается только в заголовках.

Примеры запросов и ответов:

Запрос:

    GET /auth HTTP/1.0
    Host: localhost
    Auth-Method: plain # plain или apop или cram-md5
    Auth-User: user
    Auth-Pass: password
    Auth-Protocol: imap # imap, pop3 или smtp
    Auth-Login-Attempt: 1 # какая по счету попытка в рамках одной сессии
    Client-IP: 192.168.1.1

Хороший ответ:

    HTTP/1.0 200 OK # эта строка игнорируется
    Auth-Status: OK
    Auth-Server: 10.1.1.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.ru>
    Auth-Pass: auth_response
    Auth-Protocol: imap
    Auth-Login-Attempt: 1 # какая по счету попытка в рамках одной сессии
    Client-IP: 192.168.1.1

Хороший ответ:

    HTTP/1.0 200 OK # эта строка игнорируется
    Auth-Status: OK
    Auth-Server: 10.1.1.1
    Auth-Port: 143
    Auth-Pass: plan-text-pass

Для smtp в ответе дополнительно учитывется заголовок Auth-Error-Code - если он есть, то используется как код ответа в случае ошибки. Если нет, то по умолчанию к Auth-Status будет добавлен код 535 5.7.0

Например если от сервера авторизации будет получен ответ:

    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