readme.html 6.46 KB
Newer Older
Gaston Dombiak's avatar
Gaston Dombiak committed
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
<!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 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 Wildfire 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 Wildfire 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 Wildfire admin console
This should really only be considered weak security. The plugin was initially written with the assumption that http access to the Wildfire service was
only available to trusted machines. In the case of the plugin's author, a web application running on the same server as 
Wildfire 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="700">
<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</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">jid</td><td>required for delete and update operations</td>
    <td>The bare JID (address) of the user to be administered(ie includes @yourdomain.com). 
    </td>
</tr>
<tr>
    <td class="name">username</td><td>required for add operation</td>
    <td>The username of the new user. 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.</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>


</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=franz@kafka.com
</textarea>
</form>
</ul>

The following example deletes a user

<ul>
<form>
<textarea cols=65 rows=4 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=delete&secret=bigsecret&jid=kafka@example.com
</textarea>
</form>
</ul>

This example updates a user

<ul>
<form>
<textarea cols=65 rows=3 wrap=virtual>
http://example.com:9090/plugins/userService/userservice?type=update&secret=bigsecret&jid=kafka@example.com&password=drowssap&name=franz&email=beetle@kafka.com
</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="700">
<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.</td>
</tr>
<tr>
    <td class="name">UserAlreadyExistsException</td>
    <td>A user with the same name as the user about to be added, already exists. 
    </td>
</tr>
<tr>
    <td class="name">RequestNotAuthorised</td>
    <td>The supplied secret does not match the secret specified in the Admin Console.</td>
</tr>
<tr>
    <td class="name">UserServiceDisabled</td>
    <td>The User Service is currently set to disabled in the Admin Console.</td>
</tr>


</table><p>


</body>
</html>