Managing Users

Prerequisites: To manage users, groups and roles with the APIs, you need:

  • The URL of the HID Authentication Service platform (see HID Authentication Service Platforms around the World)

  • Your tenant ID (the identifier of your tenant, starting with the letter "t", for example, t987198273d986w9869)

  • A bearer token (access token) obtained by authenticating a privileged user (Organization Administrator, Client ID M2M) through an authentication flow. You need an privileged user to have sufficient permissions to perform the actions in the following sections.

    Using a bearer token from an non-privileged user / Client ID will result in 401 / 403 HTTP responses from the HID Authentication Service APIs.

    For further information about tokens, see Enabling User Authentication.

Create an End User

End users should be created in the UG_ROOT group and they do not have any specific role.

An end user can be created in the following ways:

Note: About End-User Logins

When authenticating to your application, an email address is an easy, commonly used way to identify an end user.

However, you are free to use a different piece of data such as your own user identifiers or pseudonyms.

The only constraint is that the HID Authentication Service will enforce the parameter to be unique within your tenant.

For further information, see Internal IDs vs External IDs.

A user can be set up with the following standard attributes:

  • externalId - external ID of the user (mandatory for API versions earlier than 4)

  • userName - user name (mandatory for API version 4 or later)

  • groups (array of objects)

    • value, the group code (UG_ROOT ...)

  • roles (array of objects)

    • value, the role code (RL_ORGADMIN...)

  • urn:hid:scim:api:idp:2.0:UserAuthenticator (array of objects)

    The user's available authenticators

    To know more about authenticators and how to enable authentication on users and Client IDs, see Enabling User Authentication.

  • urn:hid:scim:api:idp:2.0:UserDevice (array of Objects)

    The user's available devices

    To know more about devices and how to set up device based authentication factors, see Managing Devices and Credentials and Enabling User Authentication.

Note:
  • It is not possible to set the internal ID (id)

    The HID Authentication Service will generate it.

  • Even though the groups attribute is an array, only one group is supported per user

Apart from standard attributes, each user can be assigned extra attributes with the parameter urn:hid:scim:api:idp:2.0:UserAttribute. Here is a full list of attributes that can be used:

Attribute Name Description

DOB

Date of Birth

ATR_EMAIL

E-Mail Address

ADDRESS1

Address Line 1

ATR_MOBILE

Mobile Phone Number

ADDRESS2

Address Line 2

LANGUAGE

language

ADDRESS3

Address Line 3

ATT_CNY_ID

Country ID

ADDRESS4

Address Line 4

COUNTY

county

CITY

City

STATE

state

POSTCODE

Post code

PHONE

phone

FIRSTNAME

First Name

CMPNY_NAME

Company Name

LASTNAME

Last Name

TITLE

Title

MIDDLENAME

Middle Name

You can also add your desired attributes using the Custom Attribute Type endpoints.

The below request shows the Custom Attribute Type:

Copy 
POST  https://[base-server-url]/configuration/{tenant}/v2/Users/AttributeType HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
  "id": "TEST10",
  "name": "test 10 name",
  "notes": "test 10 notes"
}

The response contains the newly created Attribute Type:

Copy 
{
  "schemas": [
    "urn:urn:hid:scim:api:idp:2.0:userattribute:Type"
  ],
  "id": "TEST10",
  "meta": {
    "resourceType": "UserAttributeType",
    "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/TEST10",
    "version": 1
  },
  "name": "test 10 name",
  "notes": "test 10 notes"
}

The Custom Attribute Type also supports the following endpoints, see SCIM API Reference:

  • Create User Attribute
  • Retrieve all User Attribute
  • Retrieve a User Attribute
  • Update User Attribute
  • Delete a Known User Attribute
Note:

Upon User creation, the extra attributes FIRSTNAME, LASTNAME, TITLE, ATR_EMAIL and PHONE are copied into the following immutable fields. Those fields are present in the User Detail response when searching or getting the detail of a user.

  • name (object):

    familyName and givenName

  • title (M., Ms., Dr. ...)

  • emails (array of objects):

    value and type (work, personal ...)

  • phoneNumbers (array of objects):

    value

Encrypt User Attribute Type

You can encrypt a UserAttributeType (for example, TITLE or FIRSTNAME) to minimize the exposure of Personally Identifiable Information (PII).

The value of the encrypted parameter must be in Boolean - true or false.

Copy

Sample request to update a user attribute type

PUT /User/AttributeType/CITY
{
    "encrypted": true
}
Copy

Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
   "id": "CITY",
   "meta":    {
      "resourceType": "UserAttributeType",
      "location": "https://[base-server-url]/configuration/{tenant}/v2/User/AttributeType/CITY",
      "version": "1"
   },
   "name": "City",
   "encrypted": true
}

