Skip to Content
Last modified by christoph_lechleitner@iteg_at on 2013-02-02 05.47:41
From version 2.1
edited by christoph_lechleitner@iteg_at
on 2012-09-21 12.40:24
Change comment: Completed operation list
To version 15.1
edited by christoph_lechleitner@iteg_at
on 2013-02-02 05.47:41
Change comment: Migrated to Confluence 5.3

Summary

Details

Page properties
Content
... ... @@ -1,8 +1,8 @@
1 1  == {{id name="HTTPauthenticationAPING-Motivation"/}}Motivation ==
2 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]].
3 +{{code language="none"}}org.clazzes.login.http{{/code}} is a the HTTP based implementation of [[DomainPasswordLoginService>>doc:LOGIN.DomainPasswordLoginService implementations and backends.WebHome]].
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>>doc:GWTBASICS.GWT implementations of http-util HttpLoginService.HTTP login service.HTTP login service backend-requests API.WebHome]] 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  
... ... @@ -57,15 +57,55 @@
57 57  * (% style="color: rgb(0,0,0);" %)a short message for logging (not more than 1024 bytes)
58 58  * (% style="color: rgb(0,0,0);" %)or a list of values separated by '{{code language="none"}},{{/code}}'
59 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"
60 +* (% style="color: rgb(0,0,0);" %)or '{{code language="none"}}--{{/code}}' for "not supported by backend"
61 61  
62 62  The server may enforce the use of HTTP basic authentication in order to keep offending servers away from dictionary attacks.
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 +{{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 +* (((
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 +
64 64  == {{id name="HTTPauthenticationAPING-Requiredoperations"/}}Required operations ==
65 65  
66 66  ==== {{id name="HTTPauthenticationAPING-tryLogin"/}}tryLogin ====
67 67  
68 -Request body (new format, preferred):
108 +====== {{id name="HTTPauthenticationAPING-Requestbody(newformat,preferred)"/}}Request body (new format, preferred) ======
69 69  
70 70  {{code}}
71 71  op=tryLogin&user=<user>&domain=<domain>&passwd=<passwd>
... ... @@ -74,25 +74,35 @@
74 74  
75 75  The {{code language="none"}}domain{{/code}} parameter is optional.
76 76  
77 -Request body in old format, supported for backward compatibility reasons:
117 +====== {{id name="HTTPauthenticationAPING-Requestbodyinoldformat,supportedforbackwardcompatibilityreasons"/}}Request body in old format, supported for backward compatibility reasons ======
78 78  
79 79  {{code}}
80 80  user=<user>&passwd=<passwd>
81 81  {{/code}}
82 82  
83 -Response body:
123 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body(% style="color: rgb(0,0,0);" %) (plain non-JSON variant)(%%) ======
84 84  
85 85  (% 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.
86 86  
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", "eMailAddress" : "jdoe@foo.bar" }
133 +{{/code}}
134 +
135 +Not found or problem: See documentation of "searchUser".
136 +
87 87  ==== {{id name="HTTPauthenticationAPING-getSupportedOperations"/}}getSupportedOperations ====
88 88  
89 -Request body (new format, preferred):
139 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
90 90  
91 91  {{code}}
92 92  op=getSupportedFeatures
93 93  {{/code}}
94 94  
95 -Response body:(% style="color: rgb(0,0,0);" %)
145 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body (plain non-JSON variant)(% style="color: rgb(0,0,0);" %) (%%) ======
96 96  
97 97  (% style="color: rgb(0,0,0);" %)List of suppored operations, separated by '{{code language="none"}},{{/code}}'.
98 98  
... ... @@ -108,6 +108,12 @@
108 108  getSupportedOperations,tryLogin,changePassword,deactivateUser,getDefaultDomain,getGroups,sendPassword,searchUser
109 109  {{/code}}
110 110  
161 +====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
162 +
163 +{{code language="none"}}
164 +[ "getSupportedOperations", "tryLogin" ]
165 +{{/code}}
166 +
111 111  == {{id name="HTTPauthenticationAPING-OptionalOperations"/}}(% style="color: rgb(0,0,0);" %)Optional Operations(%%) ==
112 112  
113 113  ==== {{id name="HTTPauthenticationAPING-changePassword"/}}changePassword ====
... ... @@ -114,7 +114,7 @@
114 114  
115 115  Changes the password of the user.
116 116  
117 -Request body:
173 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
118 118  
119 119  {{code}}
120 120  op=changePassword&user=<user>&domain=<domain>&oldPassword=<oldPassword>&newPassword=<newPassword>&newPasswordConfirmed=<newPassword>
... ... @@ -125,7 +125,7 @@
125 125  
126 126  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.
127 127  
128 -Response body:
184 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
129 129  
130 130  (% 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.
131 131  
... ... @@ -133,7 +133,7 @@
133 133  
134 134  Deactivates a user, prevents him for logging in again.
135 135  
136 -Request body:
192 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
137 137  
138 138  {{code}}
139 139  op=deactivateUser&user=<user>&domain=<domain>
... ... @@ -141,7 +141,7 @@
141 141  
142 142  The {{code language="none"}}domain{{/code}} parameter is optional.
143 143  
144 -Response body:
200 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
145 145  
146 146  (% 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.
147 147  
... ... @@ -149,7 +149,7 @@
149 149  
150 150  Returns the default domain, if there is any.
151 151  
152 -Request body (new format, preferred):
208 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
153 153  
154 154  {{code}}
155 155  op=getDefaultDomain
... ... @@ -156,31 +156,74 @@
156 156  
157 157  {{/code}}
158 158  
159 -Response body:(% style="color: rgb(0,0,0);" %)
215 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}Response body(% style="color: rgb(0,0,0);" %) (plain non-JSON variant) (%%) ======
160 160  
161 161  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.
162 162  
219 +====== {{id name="HTTPauthenticationAPING-Responsebody(JSONvariant)"/}}Response body (JSON variant) ======
220 +
221 +{{code language="none"}}
222 +[ "SOMEDOMAIN" ]
223 +{{/code}}
224 +
163 163  ==== {{id name="HTTPauthenticationAPING-getGroups"/}}getGroups ====
164 164  
165 165  Returns the groups the user is a member of.
166 166  
167 -Request body:
229 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
168 168  
169 169  {{code}}
170 -op=searchUser&user=<user>&domain=<domain>
232 +op=getGroups&user=<user>&domain=<domain>
171 171  {{/code}}
172 172  
173 173  The {{code language="none"}}domain{{/code}} parameter is optional.
174 174  
175 -Response body:
237 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}(% style="color: rgb(0, 0, 0); color: rgb(0, 0, 0)" %)Response body (plain non-JSON variant)(%%) ======
176 176  
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 +
177 177  (% 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.
178 178  
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 +
179 179  ==== {{id name="HTTPauthenticationAPING-sendPassword"/}}sendPassword ====
180 180  
181 181  Generates a new password or send a "new password" link to the user.
182 182  
183 -Request body:
282 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
184 184  
185 185  {{code}}
186 186  op=sendPassword&user=<user>&domain=<domain>
... ... @@ -189,7 +189,7 @@
189 189  
190 190  The {{code language="none"}}domain{{/code}} parameter is optional.
191 191  
192 -Response body:
291 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
193 193  
194 194  (% 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.
195 195  
... ... @@ -197,7 +197,7 @@
197 197  
198 198  Searches a user in the database, sets response code to 200 if the user is there, 404 if the user could not be found.
199 199  
200 -Request body:
299 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
201 201  
202 202  {{code}}
203 203  op=searchUser&user=<user>&domain=<domain>
... ... @@ -205,8 +205,26 @@
205 205  
206 206  The {{code language="none"}}domain{{/code}} parameter is optional.
207 207  
208 -Response body:
307 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
209 209  
210 210  (% 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.
211 211  
212 -
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 -688675
1 +688668
URL
... ... @@ -1,1 +1,1 @@
1 -https://clazzes.atlassian.net/wiki/spaces/LOGIN/pages/688675/HTTP authentication API NG
1 +https://clazzes.atlassian.net/wiki/spaces/LOGIN/pages/688668/HTTP authentication API NG