Users REST API

The Users endpoint allows creating, browsing, importing and managing users. A user can be any individual or system that accesses one or more resources protected by ActivID Appliance.

The user of an organization can be end users, staff, web applications, or back-end services etc.,

All the mobile user management request/response formats follow the SCIM V2 schema specification (see Getting Started with the ActivID Appliance SCIM API).

Note: The API version supported by ActivID Appliance 8.7 is 3.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality.

Supported User attributes:

Attribute Comments

username

readOnly

externalid

Mandatory, must be set at CREATE, can be modified with PUT/PATCH

name.familyName

readWrite

name.givenName

readWrite

displayName

readOnly

title

readWrite

userType

readOnly

active

readWrite

emails

readWrite (max supported: 1)

emails.value

readWrite

phoneNumbers

readWrite (max supported: 1)

phoneNumbers.value

readWrite

addresses

readWrite (max supported: 4)

addresses.formatted

readWrite

groups

readWrite (only 1 supported)

groups.display

readOnly

groups.ref

readOnly

groups.value

readWrite

roles

readWrite

Important:  
  • userName must be used to log on to a portal or via OpenID
  • To include the device's friendlyName in the urn:hid:scim:api:idp:2.0:UserDevice extension, set the query parameter api-version=2 or later

  • For further information, see Get a User.

Method Details

HTTPS Method Entity Action Request URI Description

GET

Read

/scim/{tenant}/v2/Users

Get all users filtered by attributes

GET

Read

/scim/{tenant}/v2/Users/{id}:(String)

Get a known user

GET

Import

/scim/{tenant}/v2/Users/.import/{uid}

Get the status of a bulk import request

POST

Create

/scim/{tenant}/v2/Users/

Create new user

POST

Search

/scim/{tenant}/v2/Users/.search

Search for users

POST

Forget

/scim/{tenant}/v2/Users/.forget

Forget user

POST

Import

/scim/{tenant}/v2/Users/.import

Import a batch of users

PUT

Replace

/scim/{tenant}/v2/Users/{id}:(String)

Fully replace a known user

DELETE

Delete

/scim/{tenant}/v2/Users/{id}:(String)

Delete a known user

Required Permissions

Function Required Permissions

GET

  • Read user details

  • Read reference data

  • Search devices

CREATE

  • Read reference data

  • Create user

  • Modify user roles

  • Read user details

  • Search devices

REPLACE

  • Read reference data

  • Read user details

  • Update user external reference id

  • Update user attributes

  • Search devices

  • Assign device

  • Unassign device

  • Assign and unassign device

  • Modify user roles

  • Move user

DELETE

  • Read user details

  • Delete user

SEARCH

  • Search users

  • Read reference data

  • Read user details

  • Search devices

FORGET

  • Forget User

IMPORT

  • To import a batch of users:

    • Create User

  • Read reference data

  • To get the status of an import:

    • Read Audit

Create a User

Accept: application/scim+json

Schema extensions:

JSON Payload Data Type Value

schemas

Schema[]

Mandatory. Lists the supported schemas

externalId

String

Required. This is provided by Service Consumer

name (givenName + familyName)

Name[]

Required. Name of the user to be enrolled

emails (value)

String

Required. Email address of the user to be enrolled

urn:hid:scim:api:idp:UserDevice

UserDevice[]

Devices to bind to the newly created user

urn:hid:scim:api:idp:UserAttribute

Attribute[]

Additional attributes to add to user

urn:hid:scim:api:idp:2.0:UserAuthenticator

UserAuthenticator[]

Authenticators to assign to the newly created user

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

String

The name of the company

roles

String

Assign roles to the user (roles must be known to the server/service)

groups

MemberRef[]

The group membership

*

String

Any other supported attribute

id

Number

This identifier is provided by HID Global and MUST be unique across the Service Provider's entire set of Resources

Meta.created

Meta

Created Date in UTC in format ISO8601

Copy

Sample Request URI

[POST] {tenant}/v2/Users 
Note: This example uses the UserAttribute section with DOB (Date Of Birth) attribute. Make sure this attribute is allowed for the specified user group. For further information about mapping attributes, see Configure User Attributes.
Copy