Switch Encryption of User Attribute Type

If necessary, you can change the non-encrypted user attribute type to encrypted and vice versa. Use value "true" for encrypting and "false" for non-encrypting.

Important: You cannot use an encrypted user attribute as a criterion for search user (for example, if attribute type FIRSTNAME is encrypted, a search user with criteria name.givenName = foo will return 0 result even if a user has this givenName).

Once the end user is created, you need to assign an authenticator to them in order to allow them to authenticate with the HID Authentication Service. To know how to assign an authenticator, see Enabling User Authentication.

Create a Single User

To create a single user, you can use Create User endpoint.

The request to create a single user is shown below:

Copy 
POST  https://[base-server-url]/scim/{tenant}/v2/Users HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:hid:scim:api:idp:2.0:Attribute",
      "urn:hid:scim:api:idp:2.0:UserDevice"   ],
   "externalId":"rdavis@company.com",
   "userName":"rdavis",
   "name":{
      "familyName":"Davis",
      "givenName":"Richard"   },
   "emails":[
      {
         "value":"rdavis@company.com",
         "type":"work"      }
   ],
   "groups":[
      {
         "value":"UG_ROOT"      }
   ],
   "urn:hid:scim:api:idp:2.0:UserAttribute":{
      "attributes":[
         {
            "name":"TITLE",
            "type":"string",
            "value":"M."         },
         {
            "name":"ATR_MOBILE",
            "type":"string",
            "value":"0044 567 456 387"         }
      ]
   },
   "meta":{
      "resourceType":"User"   }
}
Note: The userName parameter is mandatory for API version 4 or later.
Copy

The response contains the internal ID of the newly created end user:

{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:hid:scim:api:idp:2.0:UserDevice",
      "urn:hid:scim:api:idp:2.0:UserAttribute",
      "urn:hid:scim:api:idp:2.0:UserAuthenticator"   ],
   "id":"49976",
   "externalId":"rdavis@company.com",
   "userName":"rdavis", 
    <truncated output>
}

Create Multiple Users

To create multiple users, you can use the Bulk Import endpoint.

Important:
  • Maximum allowable payload size to create multiple user is 40 MB.
  • It is not possible to re-submit an import batch with new or updated information. Make sure you set all the information you want for your users. If you missed out any information, the only solution is to call updateUser on each user you wish to modify.

The request to create multiple users is shown below, user information must be in JSON format:

Copy 
POST  https://[base-server-url]/scim/{tenant}/v2/Users/.import HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
{
    "users": [{
            "emails": [{
                    "value": "email100000@company.com"
                }
            ],
            "name": {
                "familyName": "last100000",
                "givenName": "first100000"
            },
            "externalId": "email100000@company.com",
            "userName": "bb0_100000"
        }, {
            "emails": [{
                    "value": "email100001@company.com"
                }
            ],
            "name": {
                "familyName": "last100001",
                "givenName": "first100001"
            },
            "externalId": "email100001@company.com",
            "userName": "bb0_100001"
        }
    ],
    "group": {
        "value": "UG_ROOT"
    }
}
Note: The userName parameter is mandatory for API version 4 or later.
Copy

The response contains newly created users and CorrelationId:

{
    "schemas": ["urn:hid:scim:api:idp:2.0:user:ImportResponse"],
    "meta": {
        "resourceType": "UserImportResponse",
        "location": "https://[base-server-url]/scim/{tenant}/v2/Users/.import/1P5FOESDK44J6Q0QAHK2",
        "version": "1"
    },
    "correlationId": "1P5FOESDK44J6Q0QAHK2"
}
Important:
  • A correlationId is returned for each successful batch submission. It can be used in the Get Import Status endpoint or to look for events in the auditlog.
  • If an authenticator policy of type login is specified in authenticatorPolicy.value, it will create an authenticator with a random password for all users in the bulk import. This random password must be changed during first login. To change password, see SCIM API Reference.

Get Import Status

To know the status of an import, you can use the Get Import Status endpoint along with the CorrelationId ({uid}) (see Managing the Correlation ID).

The request to retrieve the status of import is shown below:

Copy 
GET https://[base-server-url]/scim/{tenant}/v2/Users/.import/{uid} HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"

The response may contains the below information:

  • importSize - the number of users in the import request

  • status - "importing" or "done"

  • nbProcessed - the number of users that has been processed so far

  • nbFailed - the number of users that have not been imported because of a failure

  • nbAlreadyExisted - the number of users that have not been imported because they already exist

  • nbImported - the number of users that were successfully imported

