Skip to Content

Wiki source code of HTTP authentication API NG

Version 6.1 by christoph_lechleitner@iteg_at on 2012-11-08 11.26:21
Hide last authors
christoph_lechleitner@iteg_at 2.1 1 == {{id name="HTTPauthenticationAPING-Motivation"/}}Motivation ==
christoph_lechleitner@iteg_at 1.1 2
3 {{code language="none"}}org.clazzes.login.http{{/code}} is a the HTTP based implementation of [[DomainPasswordLoginService>>confluencePage:page:LOGIN.(HTTP)Login Service NG: DomainPasswordLoginService]].
4
5 While the old [[HTTP authentication request>>confluencePage:page:LOGIN.HTTP authentication requests]] is satisfying for user/password checks, new optional features like group membership queries require new handshakes for the HTTP backend API.
6
7 This document speficies the next-gen HTTP authentication API.
8
christoph_lechleitner@iteg_at 2.1 9 == {{id name="HTTPauthenticationAPING-Contents"/}}Contents ==
christoph_lechleitner@iteg_at 1.1 10
christoph_lechleitner@iteg_at 2.1 11 {{toc depth="4" start="2"/}}
12
13 == {{id name="HTTPauthenticationAPING-BasicHandshakePattern"/}}Basic Handshake Pattern ==
14
15 ==== {{id name="HTTPauthenticationAPING-BasicRequestPattern"/}}Basic Request Pattern ====
16
christoph_lechleitner@iteg_at 1.1 17 A request to an authentication URL is a HTTPS POST request like this:
18
19 {{code}}
20 POST /my/authentication/service HTTP/1.1
21 Host: auth.my.domain
22 Content-Type: application/x-www-form-urlencoded
23
christoph_lechleitner@iteg_at 2.1 24 op=<op>&param1=<value1>&param2=<value2>
christoph_lechleitner@iteg_at 1.1 25
26 {{/code}}
27
28 {{code language="none"}}<op>{{/code}} is the operation requested, usually the name of the method in [[DomainPasswordLoginService.java>>url:https://svn.clazzes.org/svn/util/trunk/clazzes-util/src/main/java/org/clazzes/util/sec/DomainPasswordLoginService.java||shape="rect"]].
29
christoph_lechleitner@iteg_at 2.1 30 To provide backwards compatibility, the {{code language="none"}}op{{/code}} parameter is optional and defaults to {{code language="none"}}tryLogin{{/code}}.
christoph_lechleitner@iteg_at 1.1 31
christoph_lechleitner@iteg_at 2.1 32 See below for detailed examples.
christoph_lechleitner@iteg_at 1.1 33
christoph_lechleitner@iteg_at 2.1 34 ==== {{id name="HTTPauthenticationAPING-BasicResponsepattern"/}}Basic Response pattern ====
christoph_lechleitner@iteg_at 1.1 35
36 Every respond to an authentication request is answered with a HTTP response with
37
38 {{code}}
39 Content-Type: text/plain; charset=utf-8
40
41 {{/code}}
42
43 and on of the following status codes:
44
45 {{code}}
46 200 OK - login is ok, or other operation was completed successfully
47 403 Forbidden - the login is invalid or the operation is not permitted
christoph_lechleitner@iteg_at 2.1 48 404 Not found - if a user could not be found during a search operation
christoph_lechleitner@iteg_at 1.1 49 406 Not Acceptable - too many unsuccessful authentications, or other reason to suspect a brute force attack
50
51 {{/code}}
52
christoph_lechleitner@iteg_at 2.1 53 (% style="color: rgb(0,0,0);" %)The response body must not be empty and must be UTF-8 encoded, it's content is specified differently for each operation.
christoph_lechleitner@iteg_at 1.1 54
christoph_lechleitner@iteg_at 2.1 55 (% style="color: rgb(0,0,0);" %)For most operations the reponse is either
christoph_lechleitner@iteg_at 1.1 56
christoph_lechleitner@iteg_at 2.1 57 * (% style="color: rgb(0,0,0);" %)a short message for logging (not more than 1024 bytes)
58 * (% style="color: rgb(0,0,0);" %)or a list of values separated by '{{code language="none"}},{{/code}}'
59 * (% style="color: rgb(0,0,0);" %)or '{{code language="none"}}-{{/code}}' for "empty list"/"no data"
christoph_lechleitner@iteg_at 4.1 60 * (% style="color: rgb(0,0,0);" %)or '{{code language="none"}}--{{/code}}' for "not supported by backend"
christoph_lechleitner@iteg_at 1.1 61
christoph_lechleitner@iteg_at 2.1 62 The server may enforce the use of HTTP basic authentication in order to keep offending servers away from dictionary attacks.
63
christoph_lechleitner@iteg_at 6.1 64 ===== {{id name="HTTPauthenticationAPING-JSONvariants"/}}JSON variants =====
christoph_lechleitner@iteg_at 4.1 65
66 A backend may support to return the response in the form of small JSON documents.
67
68 To trigger json response, add the parameter {{code language="none"}}json=1{{/code}} to the request, like this:
69
70 {{code}}
71 POST /my/authentication/service HTTP/1.1
72 Host: auth.my.domain
73 Content-Type: application/x-www-form-urlencoded
74
75 op=<op>&json=1&param1=<value1>&param2=<value2>
76 {{/code}}
77
78 To explicitly disable JSON response, use {{code language="none"}}json=0{{/code}} instead.
79
80 Backends might choose to support only one variant, only with or only without JSON response.
81
82 With JSON reponses on, the repsonse is either
83
84 (% style="list-style-type: square;" %)
85 * (((
christoph_lechleitner@iteg_at 5.1 86 a short info message, like
christoph_lechleitner@iteg_at 4.1 87
88 {{code language="none"}}
christoph_lechleitner@iteg_at 5.1 89 { "info" : "Some message to use in log files" }
christoph_lechleitner@iteg_at 4.1 90 {{/code}}
91 )))
92 * (% style="color: rgb(0,0,0);" %)or a list of named values, for examples scroll down to the operation chapters
93 * (% style="color: rgb(0,0,0);" %)or a empty list if no data can be found
94 * (((
95 (% style="color: rgb(0,0,0);" %)or an error message for "not supported by backend" or similar problems, like
96
97 {{code language="none"}}
98 { "error" : "Operation not supported by backend for specified domain" }
99 {{/code}}
100
101 (% style="color: rgb(0,0,0);" %)\\
102 )))
103
christoph_lechleitner@iteg_at 2.1 104 == {{id name="HTTPauthenticationAPING-Requiredoperations"/}}Required operations ==
105
106 ==== {{id name="HTTPauthenticationAPING-tryLogin"/}}tryLogin ====
107
christoph_lechleitner@iteg_at 4.1 108 ====== {{id name="HTTPauthenticationAPING-Requestbody(newformat,preferred)"/}}Request body (new format, preferred) ======
christoph_lechleitner@iteg_at 1.1 109
110 {{code}}
christoph_lechleitner@iteg_at 2.1 111 op=tryLogin&user=<user>&domain=<domain>&passwd=<passwd>
christoph_lechleitner@iteg_at 1.1 112
113 {{/code}}
114
christoph_lechleitner@iteg_at 2.1 115 The {{code language="none"}}domain{{/code}} parameter is optional.
116
christoph_lechleitner@iteg_at 4.1 117 ====== {{id name="HTTPauthenticationAPING-Requestbodyinoldformat,supportedforbackwardcompatibilityreasons"/}}Request body in old format, supported for backward compatibility reasons ======
christoph_lechleitner@iteg_at 1.1 118
119 {{code}}
120 user=<user>&passwd=<passwd>
121 {{/code}}
122
christoph_lechleitner@iteg_at 5.1 123 ====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body(% style="color: rgb(0,0,0);" %) (plain non-JSON variant)(%%) ======
christoph_lechleitner@iteg_at 1.1 124
christoph_lechleitner@iteg_at 5.1 125 (% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Non-empty information text, not more (% style="color: rgb(0,0,0);" %)than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
christoph_lechleitner@iteg_at 1.1 126
christoph_lechleitner@iteg_at 5.1 127 ====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}(% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Response body (JSON variant)(%%) ======
128
129 (% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Successful:
130
131 {{code language="none"}}
132 { "user" : "jdoe", "prettyName" : "John Doe" }
133 {{/code}}
134
135 Not found or problem: See documentation of "searchUser".
136
christoph_lechleitner@iteg_at 2.1 137 ==== {{id name="HTTPauthenticationAPING-getSupportedOperations"/}}getSupportedOperations ====
christoph_lechleitner@iteg_at 1.1 138
christoph_lechleitner@iteg_at 4.1 139 ====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
christoph_lechleitner@iteg_at 2.1 140
141 {{code}}
142 op=getSupportedFeatures
143 {{/code}}
144
christoph_lechleitner@iteg_at 4.1 145 ====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body (plain non-JSON variant)(% style="color: rgb(0,0,0);" %) (%%) ======
christoph_lechleitner@iteg_at 2.1 146
147 (% style="color: rgb(0,0,0);" %)List of suppored operations, separated by '{{code language="none"}},{{/code}}'.
148
149 (% style="color: rgb(0,0,0);" %)Example showing minimal feature set:
150
151 {{code language="none"}}
152 getSupportedOperations,tryLogin
153 {{/code}}
154
155 (% style="color: rgb(0,0,0);" %)Example specifying maximum feature set:
156
157 {{code language="none"}}
158 getSupportedOperations,tryLogin,changePassword,deactivateUser,getDefaultDomain,getGroups,sendPassword,searchUser
159 {{/code}}
160
christoph_lechleitner@iteg_at 4.1 161 ====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
162
163 {{code language="none"}}
christoph_lechleitner@iteg_at 5.1 164 [ "getSupportedOperations", "tryLogin" ]
christoph_lechleitner@iteg_at 4.1 165 {{/code}}
166
christoph_lechleitner@iteg_at 2.1 167 == {{id name="HTTPauthenticationAPING-OptionalOperations"/}}(% style="color: rgb(0,0,0);" %)Optional Operations(%%) ==
168
169 ==== {{id name="HTTPauthenticationAPING-changePassword"/}}changePassword ====
170
171 Changes the password of the user.
172
christoph_lechleitner@iteg_at 4.1 173 ====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
christoph_lechleitner@iteg_at 2.1 174
175 {{code}}
176 op=changePassword&user=<user>&domain=<domain>&oldPassword=<oldPassword>&newPassword=<newPassword>&newPasswordConfirmed=<newPassword>
177
178 {{/code}}
179
180 The {{code language="none"}}domain{{/code}} parameter is optional.
181
182 The {{code language="none"}}newPasswordConfirmed{{/code}} parameter is optional and available only to simplify writing web interfaces. If it is specified and does not match {{code language="none"}}newPassword{{/code}}, the password is not changed.
183
christoph_lechleitner@iteg_at 4.1 184 ====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
christoph_lechleitner@iteg_at 2.1 185
186 (% style="color: rgb(0,0,0);" %)Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
187
188 ==== {{id name="HTTPauthenticationAPING-deactivateUser"/}}deactivateUser ====
189
190 Deactivates a user, prevents him for logging in again.
191
christoph_lechleitner@iteg_at 4.1 192 ====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
christoph_lechleitner@iteg_at 2.1 193
194 {{code}}
195 op=deactivateUser&user=<user>&domain=<domain>
196 {{/code}}
197
198 The {{code language="none"}}domain{{/code}} parameter is optional.
199
christoph_lechleitner@iteg_at 4.1 200 ====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
christoph_lechleitner@iteg_at 2.1 201
202 (% style="color: rgb(0,0,0);" %)Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
203
204 ==== {{id name="HTTPauthenticationAPING-getDefaultDomain"/}}getDefaultDomain ====
205
206 Returns the default domain, if there is any.
207
christoph_lechleitner@iteg_at 4.1 208 ====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
christoph_lechleitner@iteg_at 2.1 209
210 {{code}}
211 op=getDefaultDomain
212
213 {{/code}}
214
christoph_lechleitner@iteg_at 4.1 215 ====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body(% style="color: rgb(0,0,0);" %) (plain non-JSON variant) (%%) ======
christoph_lechleitner@iteg_at 2.1 216
217 Default authentication domain, or '{{code language="none"}}-{{/code}}' if there is no default domain, or '{{code language="none"}}--{{/code}}' if there is no domain support at all.
218
christoph_lechleitner@iteg_at 4.1 219 ====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
220
221 {{code language="none"}}
christoph_lechleitner@iteg_at 5.1 222 [ "SOMEDOMAIN" ]
christoph_lechleitner@iteg_at 4.1 223 {{/code}}
224
christoph_lechleitner@iteg_at 2.1 225 ==== {{id name="HTTPauthenticationAPING-getGroups"/}}getGroups ====
226
227 Returns the groups the user is a member of.
228
christoph_lechleitner@iteg_at 4.1 229 ====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
christoph_lechleitner@iteg_at 2.1 230
231 {{code}}
christoph_lechleitner@iteg_at 3.1 232 op=getGroups&user=<user>&domain=<domain>
christoph_lechleitner@iteg_at 2.1 233 {{/code}}
234
235 The {{code language="none"}}domain{{/code}} parameter is optional.
236
christoph_lechleitner@iteg_at 4.1 237 ====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}(% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Response body (plain non-JSON variant)(%%) ======
christoph_lechleitner@iteg_at 2.1 238
christoph_lechleitner@iteg_at 5.1 239 (% style="color: rgb(0,0,0);" %)List of group names, separated by '(% style="color: rgb(0,0,0);" %){{code language="none"}},{{/code}}' or just '(% style="color: rgb(0,0,0);" %){{code language="none"}}-{{/code}}' if the user is not member of any group, or '(% style="color: rgb(0,0,0);" %){{code language="none"}}--{{/code}}' if there is no group support.
christoph_lechleitner@iteg_at 2.1 240
christoph_lechleitner@iteg_at 5.1 241 ====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
242
243 The following example shows a list of 2 groups, one with maximum details, one wiht miniimal details:
244
245 {{code language="none"}}
246 [ 
247 { "group" : "users", "prettyName" : "Human users of this system", "domain" : "MYDOMAIN" } ,
248 { "group" : "dialout" }
249 ]
250 {{/code}}
251
christoph_lechleitner@iteg_at 3.1 252 ==== {{id name="HTTPauthenticationAPING-getGroupMembers"/}}getGroupMembers ====
253
254 Returns the users the are a member of the specified group.
255
christoph_lechleitner@iteg_at 4.1 256 ====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
christoph_lechleitner@iteg_at 3.1 257
258 {{code}}
259 op=getGroupMembers&group=<group>&domain=<domain>
260 {{/code}}
261
262 The {{code language="none"}}domain{{/code}} parameter is optional.
263
christoph_lechleitner@iteg_at 4.1 264 ====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}(% style="color: rgb(0,0,0);" %)Response body (plain non-JSON variant)(%%) ======
christoph_lechleitner@iteg_at 3.1 265
266 (% style="color: rgb(0,0,0);" %)List of group names, separated by '{{code language="none"}},{{/code}}' or just '{{code language="none"}}-{{/code}}' if the user is not member of any group, or '{{code language="none"}}--{{/code}}' if there is no group support.
267
christoph_lechleitner@iteg_at 5.1 268 ====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
269
270 {{code language="none"}}
271 [
272 { "user" : "leonard", "prettyName" : "Leonard Hofstaetter" } ,
273 { "user" : "penny" } ,
274 { "user" : "sheldon" }
275 ]
276 {{/code}}
277
christoph_lechleitner@iteg_at 2.1 278 ==== {{id name="HTTPauthenticationAPING-sendPassword"/}}sendPassword ====
279
280 Generates a new password or send a "new password" link to the user.
281
christoph_lechleitner@iteg_at 4.1 282 ====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
christoph_lechleitner@iteg_at 2.1 283
284 {{code}}
285 op=sendPassword&user=<user>&domain=<domain>
286
287 {{/code}}
288
289 The {{code language="none"}}domain{{/code}} parameter is optional.
290
christoph_lechleitner@iteg_at 4.1 291 ====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
christoph_lechleitner@iteg_at 2.1 292
293 (% style="color: rgb(0,0,0);" %)Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
294
295 ==== {{id name="HTTPauthenticationAPING-searchUser"/}}searchUser ====
296
297 Searches a user in the database, sets response code to 200 if the user is there, 404 if the user could not be found.
298
christoph_lechleitner@iteg_at 4.1 299 ====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
christoph_lechleitner@iteg_at 2.1 300
301 {{code}}
302 op=searchUser&user=<user>&domain=<domain>
303 {{/code}}
304
305 The {{code language="none"}}domain{{/code}} parameter is optional.
306
christoph_lechleitner@iteg_at 4.1 307 ====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
christoph_lechleitner@iteg_at 2.1 308
309 (% style="color: rgb(0,0,0);" %)Non-empty information text, not more than 1024 bytes. The message may go into logfiles and should not be displayed to the user.
310
christoph_lechleitner@iteg_at 5.1 311 ====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
312
313 Successful, with response code 200:
314
315 {{code language="none"}}
316 { "user" : "jdoe", "prettyName" : "John Doe" }
317 {{/code}}
318
319 Not found, with response code 404:
320
321 {{code language="none"}}
322 { "error" : "user not found" }
323 {{/code}}
324
325 Problem, with repsonse code 500:
326
327 {{code language="none"}}
328 { "error" : "Operation not supported by backend for specified domain" }
329 {{/code}}