Mercurial > hg > nginx-site

comparison xml/en/docs/mail/ngx_mail_auth_http_module.xml @ 966:95c3c3bbf1ce

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Text review.
author Egor Nikitin <yegor.nikitin@gmail.com>
date Wed, 14 Aug 2013 12:03:41 +0400
parents 59def594b0c9
children b81ad8234f90
comparison
equal deleted inserted replaced
965:fadccc156188 966:95c3c3bbf1ce
33 <default/> 33 <default/>
34 <context>mail</context> 34 <context>mail</context>
35 <context>server</context> 35 <context>server</context>
36 36
37 <para> 37 <para>
38 Allows to append the specified header to requests to the authentication server. 38 Appends the specified header to requests to the authentication server.
39 Can be used as a shared secret to verify 39 This header can be used as the shared secret to verify
40 that the request came in from nginx. 40 that the request comes from nginx.
41 For example: 41 For example:
42 <example> 42 <example>
43 auth_http_header X-Auth-Key "secret_string"; 43 auth_http_header X-Auth-Key "secret_string";
44 </example> 44 </example>
45 </para> 45 </para>
63 63
64 <section id="protocol" name="Protocol"> 64 <section id="protocol" name="Protocol">
65 65
66 <para> 66 <para>
67 The HTTP is used to communicate with the authentication server. 67 The HTTP is used to communicate with the authentication server.
68 The data in the response body is ignored, information is passed only in headers. 68 The data in the response body is ignored, and the information is passed only in
69 the headers.
69 </para> 70 </para>
70 71
71 <para> 72 <para>
72 Requests and responses examples: 73 Examples of requests and responses:
73 </para> 74 </para>
74 75
75 <para> 76 <para>
76 Request: 77 Request:
77 <example> 78 <example>
98 Auth-Wait: 3 # wait for 3 seconds before returning an error to the client 99 Auth-Wait: 3 # wait for 3 seconds before returning an error to the client
99 </example> 100 </example>
100 </para> 101 </para>
101 102
102 <para> 103 <para>
103 If there is no the <header>Auth-Wait</header> header, 104 If there is no <header>Auth-Wait</header> header in a request,
104 the connection will be closed after returning an error. 105 an error will be returned and the connection will be closed.
105 The current implementation allocates memory per each authentication attempt, 106 The current implementation allocates memory for each authentication attempt.
106 which is freed only at the end of a session. 107 The memory is freed only at the end of a session.
107 Therefore a number of invalid authentication attempts in a single session 108 Therefore, the number of invalid authentication attempts in a single session
108 must be limited — the server must response without 109 must be limited — the server must response without
109 the <header>Auth-Wait</header> header after 10-20 attempts 110 the <header>Auth-Wait</header> header after 10-20 attempts
110 (see the <header>Auth-Login-Attempt</header> header). 111 (the attempt number is passed in the <header>Auth-Login-Attempt</header>
112 header).
111 </para> 113 </para>
112 114
113 <para> 115 <para>
114 When using the APOP or CRAM-MD5 request-response will look like: 116 When the APOP or CRAM-MD5 are used, a request-response will look as follows.
115 <example> 117 <example>
116 GET /auth HTTP/1.0 118 GET /auth HTTP/1.0
117 Host: localhost 119 Host: localhost
118 Auth-Method: apop 120 Auth-Method: apop
119 Auth-User: user 121 Auth-User: user
133 </example> 135 </example>
134 </para> 136 </para>
135 137
136 <para> 138 <para>
137 For the SMTP, the response additionally takes into account 139 For the SMTP, the response additionally takes into account
138 the <header>Auth-Error-Code</header> header — it is used 140 the <header>Auth-Error-Code</header> header — if exists, it is used
139 as a response code if exists. 141 as a response code.
140 Otherwise the code 535 5.7.0 will be added to 142 Otherwise, the 535 5.7.0 code will be added to
141 the <header>Auth-Status</header> by default. 143 the <header>Auth-Status</header>.
142 </para> 144 </para>
143 145
144 <para> 146 <para>
145 For example, if the following response is received 147 For example, if the following response is received
146 from the authentication server: 148 from the authentication server:
148 HTTP/1.0 200 OK 150 HTTP/1.0 200 OK
149 Auth-Status: Temporary server problem, try again later 151 Auth-Status: Temporary server problem, try again later
150 Auth-Error-Code: 451 4.3.0 152 Auth-Error-Code: 451 4.3.0
151 Auth-Wait: 3 153 Auth-Wait: 3
152 </example> 154 </example>
153 then the SMTP client will be given an error 155 then the SMTP client will receive an error
154 <example> 156 <example>
155 451 4.3.0 Temporary server problem, try again later 157 451 4.3.0 Temporary server problem, try again later
156 </example> 158 </example>
157 </para> 159 </para>
158 160