Sample Request

{
    "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": "jdoe",
    "name": {
        "familyName": "Doe",
        "givenName": "John"
    },
    "emails": [{
        "value": "jdoe@company.com",
        "type": "work"
        }
    ],
    "groups": [{
        "value": "USG_CUST2"
        }
    ],
    "urn:hid:scim:api:idp:2.0:UserAttribute": {
        "attributes": [{
            "name": "DOB",
            "value": "1980-08-01"
            }
        ]
    }
}
Copy

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json+scim
Location: https://[base-server-url]/SCIM/tenant/v2/User/90001
 
{
    "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": "11288",
    "externalId": "jdoe",
    "meta":    {
        "resourceType": "User",
        "created": "2017-11-20T14:59:09Z",
        "location": "https://[base-server-url]/scim/tenant/v2/Users/11288",
        "version": "1"
    },
    "userName": "jdoe",
    "name":    {
        "familyName": "Doe",
        "givenName": "John"
    },
    "displayName": "John Doe",
    "userType": "FTRESS",
    "active": true,
    "emails": [{"value": "jdoe@company.com"}],
     "groups": [{
        "type": "Group",
        "display": "Business Online Banking",
        "value": "USG_CUST2",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/USG_CUST2"
    }],
    "roles": [],
    "urn:hid:scim:api:idp:2.0:UserAttribute": {
        "attributes": [
            {
                "name": "ATR_EMAIL",
                "type": "string",
                "value": "jdoe@company.com",
                "readOnly": false
            },
            {    
                "name": "LASTNAME",
                "type": "string",
                "value": "Doe",
                "readOnly": false
            },
            {
                "name": "DOB",
                "type": "string",
                "value": "1980-08-01",
                "readOnly": false
            },
            {
                "name": "FIRSTNAME",
                "type": "string",
                "value": "John",
                "readOnly": false
            }
        ]},
    "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": []},
    "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": []}
}

Get a User

Accept: application/scim+json

Schema extensions:

Path Parameter Type Value

id

String

Required. This identifier is provided by HID Global and MUST be unique across the Service Provider's entire set of Resources

JSON Response Data Type Value

User

urn:ietf:params:scim:schemas:core:2.0:User

The SCIM v2 Core User representation

User attributes

urn:hid:scim:api:idp:2.0:UserAttribute

The list of user attributes

User devices

urn:hid:scim:api:idp:2.0:UserDevice

The list of devices bound to the user

User authenticators

urn:hid:scim:api:idp:2.0:UserAuthenticator

The list of user authentication records

Copy

Sample Request URI

[GET] /scim/{tenant}/v2/Users
Or
[GET] /scim/{tenant}/v2/Users/{id}
Note:  
  • To include the device's friendlyName in the urn:hid:scim:api:idp:2.0:UserDevice extension, set the query parameter api-version=2 or later

Payload: N/A

Copy

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json+scim, 
Location: https://[base-server-url]/SCIM/tenant/v2/User/11058
 
{
   "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": "11058",
   "externalId": "jdoe",
   "meta":    {
      "resourceType": "User",
      "created": "2018-12-05T23:00:00Z",
      "location": "https://[base-server-url]/scim/tenant/v2/Users/11058",
      "version": "1"
   },
   "userName": "jdoe",
   "name":    {
      "familyName": "Doe",
      "givenName": "John"
   },
   "displayName": "John Doe",
   "userType": "FTRESS",
   "active": true,
   "groups": [   {
      "type": "Group",
      "display": "Full Time Employees",
      "value": "USG_FTEMP",
      "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/USG_FTEMP"
   }],
   "roles": [],
   "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes":    [
            {
         "name": "LASTNAME",
         "type": "string",
         "value": "Doe",
         "readOnly": false
      },
            {
         "name": "FIRSTNAME",
         "type": "string",
         "value": "John",
         "readOnly": false
      }
   ]},
   "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": [   {
      "display": "AT_EMPSMS",
      "value": "11058.AT_EMPSMS",
      "$ref": "https://[base-server-url]/scim/tenant/v2/Authenticator/11058.AT_EMPSMS"
   }]},
   "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": [   {
      "display": "11059",
      "value": "11059",
      "friendlyName": "my OOB device",
      "$ref": "https://[base-server-url]/scim/tenant/v2/Device/11059"
   }]}
}