Copy 
{
   "schemas": ["urn:hid:scim:api:idp:2.0:user:ImportResponse"],
   "correlationId": "1P5FOESDK44J6Q0QAHK2",
   "status": "done",
   "importSize": 500,
   "nbFailed": 0,
   "nbAlreadyExisted": 20,
   "nbImported": 480
}
Note: In case, if you are encountering any of the below scenario, note the following:
  • If status is importing and nbProcessed is 0:
    • If you submitted only one request, just wait a few seconds for the request to be processed.
    • If you submitted multiple import requests, they have been put in aqueue. Import requests are processed one after the other So just wait for your request to start.
  • If status is importing and nbProcessed is stuck at a number (0 or other):
    • The server may have rebooted and the request has been lost. Submit your import request again.

List All End Users

In order to list all End users, simply carry out a search on the UG_ROOT group:

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"groups eq \"UG_ROOT\""}
Copy

The response is an array of user entries: 

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 28,
   "resources": [
      {
         "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:hid:scim:api:idp:2.0:UserDevice",
            "urn:hid:scim:api:idp:2.0:UserAttribute",
            "urn:hid:scim:api:idp:2.0:UserAuthenticator"         ],
         "id": "23864",
         "externalId": "jsmith@company.com",
         "userName": "jsmith",
         
        <trunctated output>
      },
      {
         "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:hid:scim:api:idp:2.0:UserDevice",
            "urn:hid:scim:api:idp:2.0:UserAttribute",
            "urn:hid:scim:api:idp:2.0:UserAuthenticator"         ],
         "id": "23884",
         "externalId": "rdavis@company.com",
         "userName": "rdavis",
         
        <trunctated output>
      },

    <trunctated output>    
    ]}
}

Search for End Users

To search an end users, simply use the same technique as described above, but add filters by using the AND operator. Do not omit the filter on the group, or you may fetch as well client IDs or Organization Administrators.

Examples of filters:

  • Find all end users whose externalId contains "smith":

    groups eq \"UG_ROOT\" and externalId co \"smith\"

  • Find all end users whose familyName starts with "dav":

    groups eq \"UG_ROOT\" and name.familyName sw \"dav\"

  • Find all end users that have a company email address (that ends with "company.com"):

    groups eq \"UG_ROOT\" and emails ew \"company.com\"

  • Find all end users that have at least a phone number defined ("pr" operator stands for "presence"):

    groups eq \"UG_ROOT\" and phoneNumbers pr

  • Find the end users defined with a certain mobile phone (the HID Authentication Service does not enforce any unique constraint on the mobile phone attribute).

    We are using the user attributes here. The HID Authentication Service allows only one attribute per filter, as the "or" operator is not supported:

    groups eq \"UG_ROOT\" and urn:hid:scim:api:idp:2.0:UserAttribute:attributes.name eq ATR_MOBILE and urn:hid:scim:api:idp:2.0:UserAttribute:attributes.value eq \"2312312321\"

  • Find the end users that are assigned a certain role: 

    groups eq \"UG_ROOT\" and role eq \"myCustomRole\"

For further information, see Searching with the SCIM API.

Update an End User

Important:

The HID Authentication Service SCIM API is designed with a replacement approach when it comes to updates.

This means that omitting an attribute that was set on the user on an update request will simply remove/empty this attribute.

The recommended process to update a user is to first fetch the details of this user, and then modify the returned JSON.

First, you need to get the details of the end user, either with the internal ID or the externalId.

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"externalId eq \"bdavis@company.com\""}
Copy

The response is a detailed view of the user: 

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 1,
   "resources": [   {
      "schemas":       [
         "urn:ietf:params:scim:schemas:core:2.0:User",
         "urn:hid:scim:api:idp:2.0:UserDevice",
         "urn:hid:scim:api:idp:2.0:UserAttribute",
         "urn:hid:scim:api:idp:2.0:UserAuthenticator"      ],
      "id": "49796",
      "externalId": "bdavis@company.com",
      "meta":       {
         "resourceType": "User",
         "created": "2019-09-06T00:00:00Z",
         "location": "https://[base-server-url]/scim/{tenant}/v2/Users/49796",
         "version": "1"      },
      "userName": "bdavis",
      "name":       {
         "familyName": "Davis",
         "givenName": "Brian"      },
      "displayName": "Brian Davis",
      "title": "M.",
      "active": true,
      "emails": [{"value": "bdavis@company.com"}],
      "phoneNumbers": [{"value": "567 890 654"}],
      "groups": [      {
         "type": "Group",
         "display": "ROOT",
         "value": "UG_ROOT",
         "$ref": "https://[base-server-url]/scim/{tenant}/v2/Groups/UG_ROOT"      }],
      "roles": [],
      "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes":       [
                  {
            "name": "ATR_EMAIL",
            "type": "string",
            "value": "bdavis@company.com",
            "readOnly": false
         },
                  {
            "name": "LASTNAME",
            "type": "string",
            "value": "Davis",
            "readOnly": false
         },
                  {
            "name": "FIRSTNAME",
            "type": "string",
            "value": "Brian",
            "readOnly": false
         },
                  {
            "name": "TITLE",
            "type": "string",
            "value": "M.",
            "readOnly": false
         },
                  {
            "name": "ATR_MOBILE",
            "type": "string",
            "value": "567 890 654",
            "readOnly": false
         }
      ]},
      "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": []},
      "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": []}
   }]
}

