Skip to Content
Last modified by christoph_lechleitner@iteg_at on 2013-02-02 05.47:41
From version 3.1
edited by christoph_lechleitner@iteg_at
on 2012-09-23 03.00:15
Change comment: There is no comment for this version
To version 8.1
edited by christoph_lechleitner@iteg_at
on 2013-02-02 05.17:08
Change comment: There is no comment for this version

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>>confluencePage:page:OSGI.(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]] 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,15 +156,21 @@
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 170  op=getGroups&user=<user>&domain=<domain>
... ... @@ -172,15 +172,26 @@
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  
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.
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.
178 178  
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 +
179 179  ==== {{id name="HTTPauthenticationAPING-getGroupMembers"/}}getGroupMembers ====
180 180  
181 181  Returns the users the are a member of the specified group.
182 182  
183 -Request body:
256 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
184 184  
185 185  {{code}}
186 186  op=getGroupMembers&group=<group>&domain=<domain>
... ... @@ -188,15 +188,25 @@
188 188  
189 189  The {{code language="none"}}domain{{/code}} parameter is optional.
190 190  
191 -Response body:
264 +====== {{id name="HTTPauthenticationAPING-Responsebody(plainnon-JSONvariant)"/}}(% style="color: rgb(0,0,0);" %)Response body (plain non-JSON variant)(%%) ======
192 192  
193 193  (% 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.
194 194  
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 +
195 195  ==== {{id name="HTTPauthenticationAPING-sendPassword"/}}sendPassword ====
196 196  
197 197  Generates a new password or send a "new password" link to the user.
198 198  
199 -Request body:
282 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
200 200  
201 201  {{code}}
202 202  op=sendPassword&user=<user>&domain=<domain>
... ... @@ -205,7 +205,7 @@
205 205  
206 206  The {{code language="none"}}domain{{/code}} parameter is optional.
207 207  
208 -Response body:
291 +====== {{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  
... ... @@ -213,7 +213,7 @@
213 213  
214 214  Searches a user in the database, sets response code to 200 if the user is there, 404 if the user could not be found.
215 215  
216 -Request body:
299 +====== {{id name="HTTPauthenticationAPING-Requestbody"/}}Request body ======
217 217  
218 218  {{code}}
219 219  op=searchUser&user=<user>&domain=<domain>
... ... @@ -221,8 +221,26 @@
221 221  
222 222  The {{code language="none"}}domain{{/code}} parameter is optional.
223 223  
224 -Response body:
307 +====== {{id name="HTTPauthenticationAPING-Responsebody"/}}Response body ======
225 225  
226 226  (% 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.
227 227  
228 -
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 -688880
1 +688902
URL
... ... @@ -1,1 +1,1 @@
1 -https://clazzes.atlassian.net/wiki/spaces/LOGIN/pages/688880/HTTP authentication API NG
1 +https://clazzes.atlassian.net/wiki/spaces/LOGIN/pages/688902/HTTP authentication API NG