Skip to content

fixes #261: Drop the deprecated UserService functionality #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Fishbowler merged 1 commit into from
Sep 25, 2026
Merged

fixes #261: Drop the deprecated UserService functionality #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ <h1>
<p><b>1.12.1</b> (to be determined)</p>
<ul>
<li>Now requires Openfire 5.1.0 or later</li>
<li>[<a href="https://github.com/igniterealtime/openfire-restAPI-plugin/issues/261">#261</a>] - Remove the deprecated 'userservice' endpoint</li>
Comment thread
Fishbowler marked this conversation as resolved.
<li>[<a href="https://github.com/igniterealtime/openfire-restAPI-plugin/issues/259">#259</a>] - Prevent system property requests from affecting properties other than the one requested</li>
<li>[<a href="https://github.com/igniterealtime/openfire-restAPI-plugin/issues/256">#256</a>] - Record configuration changes in audit log</li>
<li>[<a href="https://github.com/igniterealtime/openfire-restAPI-plugin/issues/251">#251</a>] - Enable JUnit 5 tests</li>
Expand Down
105 changes: 0 additions & 105 deletions readme.html
View file
Open in desktop

Large diffs are not rendered by default.

115 changes: 0 additions & 115 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2230,118 +2230,3 @@ If you want to create a resource with JSON data format, please add "**Content-Ty
| userAddress | No | The JID of the user |
| role | No | Role of the user |
| affiliation | No | Affiliation of the user |

# (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

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 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/restapi/userservice. For example, if your server name is "example.com", the URL is http://example.com/plugins/restapi/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/restapi/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/restapi/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/restapi/userservice?type=delete&secret=bigsecret&username=kafka

The following example disables a user (lockout)

http://example.com:9090/plugins/restapi/userservice?type=disable&secret=bigsecret&username=kafka

The following example enables a user (removes lockout)

http://example.com:9090/plugins/restapi/userservice?type=enable&secret=bigsecret&username=kafka

The following example updates a user

http://example.com:9090/plugins/restapi/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/restapi/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/restapi/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/restapi/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/restapi/userservice?type=delete_roster&secret=bigsecret&username=kafka&item_jid=franz@example.com

The following example gets all groups

http://example.com:9090/plugins/restapi/userservice?type=grouplist&secret=bigsecret
Which replies an XML group list formatted like this:
```xml
<result>
<groupname>group1</groupname>
<groupname>group2</groupname>
</result>
```

The following example gets all groups for a specific user

http://example.com:9090/plugins/restapi/userservice?type=usergrouplist&secret=bigsecret&username=kafka
Which replies an XML group list formatted like this:
```xml
<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. |

6 changes: 0 additions & 6 deletions src/java/org/jivesoftware/openfire/plugin/rest/AuthFilter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,12 +76,6 @@ public void filter(ContainerRequestContext containerRequest) throws IOException
LOG.debug("Authentication was bypassed because of OPTIONS request");
return;
}

// To be backwards compatible to userservice 1.*
if (containerRequest.getUriInfo().getRequestUri().getPath().contains("restapi/v1/userservice")) {
LOG.info("Deprecated 'userservice' endpoint was used. Please switch to the new endpoints");
return;
}

if (!RESTServicePlugin.ALLOWED_IPS.getValue().isEmpty()) {
// Get client's IP address. Do not inspect headers like 'X-Forwarded-For' here: these can be spoofed by the client.
Expand Down
Loading
Loading