nginx: understanding the purpose of auth_http (IMAP proxy)

Question

I would like to send IMAP client requests to an IMAP back-end via an nginx proxy. According to the the mail_auth_http module, a directive auth_http has to be used in order to authenticate the clients. But what exactly is the purpose of auth_http, why can't the authentication process simply be forwarded to the IMAP back-end?

As far as I know, auth_http points to an authentication script which uses a custom HTTP protocol in order to determine which back-end will be used etc, and the actual IMAP based authentication is skipped completely. Am I correct?

I'd appreciate it if someone could post a practical example.

Answer 1

The auth_http does two main things:

• It authenticates users (including various options to effectively delay users on failed authentication).
• And it determines which backend to use (and which username and password to use in backend authentication, if at all).

While in some cases authentication can be handled directly by a backend, it's not something always possible. Moreover, if nginx needs to be used as a mail proxy, it's almost always means that there are multiple backends and backend isn't known in advance.

It's also more efficient to handle authentication (in particular, authentication errors) with nginx, as mail servers tends to use process-per-connection model and can't effectively wait for a while before returning an error.

If you don't care about all of the above, and want nginx to just pass a connection to a predetermined backend, you may use something like this in nginx http{} block as a dead simple auth_http script:

location = /auth {
    add_header Auth-Status OK;
    add_header Auth-Server 127.0.0.2;  # backend ip
    add_header Auth-Port   143;        # backend port
    return 204;
}

With such auth script nginx will always get a successful authentication result, and it will pass the connection to the backend specified, with username and password provided by the client.

Note though, that this should not be used with SMTP, as there is no backend authentication with SMTP.