Replace a User

Accept: application/scim+json

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.
Path Parameter Data Type Description

id

String

Required. This identifier is provided by HID Global and MUST be unique across the Service Provider's entire set of Resources

JSON Payload Data Type Value

User

urn:ietf:params:scim:schemas:core:2.0:User

The SCIM v2 Core User representation

User attributes

urn:hid:scim:api:idp:2.0:UserAttribute

The list of user attributes

User authenticator

urn:hid:scim:api:idp:2.0:UserAuthenticator

The list of user authentication records

User device

urn:hid:scim:api:idp:2.0:UserDevice

The list of devices bound to the user

Note:  
  • If any of the extensions are removed from the PUT, then that section will not be updated.
  • If an element is removed from an extension, it will be deleted.
  • Group section is mandatory.
Copy

Sample Request URI

[PUT] /scim/{tenant}/v2/Users/11288
Copy

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json+scim, 
Location: https://[base-server-url]/SCIM/tenant/v2/User/11288
 
{
    "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": "11288",
    "externalId": "jdoe",
    "meta":    {
        "resourceType": "User",
        "created": "2017-11-19T23:00:00Z",
        "location": "https://[base-server-url]/scim/tenant/v2/Users/11288",
        "version": "1"
    },
    "userName": "jdoe",
    "userType": "FTRESS",
    "active": true,
    "groups":    [{
        "type": "Group",
        "display": "Business Online Banking",
        "value": "USG_CUST2",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/USG_CUST2"
    }],
    "roles": [],
    "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes":    [{
        "name": "DOB",
        "type": "string",
        "value": "1980-08-01",
        "readOnly": false
    }]},
    "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators":    [{
        "display": "AT_CUSTSMS",
        "value": "11288.AT_CUSTSMS",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Authenticator/11288.AT_CUSTSMS"
    }]},
    "urn:hid:scim:api:idp:2.0:UserDevice": {"devices":    [{
        "display": "11289",
        "value": "11289",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Device/11289"
    }]}
}
Note: The whole object is always returned.

Search for Users

The supported search criteria that can be used as filters are:

SCIM Attribute Operators supported

username

eq, co, ew, sw, pr

externalid

eq, co, ew, sw, pr

displayname

eq, co, ew, sw, pr

groups.value

eq

role

eq, co, ew, sw, pr

userType

eq

userRepositoryId

eq

Other supported attributes

eq

Sample Request URI

[POST] /scim/{tenant}/v2/Users/.search
Or
[GET] /scim/{tenant}/v2/Users/.search?filter=displayName sw smith 
Or
[GET] /scim/{tenant}/v2/Users?filter=displayName sw smith
Copy

Sample Request (with no attributes defined)

POST https://[base-server-url]/SCIM/tenant/v2/Users/.search
{     
    schemas: ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    filter: "displayName sw \"smith\"",
    sortBy: "id";
    sortOrder: "descending"
    startIndex: 1,
    count: 100
}
Copy

Sample Request (with attributes to define the response)

POST https://[base-server-url]/SCIM/tenant/v2/Users/.search
{     
   schemas: ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
   attributes: ["displayName", "userName", "meta"],
   filter: "displayName sw \"smith\"",
   sortBy: "id";
   sortOrder: "descending"
   startIndex: 0,
   count: 100
}

