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 HID Authentication Service.

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 About the HID Authentication Service SCIM API).

Note: The API version supported by HID Authentication Service is 10.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. For details of the version updates, see SCIM API Revision History.

Supported User attributes:

Attribute	Comments
username	Mandatory, set with the UPN
externalid	Set with the UUID of the users in the directory using the EXTERNALID attribute
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
To include the device's lastSuccessfulDate and lastSuccessfulAuthPolicy , add the urn:hid:scim:api:idp:2.0:UserDevice extension and api-version=7 (or later) to the query parameter

For further information, see Get a User.

To include an array of multiple values for custom user attributes in the urn:hid:scim:api:idp:2.0:UserAttribute extension, set the query parameter api-version=9 or later
The multiValued property for the user attribute type must also be set to true.

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:

urn:hid:scim:api:idp:2.0:UserAttribute [optional]
urn:hid:scim:api:idp:2.0:UserDevice [optional]
urn:hid:scim:api:idp:2.0:UserAuthenticator [optional]
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User [optional]

Data returned for API versions earlier than 7

Default properties	Attributes if specified in the query
Schema and meta data All user properties	id Properties from "attributes"

Note: You can use exludedAttributes to exclude properties that are not required.

Data returned for API version 7 and later

Default properties	Attributes if specified in the query
Schema and meta data All standard user properties: id userName name object (givenName...) displayName title active emails phonenumbers addresses groups	All standard user properties (plus schema and meta data) Properties from "attributes": urn:hid:scim:api:idp:2.0:UserAttribute roles urn:hid:scim:api:idp:2.0:UserDevice urn:hid:scim:api:idp:2.0:UserAuthenticator SecurityGroups (that is, federated groups)

Note: exludedAttributes has no effect when searching for users.

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.

Copy

Sample Request

POST /scim/{tenant}/v2/Users?api-version=9
Content-Type: application/scim+json
Authorization: Bearer RT04IQAAAYciLb1XyKOCd1UiBQQHwGzc0SVDs2io
{
    "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": "john502ExtID",
    "userName" : "john502",
    "name":
        { "familyName": "John", "givenName": "Doe" },
    "emails": [
        { "value": johnDoe@company.com, "type": "work" }
    ],
    "groups": [
        { "value": "UG_ROOT" }
    ]
}

Copy

Sample Response

HTTP/1.1 201 Created
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "46052",
    "externalId": "john502ExtID",
    "meta": {
        "resourceType": "User",
        "created": "2023-03-27T08:41:45Z",
        "location": https://[base-server-url]/scim/tenant/v2/Users/46052,
        "version": "1"
    },
    "userName": "john502",
    "name": {
        "familyName": "John",
        "givenName": "Doe"
    },
    "displayName": "Doe John",
    "userType": "FTRESS",
    "active": true,
    "emails": [{"value": johnDoe@company.com}],
    "groups": [ {
        "type": "Group",
        "display": "ROOT",
        "value": "UG_ROOT",
        "$ref": https://[base-server-url]/scim/tenant/v2/Groups/UG_ROOT
    }]
}

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

Data returned for API versions earlier than 7

Default properties	Attributes if specified in the query
Schema and meta data All user properties	id Properties from "attributes"

Note: You can use exludedAttributes to exclude properties that are not required.

Data returned for API version 7 and later

Default properties	Attributes if specified in the query
Schema and meta data All standard user properties: id userName name object (givenName...) displayName title active emails phonenumbers addresses groups	All standard user properties (plus schema and meta data) Properties from "attributes": urn:hid:scim:api:idp:2.0:UserAttribute roles urn:hid:scim:api:idp:2.0:UserDevice urn:hid:scim:api:idp:2.0:UserAuthenticator SecurityGroups (that is, federated groups)

Note: exludedAttributes has no effect when searching for users.

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
To include the device's lastSuccessfulDate and lastSuccessfulAuthPolicy , add the urn:hid:scim:api:idp:2.0:UserDevice extension and api-version=7 (or later) to the query parameter

Payload: N/A

Copy

Sample Request

