Below is a list of versions that are available for the userservice plugin. To find other plugins, please review this listing of most recent releases of all plugins.

Plugins extend and enhance the functionality of Openfire. To install plugins, copy the .jar file into the plugins directory of your Openfire installation.

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.

User Service Plugin Readme
User related REST Endpoints
(Deprecated) User Service Plugin Readme

Feature list

Get overview over all or specific user and to create, update or delete a user
Get overview over all user roster entries and to add, update or delete a roster entry
Add user to a group and remove a user from a group
Lockout or unlock the user (enable / disable)

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.

Explanation of REST

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

Authentication

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.

Basic HTTP Authentication

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));

Shared secret key

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

Data types

User

Parameter	Optional	Description
username	No	The username of the user
name	Yes	The name of the user
email	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

RosterItem

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

User related REST Endpoints

GET /userService/users

Endpoint to get all users

Payload: none
Return value: Users

Possible parameters

Parameter	Parameter Type	Description	Default value
search	@QueryParam	Search/Filter by username. This act like the wildcard search %String%

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/userService/users

GET http://example.org:9090/plugins/userService/users?search=testuser

GET /userService/users/{username}

Endpoint to get information over specific user

Payload: none
Return value: User

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/userService/users/testuser

POST /userService/users

Endpoint to create a new user

Payload: User
Return value: HTTP status 201 (Created)

Examples

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>

DELETE /userService/users/{username}

Endpoint to delete a user

Payload: none
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

DELETE http://example.org:9090/plugins/userService/users/testuser

PUT /userService/users/{username}

Endpoint to update / overwrite a user

Payload: User
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

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>

GET /userService/users/{username}/groups

Endpoint to get group names of a specific user

Payload: none
Return value: Groups

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/userService/users/testuser/groups

POST /userService/users/{username}/groups

Endpoint to add user to a group(s)

Payload: Groups
Return value: HTTP status 201 (Created)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

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>

DELETE /userService/users/{username}/groups

Endpoint to remove a user from a group(s)

Payload: Groups
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

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>

POST /userService/lockouts/{username}

Endpoint to lockout the user from the chat server

Payload: none
Return value: HTTP status 201 (Created)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

POST http://example.org:9090/plugins/userService/lockouts/testuser

DELETE /userService/lockouts/{username}

Endpoint to unlock the user

Payload: none
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

DELETE http://example.org:9090/plugins/userService/lockouts/testuser

GET /userService/users/{username}/roster

Endpoint to get roster entries (buddies) from a specific user

Payload: none
Return value: Roster

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/userService/users/testuser/roster

POST /userService/users/{username}/roster

Endpoint to add a new roster entry

Payload: RosterItem
Return value: HTTP status 201 (Created)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username

Examples

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>

DELETE /userService/users/{username}/roster/{jid}

Endpoint to remove a roster entry from a user

Payload: none
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username
jid	@Path	JID of the roster item

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

DELETE http://example.org:9090/plugins/userService/users/testuser/roster/peter@pan.de

PUT /userService/users/{username}/roster/{jid}

Endpoint to update a roster entry

Payload: RosterItem
Return value: HTTP status 200 (OK)

Possible parameters

Parameter	Parameter Type	Description	Default value
username	@Path	Exact username
jid	@Path	JID of the roster item

Examples

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>

GET /userService/properties/{keyname}

Endpoint to get users which have the specific property key name

Payload: none
Return value: Users

Possible parameters

Parameter	Parameter Type	Description	Default value
keyname	@Path	Property key name

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/userService/properties/keyname

GET /userService/properties/{keyname}/{keyvalue}

Endpoint to get users which have the specific property key name and key value

Payload: none
Return value: Users

Possible parameters

Parameter	Parameter Type	Description	Default value
keyname	@Path	Property key name
keyvalue	@Path	Property key value

Examples

Header: Authorization: Basic YWRtaW46MTIzNDU=

GET http://example.org:9090/plugins/userService/properties/keyname/keyvalue

(Deprecated) User Service Plugin Readme

Overview

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.

Installation

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

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:

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

Sample HTML

The following example adds a user

http://example.com:9090/plugins/userService/userservice?type=add&secret=bigsecret&username=kafka&password=drowssap&name=franz&email=franz@kafka.com

The following example adds a user, adds two shared groups (if not existing) and adds the user to both groups.

http://example.com:9090/plugins/userService/userservice?type=add&secret=bigsecret&username=kafka&password=drowssap&name=franz&email=franz@kafka.com&groups=support,finance

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

http://example.com:9090/plugins/userService/userservice?type=update&secret=bigsecret&username=kafka&password=drowssap&name=franz&email=beetle@kafka.com

The following example adds new roster item with subscription ‘both’ for user ‘kafka’

http://example.com:9090/plugins/userService/userservice?type=add_roster&secret=bigsecret&username=kafka&item_jid=franz@example.com&name=franz&subscription=3

The following example adds new roster item with subscription ‘both’ for user ‘kafka’ and adds kafka to roster groups ‘family’ and ‘friends’

http://example.com:9090/plugins/userService/userservice?type=add_roster&secret=bigsecret&username=kafka&item_jid=franz@example.com&name=franz&subscription=3&groups=family,friends

The following example updates existing roster item to subscription ‘none’ for user ‘kafka’

http://example.com:9090/plugins/userService/userservice?type=update_roster&secret=bigsecret&username=kafka&item_jid=franz@example.com&name=franz&subscription=0

The following example deletes a specific roster item ‘franz@kafka.com’ for user ‘kafka’

http://example.com:9090/plugins/userService/userservice?type=delete_roster&secret=bigsecret&username=kafka&item_jid=franz@example.com

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.

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

Releases

Info

File

Version

Released

Openfire Version

	User Service
(Deprecated) Please use the REST API Plugin. Allows administration of users via HTTP requests.

Download

2.1.3

Thu Sep 12 13:52:44 UTC 2024

4.0.0 +

	User Service
(Deprecated) Please use the REST API Plugin. Allows administration of users via HTTP requests.

Download

2.1.2

Thu Nov 12 00:00:00 UTC 2020

4.0.0 +

	User Service
(Deprecated) Please use the REST API Plugin. Allows administration of users via HTTP requests.

Download

2.1.0

Mon Oct 12 00:00:00 UTC 2015

4.0.0 +

	User Service
Allows administration of users via HTTP requests.

Download

2.0.2

Wed Oct 08 00:00:00 UTC 2014

3.9.0 +

	User Service
Allows administration of users via HTTP requests.

Download

1.4.3

Mon May 05 00:00:00 UTC 2014

3.9.0 +

	User Service
Allows administration of users via HTTP requests.

Download

1.3.3

Wed May 22 00:00:00 UTC 2013

3.5.1 +

	User Service
Allows administration of users via HTTP requests.

Download

1.3.0

Fri Oct 12 00:00:00 UTC 2007

3.3.0 +

The plugins below, so-called SNAPSHOTS, are build automatically by the continuous integration system. They represent the latest development, but are untested.

Snapshots

Info

File

Version

Built at

Openfire Version