Where:

  • The filter attribute can be used to reduce the number of records you want to see.

    You can use the and operator between filters and use parentheses between conditions:

    "filter": "username eq f* and externalid sw 1*"

    A single criterion on UserAttribute extension is supported. For example:

    filter:"urn:hid:scim:api:idp:2.0:UserAttribute:attributes.name eq FIRSTNAME and urn:hid:scim:api:idp:2.0:UserAttribute:attributes.value eq John"

  • The following attributes can be used for a paginated search:

    • count can be used to limit the size of the search results

    • startIndex specifies the index of the first result returned (where 0 will returned the same paginated result as 1)

    The result will contain a totalResults attribute to allow you to compute the number of pages.

    Note:

    The maximum number of rows returned per request is 100, even if you specify a higher count value. Therefore, for lists that are longer than 100 elements, it is mandatory for you to paginate the results.

  • Note:  Sorting the User search results is available with API version 7 (or later).

    For further information, see Searching with the SCIM API.

  • Unsupported input:

    • sortBy

    • sortOrder

Copy

Sample Response (with only id and meta returned)

HTTP/1.1 200 OK
Content-Type: application/json+scim
 
{
    schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    totalResults: 1,
    itemsPerPage: 10,
    startIndex: 1,
    resources: [
        {
            "id":"123"
            "meta":{
                "location":
                "https://[base-server-url]/SCIM/tenant/v2/Users/12345",
                "resourceType":"User",
                "lastModified": ...
            }
        }
    ]
}
Copy

Sample Response (defined with attributes)

HTTP/1.1 200 OK
Content-Type: application/json+scim 
 
{
    schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    totalResults: 1,
    itemsPerPage: 10,
    startIndex: 1,
    resources: [
        {
            "id":"123"
            "userName":"johnsmith@acme",
            "displayName":"John Smith"
            "meta":{
                "location":
                "https://[base-server-url]/SCIM/tenant/v2/Users/12345",
                "resourceType":"User",
                "lastModified": ...
            }
        }
    ]
}

By default, the user search request returns the users’ roles, authenticators and devices. If you do not need this information in the response, you can exclude them by using the excludedAttributes parameter in the request. This will improve the performance of the user search request. For example:

Copy

Sample request to exclude attributes

{
    "filter" : "groups.value eq USG_FTEMP",
    "excludedAttributes": [
        "roles", 
        "urn:hid:scim:api:idp:2.0:UserAuthenticator", 
        "urn:hid:scim:api:idp:2.0:UserDevice"
    ]
}

Delete a User

All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:

Copy

Delete entity

DELETE https://[base-server-url]/scim/{tenant}/v2/ENTITY_TYPE/{id}

Accept: application/scim+json

Copy

Sample Response

HTTP/1.1 204 No content

Forget a User

Accept: application/scim+json

The Forget functionality can be used to remove all anonymization tokens for a user in the Audit log.

Only externalId can be used in the request to forget a user. If other user parameters are present, they will not be used.

Note:  
  • You must delete the user before calling forgetUser.

  • You must be assigned the "Forget User" permission to perform this action.

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Users/.forget
Copy

Sample Request

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "externalId": "myuser"
}
Copy

Sample Response

HTTP/1.1 200 OK

Import Users

The Import function allows importing a batch of users (the batch is an array of the users). For further information, see the User schema.

The parameters are:

  • users – array of users (mandatory)

  • group – group in which users will be created (mandatory)

  • authenticatorPolicy – a "login" Authenticator of the specified policy will be created for each user (optional)

If a "login" type authenticator policy is specified in authenticatorPolicy.value, it will create an authenticator with a random password for all users in the bulk import.

The authenticator will not be disabled nor expired so that it can be reset with the "Forgotten Password" feature.

A correlationId is returned for each successful batch submission.

It can also be used in the Get Import Status endpoint or to look for events in the audit log.

Note:  
  • The function only takes the "base" user schema (that is, without the group, role, authenticator and devices extensions).

  • The group must be set in the group.value property outside the array of users.

  • Make sure you set all the information you want to include for your users. If details are missing, you will need to call replaceUser for each user that you need to modify. It is not possible to re-submit an import batch with new or updated information.

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Users/.import
Copy

Sample Request

