The User Service Plugin provides the ability to manage 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.
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.
To provide a standard way of accessing the data the MUC Service is using REST.
| HTTP Method | Usage |
|---|---|
| GET | Receive a read-only data |
| PUT | Overwrite an existing resource |
| POST | Creates a new resource |
| DELETE | Deletes the given resource |
All REST Endpoint are secured by Basic HTTP Authentication or by shared secret key. The configuration can be done in Openfire Admin console under Server > Server Settings > User Service.
To access the endpoints is that required to send the Username and Password of a Openfire Admin account in your header request.
E.g. Header: Authorization: Basic YWRtaW46MTIzNDU= (username: admin / password: 12345)
Example for Jersey Client
Client c = Client.create();
c.addFilter(new HTTPBasicAuthFilter(user, password));
To access the endpoints is that required to send the secret key in your header request. The secret key can be defined in Openfire Admin console under Server > Server Settings > User Service.
E.g. Header: Authorization: s3cret
| Parameter | Optional | Description |
|---|---|---|
| username | No | The username of the user |
| name | Yes | The name of the user |
| Yes | The email of the user | |
| password | No | The password of the user |
| properties | Yes | List of properties. Property is a key / value object. The key must to be per user unique |
| Parameter | Optional | Description |
|---|---|---|
| jid | No | The JID of the roster item |
| nickname | Yes | The nickname for the user when used in this roster |
| subscriptionType | Yes | The subscription type Possible numeric values are: -1 (remove), 0 (none), 1 (to), 2 (from), 3 (both) |
| groups | No | A list of groups to organize roster entries under (e.g. friends, co-workers, etc.) |
Endpoint to get all users
Payload: none
Return value: Users
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| search | @QueryParam | Search/Filter by username. This act like the wildcard search %String% |
Header: Authorization: Basic YWRtaW46MTIzNDU=
GET http://example.org:9090/plugins/userService/users
GET http://example.org:9090/plugins/userService/users?search=testuser
Endpoint to get information over specific user
Payload: none
Return value: User
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
GET http://example.org:9090/plugins/userService/users/testuser
Endpoint to create a new user
Payload: User
Return value: HTTP status 201 (Created)
Header: Authorization: Basic YWRtaW46MTIzNDU=
Header: Content-Type: application/xml
POST http://example.org:9090/plugins/userService/users
Payload Example 1 (required parameters):
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
<username>test3</username>
<password>p4ssword</password>
</user>Payload Example 2 (available parameters):
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
<username>testuser</username>
<password>p4ssword</password>
<name>Test User</name>
<email>test@localhost.de</email>
<properties>
<property key="keyname" value="value"/>
<property key="anotherkey" value="value"/>
</properties>
</user>Endpoint to delete a user
Payload: none
Return value: HTTP status 200 (OK)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
DELETE http://example.org:9090/plugins/userService/users/testuser
Endpoint to update / overwrite a user
Payload: User
Return value: HTTP status 200 (OK)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
Header: Content-Type application/xml
PUT http://example.org:9090/plugins/userService/users/testuser
Payload:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
<username>testuser</username>
<name>Test User edit</name>
<email>test@edit.de</email>
<properties>
<property key="keyname" value="value"/>
</properties>
</user>Endpoint to get group names of a specific user
Payload: none
Return value: Groups
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
GET http://example.org:9090/plugins/userService/users/testuser/groups
Endpoint to add user to a group(s)
Payload: Groups
Return value: HTTP status 201 (Created)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
Header: Content-Type application/xml
POST http://example.org:9090/plugins/userService/users/testuser/groups
Payload:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<groups>
<groupname>Admins</groupname>
<groupname>Support</groupname>
</groups>Endpoint to remove a user from a group(s)
Payload: Groups
Return value: HTTP status 200 (OK)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
Header: Content-Type application/xml
DELETE http://example.org:9090/plugins/userService/users/testuser/groups
Payload:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<groups>
<groupname>Admins</groupname>
<groupname>Support</groupname>
</groups>Endpoint to lockout the user from the chat server
Payload: none
Return value: HTTP status 201 (Created)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
POST http://example.org:9090/plugins/userService/lockouts/testuser
Endpoint to unlock the user
Payload: none
Return value: HTTP status 200 (OK)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
DELETE http://example.org:9090/plugins/userService/lockouts/testuser
Endpoint to get roster entries (buddies) from a specific user
Payload: none
Return value: Roster
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
GET http://example.org:9090/plugins/userService/users/testuser/roster
Endpoint to add a new roster entry
Payload: RosterItem
Return value: HTTP status 201 (Created)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username |
Header: Authorization: Basic YWRtaW46MTIzNDU=
Header: Content-Type application/xml
POST http://example.org:9090/plugins/userService/users/testuser/roster
Payload:
Payload Example 1 (required parameters):
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rosterItem>
<jid>peter@pan.de</jid>
</rosterItem>Payload Example 2 (available parameters):
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rosterItem>
<jid>peter@pan1.de</jid>
<nickname>Peter1</nickname>
<subscriptionType>3</subscriptionType>
<groups>
<group>Friends</group>
</groups>
</rosterItem>Endpoint to remove a roster entry from a user
Payload: none
Return value: HTTP status 200 (OK)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username | |
| jid | @Path | JID of the roster item |
Header: Authorization: Basic YWRtaW46MTIzNDU=
DELETE http://example.org:9090/plugins/userService/users/testuser/roster/peter@pan.de
Endpoint to update a roster entry
Payload: RosterItem
Return value: HTTP status 200 (OK)
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| username | @Path | Exact username | |
| jid | @Path | JID of the roster item |
Header: Authorization: Basic YWRtaW46MTIzNDU=
Header: Content-Type application/xml
PUT http://example.org:9090/plugins/userService/users/testuser/roster/peter@pan.de
Payload:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rosterItem>
<jid>peter@pan.de</jid>
<nickname>Peter Pan</nickname>
<subscriptionType>0</subscriptionType>
<groups>
<group>Support</group>
</groups>
</rosterItem>Endpoint to get users which have the specific property key name
Payload: none
Return value: Users
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| keyname | @Path | Property key name |
Header: Authorization: Basic YWRtaW46MTIzNDU=
GET http://example.org:9090/plugins/userService/properties/keyname
Endpoint to get users which have the specific property key name and key value
Payload: none
Return value: Users
| Parameter | Parameter Type | Description | Default value |
|---|---|---|---|
| keyname | @Path | Property key name | |
| keyvalue | @Path | Property key value |
Header: Authorization: Basic YWRtaW46MTIzNDU=
GET http://example.org:9090/plugins/userService/properties/keyname/keyvalue
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.
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.
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.
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:
| Name | Description | |
|---|---|---|
| type | Required | The admin service required. Possible values are ‘add’, ‘delete’, ‘update’, ‘enable’, ‘disable’, ‘add_roster’, ‘update_roster’, ‘delete_roster’, ‘grouplist’, ‘usergrouplist’. |
| secret | Required | The secret key that allows access to the User Service. |
| username | Required | The username of the user to ‘add’, ‘delete’, ‘update’, ‘enable’, ‘disable’, ‘add_roster’, ‘update_roster’, ‘delete_roster’. ie the part before the @ symbol. |
| password | Required for ‘add’ operation | The password of the new user or the user being updated. |
| name | Optional | 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. |
| Optional | The email address of the new user or the user being updated. | |
| groups | Optional | 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. 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. |
| item_jid | Required for ‘add_roster’, ‘update_roster’, ‘delete_roster’ operations. | The JID of the roster item |
| subscription | Optional | Type of subscription for ‘add_roster’, ‘update_roster’ operations. Possible numeric values are: -1(remove), 0(none), 1(to), 2(from), 3(both). |
The following example adds a user
The following example adds a user, adds two shared groups (if not existing) and adds the user to both groups.
The following example deletes a user and all roster items of the user.
http://example.com:9090/plugins/userService/userservice?type=delete&secret=bigsecret&username=kafka
The following example disables a user (lockout)
http://example.com:9090/plugins/userService/userservice?type=disable&secret=bigsecret&username=kafka
The following example enables a user (removes lockout)
http://example.com:9090/plugins/userService/userservice?type=enable&secret=bigsecret&username=kafka
The following example updates a user
The following example adds new roster item with subscription ‘both’ for user ‘kafka’
The following example adds new roster item with subscription ‘both’ for user ‘kafka’ and adds kafka to roster groups ‘family’ and ‘friends’
The following example updates existing roster item to subscription ‘none’ for user ‘kafka’
The following example deletes a specific roster item ‘franz@kafka.com’ for user ‘kafka’
The following example gets all groups
http://example.com:9090/plugins/userService/userservice?type=grouplist&secret=bigsecret
Which replies an XML group list formatted like this:
<result>
<groupname>group1</groupname>
<groupname>group2</groupname>
</result>The following example gets all groups for a specific user
http://example.com:9090/plugins/userService/userservice?type=usergrouplist&secret=bigsecret&username=kafka
Which replies an XML group list formatted like this:
<result>
<groupname>usergroup1</groupname>
<groupname>usergroup2</groupname>
</result>* 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.
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”, or an XML grouplist formatted like in the example for “grouplist” and “usergrouplist” above. If the request was unsuccessful, the return will be an “error” element with a text body of one of the following error strings.
| Error String | Description |
|---|---|
| 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. For ‘update_roster’ operation, roster item to be updated was not found. |
| UserAlreadyExistsException | 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. |
| 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. |
| SharedGroupException | Roster item can not be added/deleted to/from a shared group for operations with roster. |