-
Notifications
You must be signed in to change notification settings - Fork 0
/
readme.html
292 lines (244 loc) · 9.97 KB
/
readme.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>User Service Plugin Readme</title>
<style type="text/css">
BODY {
font-size : 100%;
}
BODY, TD, TH {
font-family : tahoma, verdana, arial, helvetica, sans-serif;
font-size : 0.8em;
}
H2 {
font-size : 10pt;
font-weight : bold;
}
A:hover {
text-decoration : none;
}
H1 {
font-family : tahoma, arial, helvetica, sans-serif;
font-size : 1.4em;
font-weight: bold;
border-bottom : 1px #ccc solid;
padding-bottom : 2px;
}
TT {
font-family : courier new;
font-weight : bold;
color : #060;
}
PRE {
font-family : courier new;
font-size : 100%;
}
#datatable TH {
color : #fff;
background-color : #2A448C;
text-align : left;
}
#datatable TD {
background-color : #FAF6EF;
}
#datatable .name {
background-color : #DCE2F5;
}
</style>
</head>
<body>
<h1>
User Service Plugin Readme
</h1>
<h2>Overview</h2>
<p>
The User Service Plugin provides the ability to add,edit,delete users and manage their rosters by sending an http request to the server.
It is intended to be used by applications automating the user administration process.
This plugin's functionality is useful for applications that need to administer users outside of the Openfire admin console.
An example of such an application might be a live sports reporting application that uses XMPP as its transport, and
creates/deletes users according to the receipt, or non receipt, of a subscription fee.
</p>
<h2>Installation</h2>
<p>Copy userservice.jar into the plugins directory of your Openfire server. The
plugin will then be automatically deployed. To upgrade to a new version, copy the new
userservice.jar file over the existing file.</p>
<h2>Configuration</h2>
Access to the service is restricted with a "secret" that can be viewed and
set from the User Service page in the Openfire admin console. This page is
located on the admin console under "Server" and then "Server Settings".
This should really only be considered weak security. The plugin was initially written with the assumption that http access to the Openfire service was
only available to trusted machines. In the case of the plugin's author, a web application running on the same server as
Openfire makes the request.
<h2>Using the Plugin</h2>
To administer users, submit HTTP requests to the userservice service.
The service address is [hostname]plugins/userService/userservice. For example,
if your server name is "example.com", the URL is http://example.com/plugins/userService/userservice<p>
The following parameters can be passed into the request:<p>
<div id="datatable">
<table cellpadding="3" cellspacing="1" border="0" width="900">
<tr>
<th colspan=2>Name</th><th>Description</th>
</tr>
<tr>
<td class="name">type</td><td>Required</td><td>The admin service required.
Possible values are 'add', 'delete', 'update', 'enable', 'disable', 'add_roster', 'update_roster', 'delete_roster'.</td>
</tr>
<tr>
<td class="name">secret</td><td>Required</td>
<td>The secret key that allows access to the User Service.</td>
</tr>
<tr>
<td class="name">username</td><td>Required</td>
<td>The username of the user to 'add', 'delete', 'update', 'enable', 'disable', 'add_roster', 'update_roster', 'delete_roster'. ie the part before the @ symbol.</td>
</tr>
<tr>
<td class="name">password</td><td>Required for 'add' operation</td>
<td>The password of the new user or the user being updated.</td>
</tr>
<tr>
<td class="name">name</td><td>Optional</td>
<td>The display name of the new user or the user being updated. For 'add_roster', 'update_roster' operations specifies the nickname of the roster item.</td>
</tr>
<tr>
<td class="name">email</td><td>Optional</td>
<td>The email address of the new user or the user being updated.</td>
</tr>
<tr>
<td class="name">groups</td><td>Optional</td>
<td>
List of groups where the user is a member. Values are comma delimited. When used with types "add" or "update", it adds the user to shared groups and auto-creates new groups.<br/>
When used with 'add_roster' and 'update_roster', it adds the user to roster groups provided the group name does not clash with an existing shared group.
</td>
</tr>
<tr>
<td class="name">item_jid</td><td>Required for 'add_roster', 'update_roster', 'delete_roster' operations.</td>
<td>The JID of the roster item</td>
</tr>
<tr>
<td class="name">subscription</td><td>Optional</td>
<td>Type of subscription for 'add_roster', 'update_roster' operations. Possible numeric values are: -1(remove), 0(none), 1(to), 2(from), 3(both).</td>
</tr>
</table><p>
<p><b>Sample HTML</b><p>
The following example adds a user
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=add&secret=bigsecret&username=kafka&password=drowssap&name=franz&[email protected]
</textarea>
</form>
</ul>
The following example adds a user, adds two shared groups (if not existing) and adds the user to both groups.
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=add&secret=bigsecret&username=kafka&password=drowssap&name=franz&[email protected]&groups=support,finance
</textarea>
</form>
</ul>
The following example deletes a user and all roster items of the user.
<ul>
<form>
<textarea cols=65 rows=4 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=delete&secret=bigsecret&username=kafka
</textarea>
</form>
</ul>
The following example disables a user (lockout)
<ul>
<form>
<textarea cols=65 rows=4 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=disable&secret=bigsecret&username=kafka
</textarea>
</form>
</ul>
The following example enables a user (removes lockout)
<ul>
<form>
<textarea cols=65 rows=4 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=enable&secret=bigsecret&username=kafka
</textarea>
</form>
</ul>
The following example updates a user
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=update&secret=bigsecret&username=kafka&password=drowssap&name=franz&[email protected]
</textarea>
</form>
</ul>
The following example adds new roster item with subscription 'both' for user 'kafka'
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=add_roster&secret=bigsecret&username=kafka&[email protected]&name=franz&subscription=3
</textarea>
</form>
</ul>
The following example adds new roster item with subscription 'both' for user 'kafka' and adds kafka to roster groups 'family' and 'friends'
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=add_roster&secret=bigsecret&username=kafka&[email protected]&name=franz&subscription=3&groups=family,friends
</textarea>
</form>
</ul>
The following example updates existing roster item to subscription 'none' for user 'kafka'
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=update_roster&secret=bigsecret&username=kafka&[email protected]&name=franz&subscription=0
</textarea>
</form>
</ul>
The following example deletes a specific roster item '[email protected]' for user 'kafka'
<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=delete_roster&secret=bigsecret&username=kafka&[email protected]
</textarea>
</form>
</ul>
<br><br>
* When sending double characters (Chinese/Japanese/Korean etc) you should URLEncode the string as utf8.<br>
In Java this is done like this<br>
URLEncoder.encode(username, "UTF-8"));
<br>If the strings are encoded incorrectly, double byte characters will look garbeled in the Admin Console.
<h2>Server Reply</h2>
The server will reply to all User Service requests with an XML result page.
If the request was processed successfully the return will be a "result" element with a text body of "OK".
If the request was unsuccessful, the return will be an "error" element with a text body of one of the following error strings.
<p>
<div id="datatable">
<table cellpadding="3" cellspacing="1" border="0" width="900">
<tr>
<th >Error String</th><th>Description</th>
</tr>
<tr>
<td class="name">IllegalArgumentException</td>
<td>one of the parameters passed in to the User Service was bad.</td>
</tr>
<tr>
<td class="name">UserNotFoundException</td>
<td>No user of the name specified, for a delete or update operation, exists on this server. For 'update_roster' operation, roster item to be updated was not found.</td>
</tr>
<tr>
<td class="name">UserAlreadyExistsException</td>
<td>A user with the same name as the user about to be added, already exists. For 'add_roster' operation, roster item with the same JID already exists.</td>
</tr>
<tr>
<td class="name">RequestNotAuthorised</td>
<td>The supplied secret does not match the secret specified in the Admin Console or the requester is not a valid IP address.</td>
</tr>
<tr>
<td class="name">UserServiceDisabled</td>
<td>The User Service is currently set to disabled in the Admin Console.</td>
</tr>
<tr>
<td class="name">SharedGroupException</td>
<td>Roster item can not be added/deleted to/from a shared group for operations with roster.</td>
</tr>
</table><p>
</body>
</html>