{
    "users": [
        {
            "emails": [{
                "value": "email100000@company.com"
            }],
            "name": {
                "familyName": "last100000",
                "givenName": "first100000"
            },
            "externalId": "bb0_100000",
        }, 
        {
            "emails": [{
                "value": "email100001@company.com"
            }],
            "name": {
                "familyName": "last100001",
                "givenName": "first100001"
            },
            "externalId": "bb0_100001"
        }],
    "group": {
        value": "USG_FTEMP"
    }
}
Copy

Sample Response

{
    "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"
}

Get Import Status

This endpoint is used to get the status of a device import request. It will return the following information:

  • importSize – the number of users in the import request

  • status – "importing", "done" or "failed"

  • 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

Note:
  • If the status is importing and nbProcessed is 0:

    • If you submitted only one request, just wait a few seconds ; the worker verifies every 10 seconds if there is a new job to process.

    • If you submitted multiple import requests, they have been put in a FIFO queue. Import requests are processed one after the other. So just wait for your request to start.
  • If the status is importing and nbProcessed remains at a number (0 or other), the server might have rebooted and the request has been lost. Submit your import request again.

  • You can also monitor the audit log to verify if "createUser" events are being audited.

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Users/.import/{uid}

Where {uid} is the correlationId

Copy

Sample Request

GET /scim/{tenant}/v2/Users/.import/1P5FOESDK44J6Q0QAHK2
Copy

Sample response where the import request is still in progress

{
   "schemas": ["urn:hid:scim:api:idp:2.0:user:ImportResponse"],
   "correlationId": "1P5FOESDK44J6Q0QAHK2",
   "status": "importing",
   "importSize": 500,
   "nbProcessed": 82
}
Copy

Sample response where the import has finished

{
   "schemas": ["urn:hid:scim:api:idp:2.0:user:ImportResponse"],
   "correlationId": "1P5FOESDK44J6Q0QAHK2",
   "status": "done",
   "importSize": 500,
   "nbFailed": 0,
   "nbAlreadyExisted": 20,
   "nbImported": 480
}

Manage Users in a SCIM Federated Repository

Microsoft Azure calls the standard Users endpoints to manage users.

Prerequisites: The provisioning agent must have the:
  • Required permissions to manage users.

  • ActivID Appliance Security Groups Functions permission set.

For further information about provisioning, go to https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/use-scim-to-provision-users-and-groups#understand-the-aad-scim-implementation

Create Users

Copy

Sample request for user creation, set userType to SCIM_FED

POST https://[base-server-url]/scim/{tenant}/v2/Users
{
    "userType": "SCIM_FED",
    "active": true,
    "externalId": "toto1000",
    "name": {
        "familyName": "smith",
        "givenName": "john"
    },
    "phoneNumbers": [{
        "type": "work",
        "value": "0123456789"
    }],
    "addresses": [{
        "type": "work",
        "formatted": "5555555555"
    }]
}

Patch Users

Copy

Sample request

PATCH https://[base-server-url]/scim/{tenant}/v2/Users/10222
{
    "Operations": [{
        "op": "Replace",
        "path": "active",
        "value": "true"
    }]
}
Note: Only PATCH /Users can be used to update SCIM_FED users.

Delete Users

When you delete a user in Microsoft Azure, the user is only soft-deleted and their active status is set to false by calling PATCH /Users/{uid} (which is the equivalent of ‘disabled’ in ActivID Appliance).

After 30 days, the user is deleted permanently, and Microsoft Azure will call DELETE /Users/{uid} (which is the equivalent of deleting the user in ActivID Appliance).

If you want to skip the 30 days wait before users are deleted permanently:

  1. Log on to the Microsoft Azure AD portal (https://aad.portal.azure.com/) and go to the Users page and then Deleted users.

    Graphical user interface, application, Teams

Description automatically generated

  2. Select the required user(s) and click Delete permanently.

You can also disable authentication for a user by blocking sign in:

  1. Go to the user’s profile in Microsoft Azure.

    Graphical user interface, text, application, email

Description automatically generated

  2. Under Settings, set Block sign in to Yes.

Microsoft Azure will call PATCH /Users and set the user’s active status to false (which is the equivalent of ‘disabled’ in ActivID Appliance).