GET https://[base-server-url]/scim/tenant/v2/Users/38857?api-version=9 HTTP/1.1

Copy

Sample Response

HTTP/1.1 200 OK
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "38857",
    "meta": {
        "resourceType": "User",
        "created": "2023-01-05T00:00:00Z",
        "location": https://[base-server-url]/scim/tenant/v2/Users/38857,
        "version": "1"
    },
    "userName": myuser@company.com,
    "userType": "FTRESS",
    "active": true,
    "emails": [{"value": " myuser@company.com"}],
    "phoneNumbers": [{"value": "+00112345680"}],
    "groups": [ {
        "type": "Group",
        "display": "ROOT",
        "value": "UG_ROOT",
        "$ref": https://[base-server-url]/scim/tenant/v2/Groups/UG_ROOT
    }]
}

Copy

Sample Request to get additional information about the user's devices

GET https://[base-server-url]/scim/tenant/v2/Users/11058?api-version=9&attributes=urn:hid:scim:api:idp:2.0:UserDevice HTTP/1.1

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"
    ],
    "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"
    }],
    "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": [
        {
            "display": "969c082357acb375f051d4897f9f1518",
            "value": "13527",
            "friendlyName": "HID Crescendo Key",
            "lastSuccessfulDate": "2023-02-17T16:18:06Z",
            "lastSuccessfulAuthPolicy": "AT_FIDO",
            "$ref": "https://[base-server-url]/scim/tenant/v2/Device/13527"
        },
        {
            "display": "f450881d-cef0-4f09-a4f5-672a5c52a6db",
            "value": "13757",
            "friendlyName": "AAHID6GRFQ13",
            "lastSuccessfulDate": "2023-02-27T16:08:11Z",
            "lastSuccessfulAuthPolicy": "AT_PASA",
            "$ref": "https://[base-server-url]/scim/tenant/v2/Device/13757"
        }
    ]}
}

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

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?api-version=9

Copy

Sample Request to update the DOB user attribute and add the custom attribute with multiple values for office locations

UserAuthenticator and UserDevice remain untouched.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:hid:scim:api:idp:2.0:Attribute"
    ],
    "externalId": "jdoe",
    "groups":    [{
        "value": "USG_CUST2"
    }],
    "urn:hid:scim:api:idp:2.0:UserAttribute": {
        "attributes": [
        {
            "name": "DOB",
            "value": "1980-08-01"
        },
        {
            "name": "CUSTOM_ATTRIBUTE_OFFICE",
            "type": "string",
            "multiValued": true,
            "value": [
                "London",
                "Paris"
            ],
            "readOnly": false
        }]
    }
}

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
        },
        {
            "name": "CUSTOM_ATTRIBUTE_OFFICE",
            "type": "string",
            "multiValued": true,
            "value": [
                "London",
                "Paris"
            ],
            "readOnly": false
        }
    ]},
    "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": [
        {
            "display": "AT_FIDO",
            "value": "11094.AT_FIDO",
            "$ref": "https://[base-server-url]/scim/tenant/v2/Authenticator/11094.AT_FIDO"
        },
        {
            "display": "AT_CUSTPW",
            "value": "11094.AT_CUSTPW",
            "$ref": "https://[base-server-url]/scim/tenant/v2/Authenticator/11094.AT_CUSTPW"
        }
    ]},
    "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": [
        {
            "display": "969c082357acb375f051d4897f9f1518",
            "value": "13527",
            "friendlyName": "HID Crescendo Key",
            "lastSuccessfulDate": "2023-02-17T16:18:06Z",
            "lastSuccessfulAuthPolicy": "AT_FIDO",
            "$ref": "https://[base-server-url]/scim/tenant/v2/Device/13527"
        }
    ]}
}

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
id	eq
username	eq, co, ew, sw, pr
externalid	eq, co, ew, sw, pr
displayname	eq, co, ew, sw, pr
emails	eq, co, ew, sw, pr
emails.value	eq, co, ew, sw, pr
name.familyname	eq, co, ew, sw, pr
name.givenname	eq, co, ew, sw, pr
phonenumbers	eq, co, ew, sw, pr
phonenumbers.value	eq, co, ew, sw, pr
title	eq, co, ew, sw, pr
groups.value	eq
role	eq, co, ew, sw, pr
userType	eq
userRepositoryId	eq

