Mercurial > hg > nginx-site

annotate xml/en/docs/mail/ngx_mail_auth_http_module.xml @ 2063:6855bdb15368

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Removed mentions of wiki.nginx.org. The wiki was moved to nginx.com long time ago. It's almost unmaintained now and all the links have been removed from nginx.com as well.
author Valentin Bartenev <vbart@nginx.com>
date Thu, 19 Oct 2017 20:43:00 +0300
parents 9af1e88e10c8
children 468e6e14e5cc
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
2
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
3 <!--
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
4 Copyright (C) 2006, 2007 Anton Yuzhaninov
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
5 Copyright (C) Nginx, Inc.
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
6 -->
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
7
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
9
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
10 <module name="Module ngx_mail_auth_http_module"
667
81ac18894319 link and lang tags corrected.
Maxim Konovalov <maxim@nginx.com>
parents: 664
diff changeset
11 link="/en/docs/mail/ngx_mail_auth_http_module.html"
81ac18894319 link and lang tags corrected.
Maxim Konovalov <maxim@nginx.com>
parents: 664
diff changeset
12 lang="en"
1887
9af1e88e10c8 Documented SASL EXTERNAL support in mail.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1863
diff changeset
13 rev="9">
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
14
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
15 <section id="directives" name="Directives">
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
16
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
17 <directive name="auth_http">
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
18 <syntax><value>URL</value></syntax>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
19 <default/>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
20 <context>mail</context>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
21 <context>server</context>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
22
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
23 <para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
24 Sets the URL of the HTTP authentication server.
1255
e48d4309e7f2 Mail auth: added link to the protocol in the "auth_http" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1254
diff changeset
25 The protocol is described <link id="protocol">below</link>.
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
26 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
27
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
28 </directive>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
29
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
30
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
31 <directive name="auth_http_header">
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
32 <syntax><value>header</value> <value>value</value></syntax>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
33 <default/>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
34 <context>mail</context>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
35 <context>server</context>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
36
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
37 <para>
1256
ebfcd76e23b6 Mail auth: corrected articles, rephrased some parts.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1255
diff changeset
38 Appends the specified header to requests sent to the authentication server.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
39 This header can be used as the shared secret to verify
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
40 that the request comes from nginx.
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
41 For example:
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
42 <example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
43 auth_http_header X-Auth-Key "secret_string";
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
44 </example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
45 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
46
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
47 </directive>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
48
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
49
1429
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
50 <directive name="auth_http_pass_client_cert">
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
51 <syntax><literal>on</literal> | <literal>off</literal></syntax>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
52 <default>off</default>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
53 <context>mail</context>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
54 <context>server</context>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
55 <appeared-in>1.7.11</appeared-in>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
56
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
57 <para>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
58 Appends the <header>Auth-SSL-Cert</header> header with the
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
59 <link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">client</link>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
60 certificate in the PEM format (urlencoded)
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
61 to requests sent to the authentication server.
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
62 </para>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
63
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
64 </directive>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
65
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
66
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
67 <directive name="auth_http_timeout">
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
68 <syntax><value>time</value></syntax>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
69 <default>60s</default>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
70 <context>mail</context>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
71 <context>server</context>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
72
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
73 <para>
1254
f49e326758c0 Mail auth: added description for the "auth_http_timeout" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1066
diff changeset
74 Sets the timeout for communication with the authentication server.
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
75 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
76
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
77 </directive>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
78
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
79 </section>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
80
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
81
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
82 <section id="protocol" name="Protocol">
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
83
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
84 <para>
1256
ebfcd76e23b6 Mail auth: corrected articles, rephrased some parts.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1255
diff changeset
85 The HTTP protocol is used to communicate with the authentication server.
ebfcd76e23b6 Mail auth: corrected articles, rephrased some parts.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1255
diff changeset
86 The data in the response body is ignored, the information is passed only in
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
87 the headers.
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
88 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
89
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
90 <para>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
91 Examples of requests and responses:
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
92 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
93
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
94 <para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
95 Request:
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
96 <example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
97 GET /auth HTTP/1.0
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
98 Host: localhost
1887
9af1e88e10c8 Documented SASL EXTERNAL support in mail.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1863
diff changeset
99 Auth-Method: plain # plain/apop/cram-md5/external
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
100 Auth-User: user
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
101 Auth-Pass: password
1063
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
102 Auth-Protocol: imap # imap/pop3/smtp
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
103 Auth-Login-Attempt: 1
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
104 Client-IP: 192.0.2.42
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
105 Client-Host: client.example.org
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
106 </example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
107 Good response:
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
108 <example>
1063
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
109 HTTP/1.0 200 OK
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
110 Auth-Status: OK
1063
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
111 Auth-Server: 198.51.100.1
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
112 Auth-Port: 143
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
113 </example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
114 Bad response:
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
115 <example>
1063
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
116 HTTP/1.0 200 OK
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
117 Auth-Status: Invalid login or password
1063
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
118 Auth-Wait: 3
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
119 </example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
120 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
121
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
122 <para>
1046
b81ad8234f90 Minor assorted fixes.
Sergey Kandaurov <pluknet@nginx.com>
parents: 966
diff changeset
123 If there is no <header>Auth-Wait</header> header,
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
124 an error will be returned and the connection will be closed.
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
125 The current implementation allocates memory for each authentication attempt.
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
126 The memory is freed only at the end of a session.
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
127 Therefore, the number of invalid authentication attempts in a single session
1046
b81ad8234f90 Minor assorted fixes.
Sergey Kandaurov <pluknet@nginx.com>
parents: 966
diff changeset
128 must be limited — the server must respond without
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
129 the <header>Auth-Wait</header> header after 10-20 attempts
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
130 (the attempt number is passed in the <header>Auth-Login-Attempt</header>
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
131 header).
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
132 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
133
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
134 <para>
1256
ebfcd76e23b6 Mail auth: corrected articles, rephrased some parts.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1255
diff changeset
135 When the APOP or CRAM-MD5 are used, request-response will look as follows:
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
136 <example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
137 GET /auth HTTP/1.0
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
138 Host: localhost
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
139 Auth-Method: apop
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
140 Auth-User: user
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
141 Auth-Salt: &lt;238188073.1163692009@mail.example.com&gt;
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
142 Auth-Pass: auth_response
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
143 Auth-Protocol: imap
1063
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
144 Auth-Login-Attempt: 1
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
145 Client-IP: 192.0.2.42
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
146 Client-Host: client.example.org
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
147 </example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
148 Good response:
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
149 <example>
1063
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
150 HTTP/1.0 200 OK
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
151 Auth-Status: OK
1063
6a19aadc15b2 Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1046
diff changeset
152 Auth-Server: 198.51.100.1
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
153 Auth-Port: 143
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
154 Auth-Pass: plain-text-pass
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
155 </example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
156 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
157
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
158 <para>
1256
ebfcd76e23b6 Mail auth: corrected articles, rephrased some parts.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1255
diff changeset
159 If the <header>Auth-User</header> header exists in the response,
1066
de77e295c073 Documented the "Auth-User" authentication header field.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1065
diff changeset
160 it overrides the username used to authenticate with the backend.
de77e295c073 Documented the "Auth-User" authentication header field.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1065
diff changeset
161 </para>
de77e295c073 Documented the "Auth-User" authentication header field.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1065
diff changeset
162
de77e295c073 Documented the "Auth-User" authentication header field.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1065
diff changeset
163 <para>
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
164 For the SMTP, the response additionally takes into account
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
165 the <header>Auth-Error-Code</header> header — if exists, it is used
1064
3ee0ba5f4f08 Updated description of the "Auth-Error-Code" header field.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1063
diff changeset
166 as a response code in case of an error.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
167 Otherwise, the 535 5.7.0 code will be added to
1256
ebfcd76e23b6 Mail auth: corrected articles, rephrased some parts.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1255
diff changeset
168 the <header>Auth-Status</header> header.
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
169 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
170
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
171 <para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
172 For example, if the following response is received
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
173 from the authentication server:
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
174 <example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
175 HTTP/1.0 200 OK
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
176 Auth-Status: Temporary server problem, try again later
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
177 Auth-Error-Code: 451 4.3.0
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
178 Auth-Wait: 3
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
179 </example>
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 671
diff changeset
180 then the SMTP client will receive an error
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
181 <example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
182 451 4.3.0 Temporary server problem, try again later
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
183 </example>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
184 </para>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
185
1065
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
186 <para>
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
187 If proxying SMTP does not require authentication,
1256
ebfcd76e23b6 Mail auth: corrected articles, rephrased some parts.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1255
diff changeset
188 the request will look as follows:
1065
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
189 <example>
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
190 GET /auth HTTP/1.0
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
191 Host: localhost
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
192 Auth-Method: none
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
193 Auth-User:
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
194 Auth-Pass:
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
195 Auth-Protocol: smtp
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
196 Auth-Login-Attempt: 1
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
197 Client-IP: 192.0.2.42
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
198 Client-Host: client.example.org
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
199 Auth-SMTP-Helo: client.example.org
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
200 Auth-SMTP-From: MAIL FROM: &lt;&gt;
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
201 Auth-SMTP-To: RCPT TO: &lt;postmaster@mail.example.com&gt;
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
202 </example>
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
203 </para>
88c0d96b9825 Documented the smtp_auth "none" method.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1064
diff changeset
204
1429
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
205 <para>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
206 For the SSL/TLS client connection (1.7.11),
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
207 the <header>Auth-SSL</header> header is added, and
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
208 <header>Auth-SSL-Verify</header> will contain
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
209 the result of client certificate verification, if
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
210 <link doc="ngx_mail_ssl_module.xml" id="ssl_verify_client">enabled</link>:
1863
fef4ab2d990c Removed unnecessary version for "FAILED:reason" in $ssl_client_verify.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1856
diff changeset
211 “<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”,
fef4ab2d990c Removed unnecessary version for "FAILED:reason" in $ssl_client_verify.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1856
diff changeset
212 and “<literal>NONE</literal>” if a certificate was not present.
1856
7133004fa5b3 $ssl_client_verify extended with a failure reason.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1429
diff changeset
213 <note>
7133004fa5b3 $ssl_client_verify extended with a failure reason.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1429
diff changeset
214 Prior to version 1.11.7, the “<literal>FAILED</literal>” result
7133004fa5b3 $ssl_client_verify extended with a failure reason.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1429
diff changeset
215 did not contain the <value>reason</value> string.
7133004fa5b3 $ssl_client_verify extended with a failure reason.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1429
diff changeset
216 </note>
1429
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
217 When the client certificate was present,
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
218 its details are passed in the following request headers:
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
219 <header>Auth-SSL-Subject</header>, <header>Auth-SSL-Issuer</header>,
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
220 <header>Auth-SSL-Serial</header>, and <header>Auth-SSL-Fingerprint</header>.
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
221 If <link id="auth_http_pass_client_cert"/> is enabled,
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
222 the certificate itself is passed in the
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
223 <header>Auth-SSL-Cert</header> header.
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
224 The request will look as follows:
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
225 <example>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
226 GET /auth HTTP/1.0
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
227 Host: localhost
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
228 Auth-Method: plain
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
229 Auth-User: user
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
230 Auth-Pass: password
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
231 Auth-Protocol: imap
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
232 Auth-Login-Attempt: 1
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
233 Client-IP: 192.0.2.42
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
234 Auth-SSL: on
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
235 Auth-SSL-Verify: SUCCESS
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
236 Auth-SSL-Subject: /CN=example.com
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
237 Auth-SSL-Issuer: /CN=example.com
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
238 Auth-SSL-Serial: C07AD56B846B5BFF
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
239 Auth-SSL-Fingerprint: 29d6a80a123d13355ed16b4b04605e29cb55a5ad
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
240 </example>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
241 </para>
06322891b4e3 Client certificate directives in mail_ssl_module and associates.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1256
diff changeset
242
664
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
243 </section>
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
244
8283b1048b27 Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
245 </module>