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

Important

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

CLI¶

Listing 183 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]
admin@localhost%

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.

WebUI¶

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

Fig. 168 Select OAuth profile

CLI¶

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

Note

GraphQL is only fully supported for JDBC data sources.

WebUI¶

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

Fig. 169 Selecting a User Account Data Source

CLI¶

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

WebUI¶

Fig. 170 Selecting Delegations Data Source

CLI¶

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

WebUI¶

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. 171 Adding Endpoints to the Profile

CLI¶

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

WebUI¶

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. 172 Exposing the new endpoints on the services.

CLI¶

Listing 188 Add the endpoints to a running node¶

admin@localhost% top
[ok][2017-08-21 15:05:29]

[edit]
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.

WebUI¶

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. 173 Commit the changes

CLI¶

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

Listing 189 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 190 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;
}

Username updates¶

The User Management Service can be configured to allow/disallow changing an account’s username via update requests submitted to the User Management APIs. This behavior is controlled by the Allow Username Updates option in the Data Sources section, which by default is set to false, meaning that any request which contains a username update is rejected.

When the User Management Service is configured to also allow updating user credentials, username updates become even more delicate, as credentials may be managed separately from the main user account data. In such cases, the system needs to propagate the username update to the configured Credential Manager to ensure that its data source is in sync with the main account data, which, depending on the capabilities of the Credential Manager’s data source, may not always be possible. However, if the Allow Username Updates option is enabled, the system will always accept username updates, even if a Credential Manager is not configured or if its data source does not support updating credential usernames.

If this feature is really required, the system administrator should ensure that the different parts of the setup support it. The system will log warning messages if it encounters a configuration that may lead to data inconsistency.