Mercurial > hg > nginx-site
view xml/en/docs/mail/ngx_mail_auth_http_module.xml @ 2778:9cafae0b7ef3
Minor fixes in njs examples.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 14 Oct 2021 18:53:16 +0100 |
parents | 96d6d66d36e4 |
children | 7b7dbaa7d777 |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) 2006, 2007 Anton Yuzhaninov Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_mail_auth_http_module" link="/en/docs/mail/ngx_mail_auth_http_module.html" lang="en" rev="11"> <section id="directives" name="Directives"> <directive name="auth_http"> <syntax><value>URL</value></syntax> <default/> <context>mail</context> <context>server</context> <para> Sets the URL of the HTTP authentication server. The protocol is described <link id="protocol">below</link>. </para> </directive> <directive name="auth_http_header"> <syntax><value>header</value> <value>value</value></syntax> <default/> <context>mail</context> <context>server</context> <para> Appends the specified header to requests sent to the authentication server. This header can be used as the shared secret to verify that the request comes from nginx. For example: <example> auth_http_header X-Auth-Key "secret_string"; </example> </para> </directive> <directive name="auth_http_pass_client_cert"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>off</default> <context>mail</context> <context>server</context> <appeared-in>1.7.11</appeared-in> <para> Appends the <header>Auth-SSL-Cert</header> header with the <link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">client</link> certificate in the PEM format (urlencoded) to requests sent to the authentication server. </para> </directive> <directive name="auth_http_timeout"> <syntax><value>time</value></syntax> <default>60s</default> <context>mail</context> <context>server</context> <para> Sets the timeout for communication with the authentication server. </para> </directive> </section> <section id="protocol" name="Protocol"> <para> The HTTP protocol is used to communicate with the authentication server. The data in the response body is ignored, the information is passed only in the headers. </para> <para> Examples of requests and responses: </para> <para> Request: <example> 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 </example> Good response: <example> HTTP/1.0 200 OK Auth-Status: OK Auth-Server: 198.51.100.1 Auth-Port: 143 </example> Bad response: <example> HTTP/1.0 200 OK Auth-Status: Invalid login or password Auth-Wait: 3 </example> </para> <para> If there is no <header>Auth-Wait</header> header, an error will be returned and the connection will be closed. The current implementation allocates memory for each authentication attempt. The memory is freed only at the end of a session. Therefore, the number of invalid authentication attempts in a single session must be limited — the server must respond without the <header>Auth-Wait</header> header after 10-20 attempts (the attempt number is passed in the <header>Auth-Login-Attempt</header> header). </para> <para> When the APOP or CRAM-MD5 are used, request-response will look as follows: <example> 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 </example> Good response: <example> HTTP/1.0 200 OK Auth-Status: OK Auth-Server: 198.51.100.1 Auth-Port: 143 Auth-Pass: plain-text-pass </example> </para> <para> If the <header>Auth-User</header> header exists in the response, it overrides the username used to authenticate with the backend. </para> <para> For the SMTP, the response additionally takes into account the <header>Auth-Error-Code</header> header — if exists, it is used as a response code in case of an error. Otherwise, the 535 5.7.0 code will be added to the <header>Auth-Status</header> header. </para> <para> For example, if the following response is received from the authentication server: <example> HTTP/1.0 200 OK Auth-Status: Temporary server problem, try again later Auth-Error-Code: 451 4.3.0 Auth-Wait: 3 </example> then the SMTP client will receive an error <example> 451 4.3.0 Temporary server problem, try again later </example> </para> <para> If proxying SMTP does not require authentication, the request will look as follows: <example> 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> </example> </para> <para> For the SSL/TLS client connection (1.7.11), the <header>Auth-SSL</header> header is added, and <header>Auth-SSL-Verify</header> will contain the result of client certificate verification, if <link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">enabled</link>: “<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”, and “<literal>NONE</literal>” if a certificate was not present. <note> Prior to version 1.11.7, the “<literal>FAILED</literal>” result did not contain the <value>reason</value> string. </note> When the client certificate was present, its details are passed in the following request headers: <header>Auth-SSL-Subject</header>, <header>Auth-SSL-Issuer</header>, <header>Auth-SSL-Serial</header>, and <header>Auth-SSL-Fingerprint</header>. If <link id="auth_http_pass_client_cert"/> is enabled, the certificate itself is passed in the <header>Auth-SSL-Cert</header> header. The protocol and cipher of the established connection are passed in the <header>Auth-SSL-Protocol</header> and <header>Auth-SSL-Cipher</header> headers (1.21.2). The request will look as follows: <example> 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 </example> </para> <para id="proxy_protocol"> When the <link doc="ngx_mail_core_module.xml" id="proxy_protocol">PROXY protocol</link> is used, its details are passed in the following request headers: <header>Proxy-Protocol-Addr</header>, <header>Proxy-Protocol-Port</header>, <header>Proxy-Protocol-Server-Addr</header>, and <header>Proxy-Protocol-Server-Port</header> (1.19.8). </para> </section> </module>