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.

../_images/um-setup-01.png

Fig. 165 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 244 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.

../_images/um-setup-02.png

Fig. 166 Select OAuth profile

CLI

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

WebUI

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

../_images/um-setup-03.png

Fig. 167 Selecting a User Account Data Source

CLI

Listing 246 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

../_images/um-setup-04.png

Fig. 168 Selecting Delegations Data Source

CLI

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

../_images/um-setup-05.png

Fig. 169 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 248 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.

../_images/um-setup-06.png

Fig. 170 Exposing the new endpoints on the services.

CLI

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

../_images/um-setup-07.png

Fig. 171 Commit the changes

CLI

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

Listing 250 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]