Skip to Content
Last modified by christoph_lechleitner@iteg_at on 2013-02-02 05.47:41
From version 12.1
edited by christoph_lechleitner@iteg_at
on 2013-02-02 05.32:39
Change comment: There is no comment for this version
To 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

Summary

Details

Page properties
Content
... ... @@ -1,19 +1,13 @@
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:GWTBASICS.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.
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 6  
7 7  This document speficies the next-gen HTTP authentication API.
8 8  
9 -== {{id name="HTTPauthenticationAPING-Contents"/}}Contents ==
9 +=== {{id name="HTTPauthenticationAPING-BasicRequestpattern"/}}Basic Request pattern ===
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 -
17 17  A request to an authentication URL is a HTTPS POST request like this:
18 18  
19 19  {{code}}
... ... @@ -21,17 +21,17 @@
21 21  Host: auth.my.domain
22 22  Content-Type: application/x-www-form-urlencoded
23 23  
24 -op=<op>&param1=<value1>&param2=<value2>
18 +[op=<op>&]param1=<value1>&param2=<value2>
25 25  
26 26  {{/code}}
27 27  
28 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 29  
30 -To provide backwards compatibility, the {{code language="none"}}op{{/code}} parameter is optional and defaults to {{code language="none"}}tryLogin{{/code}}.
24 +To provide backwards compatibility, the op parameter is optional and defaults to {{code language="none"}}tryLogin{{/code}}.
31 31  
32 -See below for detailed examples.
26 +See below for examples.
33 33  
34 -==== {{id name="HTTPauthenticationAPING-BasicResponsepattern"/}}Basic Response pattern ====
28 +=== {{id name="HTTPauthenticationAPING-BasicResponsepattern"/}}Basic Response pattern ===
35 35  
36 36  Every respond to an authentication request is answered with a HTTP response with
37 37  
... ... @@ -45,285 +45,33 @@
45 45  {{code}}
46 46  200 OK - login is ok, or other operation was completed successfully
47 47  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
49 49  406 Not Acceptable - too many unsuccessful authentications, or other reason to suspect a brute force attack
50 50  
51 51  {{/code}}
52 52  
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.
46 +(% style="color: rgb(0,0,0);" %)The response body must not be empty, it's content is specified differently for each operation.
54 54  
55 -(% style="color: rgb(0,0,0);" %)For most operations the reponse is either
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.
56 56  
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"
50 +=== {{id name="HTTPauthenticationAPING-Authenticationoperation:tryLogin"/}}Authentication operation: tryLogin ===
61 61  
62 -The server may enforce the use of HTTP basic authentication in order to keep offending servers away from dictionary attacks.
52 +Request body (new format, preferred):
63 63  
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 -
70 70  {{code}}
71 -POST /my/authentication/service HTTP/1.1
72 -Host: auth.my.domain
73 -Content-Type: application/x-www-form-urlencoded
55 +op=tryLogin&user=<user>&passwd=<passwd>
74 74  
75 -op=<op>&json=1&param1=<value1>&param2=<value2>
76 76  {{/code}}
77 77  
78 -To explicitly disable JSON response, use {{code language="none"}}json=0{{/code}} instead.
59 +Request body in old format, supported for backward compatibility reasons:
79 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 -* (((
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 -
110 110  {{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}}
120 120  user=<user>&passwd=<passwd>
121 121  {{/code}}
122 122  
123 -====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body(% style="color: rgb(0,0,0);" %) (plain non-JSON variant)(%%) ======
65 +Response body:
124 124  
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.
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.
126 126  
127 -====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}(% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Response body (JSON variant)(%%) ======
69 +=== {{id name="HTTPauthenticationAPING-Furtheroperations:TBD"/}}(% style="color: rgb(0,0,0);" %)Further operations: TBD(%%) ===
128 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", "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}}
71 +(% style="color: rgb(0,0,0);" %)\\
Confluence.Code.ConfluencePageClass[0]
Id
... ... @@ -1,1 +1,1 @@
1 -688970
1 +688674
URL
... ... @@ -1,1 +1,1 @@
1 -https://clazzes.atlassian.net/wiki/spaces/LOGIN/pages/688970/HTTP authentication API NG
1 +https://clazzes.atlassian.net/wiki/spaces/LOGIN/pages/688674/HTTP authentication API NG