Overview

The User Management service is concerned with managing user profiles and the resources associated with them, such as devices and delegations. For example, it might be desirable to let users manage their own account via a protected user interface, or for an administrator to be able to manage user accounts, and what permissions they have. As the User Management Service is connected to the Security Token Service, administrators are able to manage the delegations associated with a user profile, including revoking delegations (and consequently, tokens) owned by users.

The User Management Service abstracts the data sources and places a SCIM 2.0 API as the access layer on top. This enables the system to keep the user information in many places and use the Profile Service as an umbrella access layer.

../_images/user-management-overview.png

Fig. 164 User Management with SCIM 2.0 connected to LDAP, SQL, REST and another SCIM service

SCIM 2.0

The User Management Service is based on the SCIM 2.0 protocol which is a RESTful protocol for user and resource management.

Up to three resource types are currently exposed by Curity, depending on how the user management profile has been configured. Every resource is represented with a unique ID, and retrieving a resource is a simple GET operation.

Users

After having configured a user account data source on your user management profile, the /Users endpoint will be made available under your user management endpoint.

Retrieving a user with GET

Listing 229 Getting a user by ID
GET /um/Users/VVNFUjowODM2Mjg5MGE4ZTQ0YTA3YTRlOWIzNjhhYmM5ZGNhYg HTTP/1.1
Host: login.example.com
Authorization: Bearer 21b652ed-5906-451a-a2a2-681bf099dba7
Accept: application/scim+json
Listing 230 Response from SCIM with a single User resource
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "active": true,
    "userName": "teddie",
    "phoneNumbers": [
        {
            "value": "456-555-555",
            "primary": true
        }
    ],
    "emails": [
        {
            "value": "teddie@example.com",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "User",
        "created": "1970-01-01T00:02:03Z",
        "lastModified": "1970-01-01T00:20:34Z",
        "location": "https://login.example.com/um/Users/VVNFUjowODM2Mjg5MGE4ZTQ0YTA3YTRlOWIzNjhhYmM5ZGNhYg"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "name": {
        "familyName": "Bear",
        "givenName": "Ted"
    },
    "id": "VVNFUjowODM2Mjg5MGE4ZTQ0YTA3YTRlOWIzNjhhYmM5ZGNhYg"
}

Searching for a user

Each resource has a server assigned ID. For a user this is not necessarily the same ID as the username. Therefore, it may be required to search for the user instead of performing a GET directly. In SCIM 2.0, a search can be done directly on the Users endpoint as a query, or if sensitive data is sent as search parameters, the query can be posted to the .search endpoint under users.

Example of a search query towards the .search endpoint

Listing 231 Finding a user by username using GET
GET /um/Users?filter=userName+eq+\"teddie\" HTTP/1.1
Host: login.example.com
Accept: application/scim+json
Authorization: Bearer 6e6c3a1b-a12f-4451-b065-2441808c6cec

The same query can be done using a POST

Listing 232 Finding a user by username using POST
POST /um/Users/.search HTTP/1.1
Host: login.example.com
Accept: application/scim+json
Authorization: Bearer ec2979e4-f766-4c79-85f9-58f6c72e224f
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "userName eq \"teddie\""
}

Both queries will render a responds on the form:

Listing 233 Response of a filter request
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 50,

    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "id": "VVNFUjowODM2Mjg5MGE4ZTQ0YTA3YTRlOWIzNjhhYmM5ZGNhYg",
            "userName": "teddie",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "name": {
                "familyName": "Bear",
                "givenName": "Ted"
            },
            "emails": [
                {
                    "value": "teddie@example.com",
                    "primary": true
                }
            ],
            "phoneNumbers": [
                {
                    "value": "456-555-555",
                    "primary": true
                }
            ],
            "active": true,
            "meta": {
                "resourceType": "User",
                "created": "1970-01-01T00:02:03Z",
                "lastModified": "1970-01-01T00:20:34Z",
                "location": "https://login.example.com/um/Users/VVNFUjowODM2Mjg5MGE4ZTQ0YTA3YTRlOWIzNjhhYmM5ZGNhYg"
            }
        }
    ]
}

