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:

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]

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

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

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

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

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
[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"
    ]
}

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 ActivID Appliance (that is, exist in the database)
- LDAP – users that are not yet bound in ActivID Appliance but have an external reference in an LDAP
- FTRESS_LDAP – users that are bound in ActivID Appliance 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 ActivID Appliance (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 ActivID Appliance:

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

Copy

Sample request to search for LDAP users that are not yet bound in ActivID Appliance:

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

Copy

Sample response for users bound in ActivID Appliance

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 ActivID Appliance

{
    "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.
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:

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 ActivID Appliance).