Data returned for API versions earlier than 7

Default properties	Attributes if specified in the query
Schema and meta data All user properties	id Properties from "attributes"

Note: You can use exludedAttributes to exclude properties that are not required.

Data returned for API version 7 and later

Default properties	Attributes if specified in the query
Schema and meta data All standard user properties: id userName name object (givenName...) displayName title active emails phonenumbers addresses groups	All standard user properties (plus schema and meta data) Properties from "attributes": urn:hid:scim:api:idp:2.0:UserAttribute roles urn:hid:scim:api:idp:2.0:UserDevice urn:hid:scim:api:idp:2.0:UserAuthenticator SecurityGroups (that is, federated groups)

Note: exludedAttributes has no effect when searching for users.

Sample Request URI

[POST] /scim/{tenant}/v2/Users/.search
Or
[POST] /scim/{tenant}/v2/Users/.search?api-version=9&attributes=urn:hid:scim:api:idp:2.0:UserDevice

Copy

Sample Request (with a filter and device information)

POST https://[base-server-url]/SCIM/tenant/v2/Users/.search?api-version=9
{     
    schemas: ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    attributes: ["urn:hid:scim:api:idp:2.0:UserDevice"],
    filter: "name.familyname eq 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 name.familyname eq f*"

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.

Important:
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.
The search results can be sorted using:
- sortBy - the created filter (the record's timestamp)
- sortOrder - either ascending or descending (or asc or desc)
Note: Sorting the User search results is available with API version 7 (or later).
For further information, see Searching with the SCIM API.

Combining Filters and Sorting

Certain rules must be applied when combing filters and sorting in a search request:

Filters used	Sorting option
None (the ‘*’ wildcard is used)	ID Username Any attribute
Single filter set on a user attribute	ID Username The user attribute set as the filter
More than one filter set on user attributes	ID Username

Copy

Sample Response (with default data and device information)

HTTP/1.1 200 OK
Content-Type: application/json+scim
{
    schemas: [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse",
        "urn:hid:scim:api:idp:2.0:UserDevice"
    ],
    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": ...
            }
            "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": [
                {
                    "display": "969c082357acb375f051d4897f9f1518",
                    "value": "13527",
                    "friendlyName": "HID Crescendo Key",
                    "lastSuccessfulDate": "2023-02-17T16:18:06Z",
                    "lastSuccessfulAuthPolicy": "AT_FIDO",
                    "$ref": "https://[base-server-url]/scim/tenant/v2/Device/13527"
                },
                {
                    "display": "f450881d-cef0-4f09-a4f5-672a5c52a6db",
                    "value": "13757",
                    "friendlyName": "AAHID6GRFQ13",
                    "lastSuccessfulDate": "2023-02-27T16:08:11Z",
                    "lastSuccessfulAuthPolicy": "AT_PASA",
                    "$ref": "https://[base-server-url]/scim/tenant/v2/Device/13757"
                }
            ]}
        }
    ]
}

Searching for repository-based users

You can search for users based on their assignment to a repository using the following parameters:

Possible values for the userType filter are:
- FTRESS – users that are bound in HID Authentication Service (that is, exist in the database)
- LDAP – users that are not yet bound in HID Authentication Service but have an external reference in an LDAP
- FTRESS_LDAP – users that are bound in HID Authentication Service and also have an external reference in an LDAP
Important: To use the userType filter, the searchRepositories parameter must be set to true.
To search for users that are in an LDAP, the searchRepositories parameter (boolean) must be set to true (the default value is false).
- When set to true, the paginated search cannot be used so startIndex must not be specified or set to 0
- When set to false, the result will only include users bound in HID Authentication Service (that is, when the source is FTRESS or FTRESS_LDAP)
The userRepositoryID search criteria can be used to search for users that have been provisioned though a specific user repository

Copy

