Defining a User Management Service Profile

To use the User Management Service, a User Management Profile needs to be defined.

It requires the following components:

  • Token Service (mandatory) - The OAuth profile that is used to provide access control.
  • Authorization Manager (optional) - authorize access to the User Management API.
  • User data source (mandatory) - data source to use to manage user accounts.
  • Token data source (mandatory) - data source for the OAuth tokens.
  • Devices data source (optional) - data source for devices.

The Profile exposes the following endpoint-kinds:

  • um-api: a SCIM 2.0-like API which allows access to Users, Devices and Delegations

Preparing the User Management Service

The User Management Service requires a Token Service in order to be able to authorize access, for example against an SQL database or a SCIM backend webservice. This means that a oauth-service must be configured, then linked to from the User Management Service, as explained in the Profile configuration documentation.

If it is desired to configure in detail the authorization policies for each endpoint and resource type, an Authorization Manager may be configured as well.

Finally, data-sources must be configured for the User Management Service.

You may configure the following data-sources (which may point to the same data-source instance, or different ones):

  • user-account-data-source (mandatory).
  • token-data-source (mandatory).
  • devices-data-source (optional, if not configured, the user-account-data-source will be used).


When an Authorization Manager is configured to manage authorization policies on the User Management Service, the configured oauth-service must use the same user-account-data-source as the User Management Service so that authorization decisions may succeed. This is not currently enforced by configuration.

If you want to allow user credentials to be updated via the User Management Service, you must also configure a credential-manager.

Pre-requisite configuration

  • Data-Sources
  • Credential Managers
  • Token Issuers

Step by step guide to setup a User Management Service

This guide will walk through the mandatory settings that are needed in order to deploy the User Management service. It will illustrate the Web UI approach and then the same settings using the Command Line Interface

1. Add the profile

Web UI

Start by in the main screen of the Web User Interface in the top level menu called User Management click New Profile.

The following screen is shown. (The type is pre-selected to be um:user-management.


Fig. 166 Name the new profile

This will prompt you with a dialog requiring a name for the profile. This can be anything, but the name can be used to identity the profile in web-requests as the realm parameter, so picking a meaningful name is recommended.


Listing 197 Create a new profile
admin@localhost% edit profiles profile UserManagementService user-management-service settings user-management-service
[ok][2017-08-21 14:48:11]

[edit profiles profile UserManagementService user-management-service settings user-management-service]

This adds the base for the new profile and navigates the admin down to the configuration of the profile at the same time

2. Select OAuth Service

The next step is to select an OAuth profile that should be used to protect the API. All requests to the API need an access token issued by the selected OAuth profile.


In the General page of the new User Management profile select an existing OAuth profile.


Fig. 167 Select OAuth profile


Listing 198 Select OAuth service to use for API authentication. oauth-dev is selected in this example.
admin@localhost% set api-authentication oauth-service oauth-dev
[ok][2017-08-21 14:55:57]

3. Select User Account Data Source

The main purpose of the User Management Service is to show user profiles. This means user account information. Therefore the profile needs to be configured with an User Account Data Source. This is the data source where the primary account is stored.

There are two options, either select an account manager or data sources directly. The first is needed when using the GraphQL API as it allows the system to find related Linked Accounts. If those are not needed, then the data sources can be set directly. When selecting an account manager the system uses that to determine what data sources to use.


GraphQL is only fully supported for JDBC data sources.


Click Data Sources in the left-hand menu and then select the data source to use as primary data source in the dropdown.


Fig. 168 Selecting a User Account Data Source


Listing 199 Select Accounts Data Source
admin@localhost% set user-account-data-source Win01AD
[ok][2017-08-21 14:58:33]

4. Select OAuth Delegations Data Source

Next to the users data source dropdown, is the OAuth Delegations dropdown. Here you should select the data-source where all the tokens are stored. This is so the User Management profile can provide the token information (not the tokens themselves) that belongs to a user via the delegations endpoint. This means that and admin can revoke and view tokens issued for a specific user.



Fig. 169 Selecting Delegations Data Source


Listing 200 Select Delegations Data Source
admin@localhost% set token-data-source DefaultHSQLDB
[ok][2017-08-21 14:59:54]

5. Setting up the endpoints

The last required step is to setup the endpoints that should be exposed. If delegations aren’t needed then that option can be omitted.


Click the Endpoints page in the left hand menu, and add two new rows. Name the endpoints appropriately, this is used when deploying them on a node. Set a path to the each endpoint, this will be the path they are accessed by in the API.

Create one endpoint of type um-api.


Fig. 170 Adding Endpoints to the Profile


In this step we need to move up in the configuration tree a few levels since the endpoints are configured directly on the profile, and not down in the settings where we’ve been operating. Note the response from the CLI to see where in the tree the CLI is standing.

Listing 201 Create the endpoints for the User Management Service
admin@localhost% up
[ok][2017-08-21 15:01:57]

[edit profiles profile UserManagementService user-management-service settings]
admin@localhost% up
[ok][2017-08-21 15:01:58]

[edit profiles profile UserManagementService user-management-service]
admin@localhost% set endpoints endpoint um-api1 endpoint-kind um-api uri /um/api
[ok][2017-08-21 15:03:19]

6. Exposing the Endpoints on a Service (node)

With the above 5 steps the profile exists and is active. But it’s not reachable before the endpoints are exposed on a service (node).


Click System in the top menu bar, followed by Deployments on the lefthand menu.

Select the node that should expose the service (repeat the steps if the endpoints should be deployed on more than one node).

Scroll down to the end of the modal that opened to the Endpoints input box. By clicking in the box, it will show the possible endpoints that can be deployed, and the new endpoints should show up as options. Add the endpoints.


Fig. 171 Exposing the new endpoints on the services.


Listing 202 Add the endpoints to a running node
admin@localhost% top
[ok][2017-08-21 15:05:29]

admin@localhost% set environments environment services service TestServer1 endpoints um-api1
[ok][2017-08-21 15:05:43]

7. Commit the changes

Now the only step left is to commit the changes, which effectively validates the config and then deploys it to the running configuration of the cluster.


To deploy, click the Changes menu on the top menu and select Commit. A dialog is shown where the user can enter a comment. This is will be kept in the revision history.


Fig. 172 Commit the changes


It is optional but recommended to add a comment in the CLI when committing.

Listing 203 Commit the changes
admin@localhost% commit comment "Added new User Management Service and deployed it to node TestServer1"
Commit complete.
[ok][2017-08-21 15:09:22]

Password validation

When the option Enable Password Management under the Credentials pane in the Data Sources tab is enabled, the Password Validation Procedure can be selected for validating the user password.

More about how to configure the validation procedure could be found here Validation procedures

Listing 204 Example of the password validating script
function result(context) {
    var MIN = 8;
    var MAX = 12;
    var errors = {};

  var password = context.getProvidedPassword();

    if (password.length < MIN) {
        errors.password = 'Password too short';
    if (password.length > MAX) {
        errors.password = 'Password too long';

    return errors;