Searching for users matching criteria

It is also possible to search for users and attributes matching certain criterias.

Listing 234 Finding all active users
POST /um/Users/.search HTTP/1.1
Host: login.example.com
Accept: application/scim+json
Authorization: Bearer ec2979e4-f766-4c79-85f9-58f6c72e224f
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "active eq true",
    "attributes" : ["userName", "emails.value"]
}

The query searched for all active users but added the attributes filter, asking for only userName and emails.value in the response.

Listing 235 Search response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "totalResults": 7,
    "startIndex": 1,
    "itemsPerPage": 50,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "id": "VVNFUjowODM2Mjg5MGE4ZTQ0YTA3YTRlOWIzNjhhYmM5ZGNhYg",
            "userName": "teddie",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "emails": [
                {
                    "value": "teddie@example.com"
                }
            ]
        },
        {
            "id": "VVNFUjozMGZlNDk5NzJmZDg0MDc2YjEzNWUxYjNkNjEzNTI4Ng",
            "userName": "larsdoe",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "emails": [
                {
                    "value": "lars.doe@example.com"
                }
            ]
        },

Creating a user

Passwords

A user resource may contain a password. As shown this can be set when creating a new user, or updated when performing a PATCH on a user resource. However, it is not possible to retrieve a password back once it has been set. This is by design; all password parameters will be excluded in the response even if asked for.

To use passwords for authentication, the .search endpoint can be used with a filter query. When passing in a password to the filter, the server will use the configured credential manager, to validate the password. This means that appropriate hashing will be applied to the password.

It is not possible to perform advanced queries at the same time as the password parameter is presented in the filter statement. The filter is expected to ask for things like userName eq "teddie" and password eq "Password1".

This should be used when the SCIM server is used as backend for other services to authenticate user credentials.

Listing 236 Verifying a password for a user
POST /um/Users/.search HTTP/1.1
Host: login.example.com
Accept: application/scim+json
Authorization: Bearer ec2979e4-f766-4c79-85f9-58f6c72e224f
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "userName eq 'teddie' and password eq 'Password1'",
    "attributes" : ["userName", "emails.value"]
}

Devices

After having configured a device data source on your user management profile, the /Devices endpoint will be made available under your user management endpoint.

Listing devices

Listing 237 Example request to list all devices
GET /um/Devices HTTP/1.1
Host: login.example.com
Authorization: Bearer 21b652ed-5906-451a-a2a2-681bf099dba7
Accept: application/scim+json
Listing 238 Example response listing all devices
{
    "totalResults": 5,
    "startIndex": 1,
    "itemsPerPage": 50,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "id": "REVWSUNFOjE",
            "deviceId": "device1",
            "accountId": "VVNFUjo2RENDOTRDRTQ1NkE3MDEzRTA1MzAyMDAxMkFDNTM0NCAgICA",
            "externalId": "12345",
            "alias": "My tablet",
            "formFactor": "ff1",
            "deviceType": "tab",
            "owner": "VVNFUjpqb2huZG9l",
            "expiresAt": "2022-01-01T00:00:05Z",
            "meta": {
                "resourceType": "Device",
                "created": "1999-11-30T18:22:30Z",
                "lastModified": "1970-01-01T00:00:01Z",
                "location": "https://login.example.com/um/Devices/REVWSUNFOjE"
            },
            "schemas": [
                "urn:se:curity:scim:2.0:Devices"
            ]
        }
    ]

Delegations

After having configured a token data source on your user management profile, the /Delegations endpoint will be made available under your user management endpoint.

Important

If enabled, it is highly recommended to configure the same token data source as the one used by the referenced OAuth profile.

Listing and searching delegations

