Skip to Content

Wiki source code of HTTP authentication API NG

Version 2.1 by christoph_lechleitner@iteg_at on 2012-09-21 12.40:24
Show last authors
1 == {{id name="HTTPauthenticationAPING-Motivation"/}}Motivation ==
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
9 == {{id name="HTTPauthenticationAPING-Contents"/}}Contents ==
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 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
24 op=<op>&param1=<value1>&param2=<value2>
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
30 To provide backwards compatibility, the {{code language="none"}}op{{/code}} parameter is optional and defaults to {{code language="none"}}tryLogin{{/code}}.
31
32 See below for detailed examples.
33
34 ==== {{id name="HTTPauthenticationAPING-BasicResponsepattern"/}}Basic Response pattern ====
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
48 404 Not found - if a user could not be found during a search operation
49 406 Not Acceptable - too many unsuccessful authentications, or other reason to suspect a brute force attack
50
51 {{/code}}
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.
54
55 (% style="color: rgb(0,0,0);" %)For most operations the reponse is either
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"
61
62 The server may enforce the use of HTTP basic authentication in order to keep offending servers away from dictionary attacks.
63
64 == {{id name="HTTPauthenticationAPING-Requiredoperations"/}}Required operations ==
65
66 ==== {{id name="HTTPauthenticationAPING-tryLogin"/}}tryLogin ====
67
68 Request body (new format, preferred):
69
70 {{code}}
71 op=tryLogin&user=<user>&domain=<domain>&passwd=<passwd>
72
73 {{/code}}
74
75 The {{code language="none"}}domain{{/code}} parameter is optional.
76
77 Request body in old format, supported for backward compatibility reasons:
78
79 {{code}}
80 user=<user>&passwd=<passwd>
81 {{/code}}
82
83 Response body:
84
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
87 ==== {{id name="HTTPauthenticationAPING-getSupportedOperations"/}}getSupportedOperations ====
88
89 Request body (new format, preferred):
90
91 {{code}}
92 op=getSupportedFeatures
93 {{/code}}
94
95 Response body:(% style="color: rgb(0,0,0);" %)
96
97 (% style="color: rgb(0,0,0);" %)List of suppored operations, separated by '{{code language="none"}},{{/code}}'.
98
99 (% style="color: rgb(0,0,0);" %)Example showing minimal feature set:
100
101 {{code language="none"}}
102 getSupportedOperations,tryLogin
103 {{/code}}
104
105 (% style="color: rgb(0,0,0);" %)Example specifying maximum feature set:
106
107 {{code language="none"}}
108 getSupportedOperations,tryLogin,changePassword,deactivateUser,getDefaultDomain,getGroups,sendPassword,searchUser
109 {{/code}}
110
111 == {{id name="HTTPauthenticationAPING-OptionalOperations"/}}(% style="color: rgb(0,0,0);" %)Optional Operations(%%) ==
112
113 ==== {{id name="HTTPauthenticationAPING-changePassword"/}}changePassword ====
114
115 Changes the password of the user.
116
117 Request body:
118
119 {{code}}
120 op=changePassword&user=<user>&domain=<domain>&oldPassword=<oldPassword>&newPassword=<newPassword>&newPasswordConfirmed=<newPassword>
121
122 {{/code}}
123
124 The {{code language="none"}}domain{{/code}} parameter is optional.
125
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
128 Response body:
129
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
132 ==== {{id name="HTTPauthenticationAPING-deactivateUser"/}}deactivateUser ====
133
134 Deactivates a user, prevents him for logging in again.
135
136 Request body:
137
138 {{code}}
139 op=deactivateUser&user=<user>&domain=<domain>
140 {{/code}}
141
142 The {{code language="none"}}domain{{/code}} parameter is optional.
143
144 Response body:
145
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
148 ==== {{id name="HTTPauthenticationAPING-getDefaultDomain"/}}getDefaultDomain ====
149
150 Returns the default domain, if there is any.
151
152 Request body (new format, preferred):
153
154 {{code}}
155 op=getDefaultDomain
156
157 {{/code}}
158
159 Response body:(% style="color: rgb(0,0,0);" %)
160
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
163 ==== {{id name="HTTPauthenticationAPING-getGroups"/}}getGroups ====
164
165 Returns the groups the user is a member of.
166
167 Request body:
168
169 {{code}}
170 op=searchUser&user=<user>&domain=<domain>
171 {{/code}}
172
173 The {{code language="none"}}domain{{/code}} parameter is optional.
174
175 Response body:
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.
178
179 ==== {{id name="HTTPauthenticationAPING-sendPassword"/}}sendPassword ====
180
181 Generates a new password or send a "new password" link to the user.
182
183 Request body:
184
185 {{code}}
186 op=sendPassword&user=<user>&domain=<domain>
187
188 {{/code}}
189
190 The {{code language="none"}}domain{{/code}} parameter is optional.
191
192 Response body:
193
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
196 ==== {{id name="HTTPauthenticationAPING-searchUser"/}}searchUser ====
197
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
200 Request body:
201
202 {{code}}
203 op=searchUser&user=<user>&domain=<domain>
204 {{/code}}
205
206 The {{code language="none"}}domain{{/code}} parameter is optional.
207
208 Response body:
209
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
212