Sample request to search for users bound in HID Authentication Service:

{
    "filter": "role eq RL_CONF*"
}

Copy

Sample request to search for LDAP users that are not yet bound in HID Authentication Service:

{
   "filter" : "groups.value eq USG_FTEMP and usertype eq LDAP",
   "count": 100,
   "searchRepositories": true
}

Copy

Sample response for users bound in HID Authentication Service

HTTP/1.1 200 OK
Content-Type: application/json+scim, 
 
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 2,
    "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": "10033",
            "externalId": "ftadmin",
            "meta": {
                "resourceType": "User",
                "created": "2010-12-31T23:00:00Z",
                "location": "https://[base-server-url]/scim/tenant/v2/Users/10033",
                "version": "1"
            },
            "userName": "ftadmin",
            "active": true,
            "groups": [ {
                "type": "Group",
                "display": "ActivID Administrators",
                "value": "FTADMIN",
                "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/FTADMIN"
            }],
            "roles": [
                {
                    "display": "Audit Viewer",
                     "value": "RL_AUDITV"
                },
                {
                    "display": "Configuration Manager",
                    "value": "RL_CFGMGR"
                },
                {
                    "display": "Configuration",
                    "value": "RL_CONFIG"
                }
            ],
            "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes": []},
            "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": [ {
                "display": "OP_ATCODE",
                "value": "10033.OP_ATCODE",
                "$ref": "https://[base-server-url]/scim/tenant/v2/Authenticator/10033.OP_ATCODE"
            }]},
            "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": []}
        },
        {
            "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": "11177",
            "externalId": "my_user",
            "meta": {
                "resourceType": "User",
                "created": "2017-10-02T22:00:00Z",
                "location": "https://[base-server-url]/scim/tenant/v2/Users/11177",
                "version": "1"
            },
            "userName": "my_user",
            "name": {"givenName": "my_user"},
            "displayName": "my_user",
            "active": true,
            "groups": [ {
                "type": "Group",
                "display": "Full Time Employees",
                "value": "USG_FTEMP",
                "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/USG_FTEMP"
            }],
            "roles": [
                {
                    "display": "Audit Viewer",
                    "value": "RL_AUDITV"
                },
                {
                    "display": "Configuration Manager",
                    "value": "RL_CFGMGR"
                },
                {
                    "display": "Configuration",
                    "value": "RL_CONFIG"
                }
            ],
            "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes": [ {
                "name": "FIRSTNAME",
                "type": "string",
                "value": "my_user",
                "readOnly": false
            }]},
            "urn:hid:scim:api:idp:2.0:UserAuthenticator": {"authenticators": []},
            "urn:hid:scim:api:idp:2.0:UserDevice": {"devices": []}
        }
    ]
}

Copy

Sample response for LDAP users that are not yet bound in HID Authentication Service

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "resources":    [
        {
            "schemas":    [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:hid:scim:api:idp:2.0:UserAttribute"
            ],
            "id": "0",
            "externalId": "ou1user2",
            "meta":    {
                "resourceType": "User",
                "location": "https://[base-server-url]/scim/tenant/v2/Users/0",
                "version": "1"
            },
            "userName": "ou1user2",
            "name": {"givenName": "ou1user2"},
            "displayName": "ou1user2",
            "userType": "LDAP",
            "active": true,
            "groups":    [{
                "type": "Group",
                "display": "Full Time Employees",
                "value": "USG_FTEMP",
                "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/USG_FTEMP"
            }],
            "urn:hid:scim:api:idp:2.0:UserAttribute": {"attributes":    [{
                "name": "FIRSTNAME",
                "type": "string",
                "value": "ou1user2",
                "readOnly": false
            }]}
        },
    <---- truncated output ---->
]}

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.
HID Authentication Service 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 HID Authentication Service).

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 HID Authentication Service).

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

Log on to the Microsoft Azure AD portal (https://aad.portal.azure.com/) and go to the Users page and then Deleted users.
Select the required user(s) and click Delete permanently.

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

Go to the user’s profile in Microsoft Azure.
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 HID Authentication Service).