Depending on the authorization policies configured on the user management endpoint, an access token will either grant admin access or user access, the former listing all issued delegations and the latter those that belong to the subject present in the access token.

Listing 239 Example request to list all delegations
GET /um/Delegations HTTP/1.1
Host: login.example.com
Authorization: Bearer 21b652ed-5906-451a-a2a2-681bf099dba7
Accept: application/scim+json
Listing 240 Example response listing all delegations
{
    "totalResults": 7,
    "startIndex": 1,
    "itemsPerPage": 50,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "sub": "johndoe",
            "clientId": "client-one",
            "active": true,
            "externalId": "15dd2133-44e8-4e2f-a789-5f54d1ea28d9",
            "userName": "johndoe",
            "meta": {
                "resourceType": "Delegation",
                "created": "2018-06-04T11:27:11Z",
                "lastModified": "2018-06-04T11:27:11Z"
            },
            "scope": "openid",
            "schemas": [
                "urn:se:curity:scim:2.0:Delegation"
            ],
            "claims": {
                "subject": {
                    "accountId": "6DCC94CE456A7013E053020012AC5344",
                    "userName": "johndoe",
                    "subject": "johndoe"
                },
                "context": {
                    "auth_time": 1528111631
                }
            },
            "id": "REVMRUdBVElPTjoxNWRkMjEzMy00NGU4LTRlMmYtYTc4OS01ZjU0ZDFlYTI4ZDk",
            "exp": 1528115231,
            "iat": 1528111631,
            "status": "issued"
        }
    ]
}

For searching/filtering specific delegations the SCIM filter parameter may be used.

Listing 241 Example requests with SCIM filters applied
/um/Delegations?filter=status eq "revoked"
/um/Delegations?filter=scope co "openid"
/um/Delegations?filter=not(scope eq "write") and userName sw "my-company"

External ID

externalId maps to the internal delegationId. delegationId is in tokens, so to find out what delegation a token stems from, find the delegationId claim, and use this filter:

Listing 242 Find delegation by delegationId
/um/Delegations?filter=externalId eq "15dd2133-44e8-4e2f-a789-5f54d1ea28d9"

Custom claims

Custom claims that are added to a token will be represented by the customClaims object.

Listing 243 Example response with custom claims
{
    "totalResults": 1,
    "startIndex": 1,
    "itemsPerPage": 50,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "Resources": [
        {
            "sub": "johndoe",
            "clientId": "client-one",
            "active": true,
            "externalId": "15dd2133-44e8-4e2f-a789-5f54d1ea28d9",
            "userName": "johndoe",
            "meta": {
                "resourceType": "Delegation",
                "created": "2018-06-04T11:27:11Z",
                "lastModified": "2018-06-04T11:27:11Z"
            },
            "scope": "openid",
            "schemas": [
                "urn:se:curity:scim:2.0:Delegation"
            ],
            "claims": {
                "subject": {
                    "accountId": "6DCC94CE456A7013E053020012AC5344",
                    "userName": "johndoe",
                    "subject": "johndoe"
                },
                "context": {
                    "auth_time": 1528111631
                }
            },
            "customClaims": {
                "email": "john@doe.com",
                "employeeNumber": 54321
            },
            "id": "REVMRUdBVElPTjoxNWRkMjEzMy00NGU4LTRlMmYtYTc4OS01ZjU0ZDFlYTI4ZDk",
            "exp": 1528115231,
            "iat": 1528111631,
            "status": "issued"
        }
    ]
}

OAuth Protected

The endpoints of the User Management Service are protected with OAuth access tokens. For this purpose the profile is connected to an OAuth profile in the configuration. Each access token is validated against the token-issuers configured for the OAuth profile.

To make a request as shown in the examples above, a valid access token must be presented in the Authorization header.

Important

It is highly recommended to configure a scopes authorization manager when using the SCIM server to limit access to the API to clients with certain scopes enabled.