Mercurial > hg > nginx-site
annotate xml/en/docs/mail/ngx_mail_auth_http_module.xml @ 1063:6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
This includes:
- switch to documentation IP-addresses as per rfc5737
- language neutral comments
- addition of the "Client-Host" header field
author | Sergey Kandaurov <pluknet@nginx.com> |
---|---|
date | Sat, 08 Feb 2014 17:42:39 +0400 |
parents | b81ad8234f90 |
children | 3ee0ba5f4f08 |
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" |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
13 rev="1"> |
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. |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
25 The protocol is described below. |
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> |
966 | 38 Appends the specified header to requests to the authentication server. |
39 This header can be used as the shared secret to verify | |
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 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
50 <directive name="auth_http_timeout"> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
51 <syntax><value>time</value></syntax> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
52 <default>60s</default> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
53 <context>mail</context> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
54 <context>server</context> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
55 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
56 <para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
57 </para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
58 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
59 </directive> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
60 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
61 </section> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
62 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
63 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
64 <section id="protocol" name="Protocol"> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
65 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
66 <para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
67 The HTTP is used to communicate with the authentication server. |
966 | 68 The data in the response body is ignored, and the information is passed only in |
69 the headers. | |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
70 </para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
71 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
72 <para> |
966 | 73 Examples of requests and responses: |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
74 </para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
75 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
76 <para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
77 Request: |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
78 <example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
79 GET /auth HTTP/1.0 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
80 Host: localhost |
1063
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
81 Auth-Method: plain # plain/apop/cram-md5 |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
82 Auth-User: user |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
83 Auth-Pass: password |
1063
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
84 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
|
85 Auth-Login-Attempt: 1 |
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
86 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
|
87 Client-Host: client.example.org |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
88 </example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
89 Good response: |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
90 <example> |
1063
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
91 HTTP/1.0 200 OK |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
92 Auth-Status: OK |
1063
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
93 Auth-Server: 198.51.100.1 |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
94 Auth-Port: 143 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
95 </example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
96 Bad response: |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
97 <example> |
1063
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
98 HTTP/1.0 200 OK |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
99 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
|
100 Auth-Wait: 3 |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
101 </example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
102 </para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
103 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
104 <para> |
1046 | 105 If there is no <header>Auth-Wait</header> header, |
966 | 106 an error will be returned and the connection will be closed. |
107 The current implementation allocates memory for each authentication attempt. | |
108 The memory is freed only at the end of a session. | |
109 Therefore, the number of invalid authentication attempts in a single session | |
1046 | 110 must be limited — the server must respond without |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
111 the <header>Auth-Wait</header> header after 10-20 attempts |
966 | 112 (the attempt number is passed in the <header>Auth-Login-Attempt</header> |
113 header). | |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
114 </para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
115 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
116 <para> |
966 | 117 When the APOP or CRAM-MD5 are used, a request-response will look as follows. |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
118 <example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
119 GET /auth HTTP/1.0 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
120 Host: localhost |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
121 Auth-Method: apop |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
122 Auth-User: user |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
123 Auth-Salt: <238188073.1163692009@mail.example.com> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
124 Auth-Pass: auth_response |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
125 Auth-Protocol: imap |
1063
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
126 Auth-Login-Attempt: 1 |
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
127 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
|
128 Client-Host: client.example.org |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
129 </example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
130 Good response: |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
131 <example> |
1063
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
132 HTTP/1.0 200 OK |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
133 Auth-Status: OK |
1063
6a19aadc15b2
Updates and unification for mail_auth_http_module examples.
Sergey Kandaurov <pluknet@nginx.com>
parents:
1046
diff
changeset
|
134 Auth-Server: 198.51.100.1 |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
135 Auth-Port: 143 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
136 Auth-Pass: plain-text-pass |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
137 </example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
138 </para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
139 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
140 <para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
141 For the SMTP, the response additionally takes into account |
966 | 142 the <header>Auth-Error-Code</header> header — if exists, it is used |
143 as a response code. | |
144 Otherwise, the 535 5.7.0 code will be added to | |
145 the <header>Auth-Status</header>. | |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
146 </para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
147 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
148 <para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
149 For example, if the following response is received |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
150 from the authentication server: |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
151 <example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
152 HTTP/1.0 200 OK |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
153 Auth-Status: Temporary server problem, try again later |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
154 Auth-Error-Code: 451 4.3.0 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
155 Auth-Wait: 3 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
156 </example> |
966 | 157 then the SMTP client will receive an error |
664
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
158 <example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
159 451 4.3.0 Temporary server problem, try again later |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
160 </example> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
161 </para> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
162 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
163 </section> |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
164 |
8283b1048b27
Translated mail modules into English.
Vladimir Homutov <vl@nginx.com>
parents:
diff
changeset
|
165 </module> |