Skip to Content
Last modified by christoph_lechleitner@iteg_at on 2013-02-02 05.47:41
From version 1.1
edited by christoph_lechleitner@iteg_at
on 2012-09-21 11.47:16
Change comment: There is no comment for this version
To version 11.1
edited by christoph_lechleitner@iteg_at
on 2013-02-02 05.21:47
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,13 +1,19 @@
1 -=== {{id name="HTTPauthenticationAPING-Motivation"/}}Motivation ===
1 +== {{id name="HTTPauthenticationAPING-Motivation"/}}Motivation ==
2 2  
3 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 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.
5 +While the old [[HTTP authentication request>>confluencePage:page:UTIL.HTTP authentication requests towardshttp-util's HttpLoginService]] is satisfying for user/password checks, new optional features like group membership queries require new handshakes for the HTTP backend API.
6 6  
7 7  This document speficies the next-gen HTTP authentication API.
8 8  
9 -=== {{id name="HTTPauthenticationAPING-BasicRequestpattern"/}}Basic Request pattern ===
9 +== {{id name="HTTPauthenticationAPING-Contents"/}}Contents ==
10 10  
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 +
11 11  A request to an authentication URL is a HTTPS POST request like this:
12 12  
13 13  {{code}}
... ... @@ -15,17 +15,17 @@
15 15  Host: auth.my.domain
16 16  Content-Type: application/x-www-form-urlencoded
17 17  
18 -[op=<op>&]param1=<value1>&param2=<value2>
24 +op=<op>&param1=<value1>&param2=<value2>
19 19  
20 20  {{/code}}
21 21  
22 22  {{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"]].
23 23  
24 -To provide backwards compatibility, the op parameter is optional and defaults to {{code language="none"}}tryLogin{{/code}}.
30 +To provide backwards compatibility, the {{code language="none"}}op{{/code}} parameter is optional and defaults to {{code language="none"}}tryLogin{{/code}}.
25 25  
26 -See below for examples.
32 +See below for detailed examples.
27 27  
28 -=== {{id name="HTTPauthenticationAPING-BasicResponsepattern"/}}Basic Response pattern ===
34 +==== {{id name="HTTPauthenticationAPING-BasicResponsepattern"/}}Basic Response pattern ====
29 29  
30 30  Every respond to an authentication request is answered with a HTTP response with
31 31  
... ... @@ -39,33 +39,285 @@
39 39  {{code}}
40 40  200 OK - login is ok, or other operation was completed successfully
41 41  403 Forbidden - the login is invalid or the operation is not permitted
48 +404 Not found - if a user could not be found during a search operation
42 42  406 Not Acceptable - too many unsuccessful authentications, or other reason to suspect a brute force attack
43 43  
44 44  {{/code}}
45 45  
46 -(% style="color: rgb(0,0,0);" %)The response body must not be empty, it's content is specified differently for each operation.
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.
47 47  
48 -(% style="color: rgb(0,0,0);" %) (%%)The server may enforce the use of HTTP basic authentication in order to keep offending servers away from dictionary attacks.
55 +(% style="color: rgb(0,0,0);" %)For most operations the reponse is either
49 49  
50 -=== {{id name="HTTPauthenticationAPING-Authenticationoperation:tryLogin"/}}Authentication operation: tryLogin ===
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"
60 +* (% style="color: rgb(0,0,0);" %)or '{{code language="none"}}--{{/code}}' for "not supported by backend"
51 51  
52 -Request body (new format, preferred):
62 +The server may enforce the use of HTTP basic authentication in order to keep offending servers away from dictionary attacks.
53 53  
64 +===== {{id name="HTTPauthenticationAPING-JSONvariants"/}}JSON variants =====
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 +
54 54  {{code}}
55 -op=tryLogin&user=<user>&passwd=<passwd>
71 +POST /my/authentication/service HTTP/1.1
72 +Host: auth.my.domain
73 +Content-Type: application/x-www-form-urlencoded
56 56  
75 +op=<op>&json=1&param1=<value1>&param2=<value2>
57 57  {{/code}}
58 58  
59 -Request body in old format, supported for backward compatibility reasons:
78 +To explicitly disable JSON response, use {{code language="none"}}json=0{{/code}} instead.
60 60  
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 +* (((
86 +a short info message, like
87 +
88 +{{code language="none"}}
89 +{ "info" : "Some message to use in log files" }
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 +
104 +== {{id name="HTTPauthenticationAPING-Requiredoperations"/}}Required operations ==
105 +
106 +==== {{id name="HTTPauthenticationAPING-tryLogin"/}}tryLogin ====
107 +
108 +====== {{id name="HTTPauthenticationAPING-Requestbody(newformat,preferred)"/}}Request body (new format, preferred) ======
109 +
61 61  {{code}}
111 +op=tryLogin&user=<user>&domain=<domain>&passwd=<passwd>
112 +
113 +{{/code}}
114 +
115 +The {{code language="none"}}domain{{/code}} parameter is optional.
116 +
117 +====== {{id name="HTTPauthenticationAPING-Requestbodyinoldformat,supportedforbackwardcompatibilityreasons"/}}Request body in old format, supported for backward compatibility reasons ======
118 +
119 +{{code}}
62 62  user=<user>&passwd=<passwd>
63 63  {{/code}}
64 64  
65 -Response body:
123 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body(% style="color: rgb(0,0,0);" %) (plain non-JSON variant)(%%) ======
66 66  
67 -(% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Non-empty information text encoded in UTF-8, 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.
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.
68 68  
69 -=== {{id name="HTTPauthenticationAPING-Furtheroperations:TBD"/}}(% style="color: rgb(0,0,0);" %)Further operations: TBD(%%) ===
127 +====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}(% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Response body (JSON variant)(%%) ======
70 70  
71 -(% style="color: rgb(0,0,0);" %)\\
129 +(% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Successful:
130 +
131 +{{code language="none"}}
132 +{ "user" : "jdoe", "prettyName" : "John Doe", "eMailAddress" : "jdoe@foo.bar" }
133 +{{/code}}
134 +
135 +Not found or problem: See documentation of "searchUser".
136 +
137 +==== {{id name="HTTPauthenticationAPING-getSupportedOperations"/}}getSupportedOperations ====
138 +
139 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
140 +
141 +{{code}}
142 +op=getSupportedFeatures
143 +{{/code}}
144 +
145 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body (plain non-JSON variant)(% style="color: rgb(0,0,0);" %) (%%) ======
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 +
161 +====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
162 +
163 +{{code language="none"}}
164 +[ "getSupportedOperations", "tryLogin" ]
165 +{{/code}}
166 +
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 +
173 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
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 +
184 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
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 +
192 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
193 +
194 +{{code}}
195 +op=deactivateUser&user=<user>&domain=<domain>
196 +{{/code}}
197 +
198 +The {{code language="none"}}domain{{/code}} parameter is optional.
199 +
200 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
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 +
208 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
209 +
210 +{{code}}
211 +op=getDefaultDomain
212 +
213 +{{/code}}
214 +
215 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body(% style="color: rgb(0,0,0);" %) (plain non-JSON variant) (%%) ======
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 +
219 +====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
220 +
221 +{{code language="none"}}
222 +[ "SOMEDOMAIN" ]
223 +{{/code}}
224 +
225 +==== {{id name="HTTPauthenticationAPING-getGroups"/}}getGroups ====
226 +
227 +Returns the groups the user is a member of.
228 +
229 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
230 +
231 +{{code}}
232 +op=getGroups&user=<user>&domain=<domain>
233 +{{/code}}
234 +
235 +The {{code language="none"}}domain{{/code}} parameter is optional.
236 +
237 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}(% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Response body (plain non-JSON variant)(%%) ======
238 +
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.
240 +
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 +
252 +==== {{id name="HTTPauthenticationAPING-getGroupMembers"/}}getGroupMembers ====
253 +
254 +Returns the users the are a member of the specified group.
255 +
256 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
257 +
258 +{{code}}
259 +op=getGroupMembers&group=<group>&domain=<domain>
260 +{{/code}}
261 +
262 +The {{code language="none"}}domain{{/code}} parameter is optional.
263 +
264 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}(% style="color: rgb(0,0,0);" %)Response body (plain non-JSON variant)(%%) ======
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 +
268 +====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
269 +
270 +{{code language="none"}}
271 +[
272 + { "user" : "leonard", "prettyName" : "Leonard Hofstaetter", "eMailAddress" : "lh@tbbt.foo.bar" } ,
273 + { "user" : "penny" } ,
274 + { "user" : "sheldon" }
275 +]
276 +{{/code}}
277 +
278 +==== {{id name="HTTPauthenticationAPING-sendPassword"/}}sendPassword ====
279 +
280 +Generates a new password or send a "new password" link to the user.
281 +
282 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
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 +
291 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
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 +
299 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
300 +
301 +{{code}}
302 +op=searchUser&user=<user>&domain=<domain>
303 +{{/code}}
304 +
305 +The {{code language="none"}}domain{{/code}} parameter is optional.
306 +
307 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
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 +
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", "eMailAddress" : "jdoe@foo.bar" }
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}}
Confluence.Code.ConfluencePageClass[0]
Id
... ... @@ -1,1 +1,1 @@
1 -688674
1 +688982
URL
... ... @@ -1,1 +1,1 @@
1 -https://clazzes.atlassian.net/wiki/spaces/LOGIN/pages/688674/HTTP authentication API NG
1 +https://clazzes.atlassian.net/wiki/spaces/LOGIN/pages/688982/HTTP authentication API NG