Reuse the JSON-based response by updating the required attributes with a PUT request. The internal ID is used as a path parameter of the query.

Note:

  • The externalId cannot be updated and it is recommended that you avoid changing the emails if you use it as an externalId

    Instead, delete the user and create another one with the correct email / external ID

  • The following fields are immutable and, to change their value, update the corresponding extra attributes with urn:hid:scim:api:idp:2.0:UserAttribute:

    • name (object):

      • familyName and givenName

    • title - the title (M., Ms., Dr. ...)

    • emails (array of objects):

      • value and type (work, personal ...)

    • phoneNumbers (array of objects):

      • value

  • Devices and authenticators can also be updated (see Enabling User Authentication)

In the following example, the email address, the family and first names, the title, the phone number are changed, as well as elevating the user to the role of Organization Administrator (by changing the group and assigning a role).

Copy 
PUT https://[base-server-url]/scim/{tenant}/v2/Users/49796 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:hid:scim:api:idp:2.0:UserDevice",
      "urn:hid:scim:api:idp:2.0:UserAttribute",
      "urn:hid:scim:api:idp:2.0:UserAuthenticator"   ],
   "id":"49796",
   "externalId":"bdavis@company.com",
   "meta":{
      "resourceType":"User",
      "created":"2019-09-06T00:00:00Z",
      "location":"https://[base-server-url]/scim/{tenant}/v2/Users/49796",
      "version":"1"   },
   "userName":"bdavis",
   "name":{
      "familyName":"Davis",
      "givenName":"Brian"   },
   "displayName":"Brian Davis",
   "title":"M.",
   "active":true,
   "emails":[
      {
         "value":"bdavis@company.com"      }
   ],
   "phoneNumbers":[
      {
         "value":"567 890 654"      }
   ],
   "groups":[
      {
         "value":"UG_ORGADMIN"      }
   ],
   "roles":[
      {
         "value":"RL_ORGADMIN"      }
   ],
   "urn:hid:scim:api:idp:2.0:UserAttribute":{
      "attributes":[
         {
            "name":"ATR_EMAIL",
            "type":"string",
            "value":"bdavis-second@company.com",
            "readOnly":false
         },
         {
            "name":"LASTNAME",
            "type":"string",
            "value":"Davis Stephan",
            "readOnly":false
         },
         {
            "name":"FIRSTNAME",
            "type":"string",
            "value":"Brian John",
            "readOnly":false
         },
         {
            "name":"TITLE",
            "type":"string",
            "value":"Mr",
            "readOnly":false
         },
         {
            "name":"ATR_MOBILE",
            "type":"string",
            "value":"897 678 456",
            "readOnly":false
         }
      ]
   },
   "urn:hid:scim:api:idp:2.0:UserAuthenticator":{
      "authenticators":[
      ]
   },
   "urn:hid:scim:api:idp:2.0:UserDevice":{
      "devices":[
      ]
   }
}

Delete an End User

Important: Do not use this method to delete Client IDs!

You will delete the user but would leave an orphan Client ID "configuration" in the background. This orphan configuration might prevent you from re-creating a Client ID with the same externalId.

For further information, see Delete a Client ID.

First, search for the user to get their internal ID:

Copy 
POST https://[base-server-url]/scim/{tenant}/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"externalId eq \"bdavis@company.com\""}

The response contains the internal ID (in this example, 49796):

Copy 
{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 1,
   "resources": [   {
      "schemas":       [
         "urn:ietf:params:scim:schemas:core:2.0:User",
         "urn:hid:scim:api:idp:2.0:UserDevice",
         "urn:hid:scim:api:idp:2.0:UserAttribute",
         "urn:hid:scim:api:idp:2.0:UserAuthenticator"      ],
      "id": "49796",
      "externalId": "bdavis@company.com",
      <trunctated output>
}

Use this internal ID as a path parameter of a DELETE request.

Copy 
DELETE https://[base-server-url]/scim/{tenant}/v2/Users/49796 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN

See also:

Managing User or Client ID Authenticators

Enabling User Authentication