User Service Plugin Readme

Overview

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 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.

Installation

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.

Configuration

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 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.

Using the Plugin

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

The following parameters can be passed into the request:

NameDescription
typeRequiredThe admin service required. Possible values are add, delete, update
secretRequired The secret key that allows access to the User Service.
usernameRequired The username of the user to add, update or delete. ie the part before the @ symbol.
passwordRequired for add operation The password of the new user or the user being updated.
nameOptional The display name of the new user or the user being updated.
emailOptional The email address of the new user or the user being updated.
groupsOptional List of groups where the user is a member. Values are comma delimited.

Sample HTML

The following example adds a user

The following example deletes a user This example updates a user

* When sending double characters (Chinese/Japanese/Korean etc) you should URLEncode the string as utf8.
In Java this is done like this
URLEncoder.encode(username, "UTF-8"));
If the strings are encoded incorrectly, double byte characters will look garbeled in the Admin Console.

Server Reply

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.

Error StringDescription
IllegalArgumentException one of the parameters passed in to the User Service was bad.
UserNotFoundException No user of the name specified, for a delete or update operation, exists on this server.
UserAlreadyExistsException A user with the same name as the user about to be added, already exists.
RequestNotAuthorised The supplied secret does not match the secret specified in the Admin Console or the requester is not a valid IP address.
UserServiceDisabled The User Service is currently set to disabled in the Admin Console.