Groups REST API

The Groups endpoint allows creating and managing subgroups. You can also create and manage security groups in a SCIM federated repository.

Groups are used to model the organizational structure of provisioned resources. Groups can contain users or other groups.

A group is always returned along with its members. The caller can use the Users/.search if the group has a large number of users. Only subgroups of the group appear in members.

Note: The API version supported by HID Authentication Service is 10.1.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.

Method Details

HTTPS Method	Entity Action	Request URI	Description
GET	Read	/scim/{tenant}/v2/Groups/	Get all groups filtered by attributes
GET	Read	/scim/{tenant}/v2/Groups/{id}:(String)	Get a known group
POST	Create	/scim/{tenant}/v2/Groups/	Create a new sub group
POST	Search	/scim/{tenant}/v2/Groups/.search	Search for groups
PUT	Replace	/scim/{tenant}/v2/Groups/{id}:(String)	Fully replace a known group
DELETE	Delete	/scim/{tenant}/v2/Groups/{id}:(String)	Delete a known group

Required Permissions

Function	Required Permissions
GET	Read reference data To get groups in a SCIM federated repository: Read security group
CREATE	Create user group Read reference data To create groups in a SCIM federated repository: Create security group
REPLACE	Read reference data If it is a root group or subgroup: Update user group Update root group Details If updating user attribute types: Update root group Attributes
PATCH	To update groups in a SCIM federated repository: Update security group
DELETE	Delete root group To delete groups in a SCIM federated repository: Delete security group Read reference data
SEARCH	Read reference data

Create a Group

Accept: application/scim+json

Note: You can only create a subgroup under an existing parent group.

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Groups

Copy

Sample Request

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:hid:scim:api:idp:2.0:GroupParent"
    ],
    "externalId": "USG_CUST3",
    "displayName": "My Test Group",
    "description": "Description for my test group",
    "urn:hid:scim:api:idp:2.0:GroupParent": {
        "parent": {
            "display": "Customers User Type",
            "value": "UT_CUST"
        }
    }
}

Copy

Sample Response

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:hid:scim:api:idp:2.0:GroupParent"
    ],
    "id": "USG_CUST3",
    "externalId": "USG_CUST3",
    "meta": {
        "resourceType": "Group",
        "location": "https://[base-server-url]/scim/tenant/v2/Groups/USG_CUST3",
        "version": "1"
    },
    "displayName": "My Test Group",
    "members": [],
    "description": "Description for my test group",
    "urn:hid:scim:api:idp:2.0:GroupParent": {
        "parent": {
            "type": "Group",
            "display": "Customers User Type",
            "value": "UT_CUST",
            "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/UT_CUST"
        }
    }
}

Get a Group

[GET] /Groups/{id}

The SCIM Core specification - section 4.2 states that a group must be returned along with its members. Only subgroups of the group will appear in members.

Note: GET /Groups can also be used to get the list of user attribute types for this group, although this parameter is returned only if the query "api-version" parameter is equal to or greater than 3.

Copy

Sample Request URI

[GET] /scim/{tenant}/v2/Groups/FTADMIN

Copy

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json+scim, 
Location: https://[base-server-url]/SCIM/tenant/v2/Groups/FTADMIN
 
{
   "schemas":    [
      "urn:ietf:params:scim:schemas:core:2.0:Group",
      "urn:hid:scim:api:idp:2.0:GroupParent"
   ],
   "id": "FTADMIN",
   "externalId": "FTADMIN",
   "meta":    {
      "resourceType": "Group",
      "location": "https://[base-server-url]/SCIM/tenant/v2/Groups/FTADMIN",
      "version": "1"
   },
   "displayName": "ActivID Administrators",
   "members":    [{
      "type": "Group",
      "display": "Subgroup of ActivID Administrators",
      "value": "FT_SUBGROUP",
      "$ref": "https://[base-server-url]/SCIM/tenant/v2/Groups/FT_SUBGROUP"
   }],
   "description": "ActivID Administrators with permissions for configuration management",
   "urn:hid:scim:api:idp:2.0:GroupParent": {
        "parent": {
              "type": "Group",
              "display": "ActivID Initial Setup",
              "value": "FTRESS",
              "$ref": "https://[base-server-url]/SCIM/tenant/v2/Groups/FTRESS"
           }
    }
}

Replace a Group

Note: PUT /Group can also be used to modify the list of user attribute types for this group, although this parameter is returned only if the query "api-version" parameter is equal to or greater than 3.

[PUT] /Groups/{id}

Accept: application/scim+json

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

The following parameters can be updated:

displayName
description

Copy

Sample Request URI

[PUT] /scim/{tenant}/v2/Groups/USG_FSTEMP

Copy

Sample Request

{
   "schemas":    ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "displayName" : "Business Online Banking 001",
   "description" : "Sample for Business Online Banking 001"
}

Copy

Sample Response

{
   "schemas":    [
      "urn:ietf:params:scim:schemas:core:2.0:Group",
      "urn:hid:scim:api:idp:2.0:GroupParent"
   ],
   "id": "USG_CUST2",
   "externalId": "USG_CUST2",
   "meta":    {
      "resourceType": "Group",
      "location": "https://[base-server-url]/scim/tenant/v2/Groups/USG_CUST2",
      "version": "1"
   },
   "displayName": "Business Online Banking 001",
   "members": [],
   "description": "Sample for Business Online Banking 001",
   "urn:hid:scim:api:idp:2.0:GroupParent": {
        "parent":    {
            "type": "Group",
            "display": "Customers User Type",
            "value": "UT_CUST",
            "$ref": "https://[base-server-url]/scim/tenant/v2/Groups/UT_CUST"
        }
    }
}

Replace a Group for User Attribute Types

Replace Group can also be used to modify the list of user attribute types for this group.

Note:

This can only be performed on root groups (= user types).
The query parameter "api-version" must equal or be greater than 3.
Only the property "id" from "urn:hid:scim:api:idp:2.0:userattribute:Type" is read (so other parameters are optional).

PUT /scim/{tenant}/v2/Groups/{id}?api-version=3

Where id is the name of the root group.

Copy

Sample Request URI

PUT /scim/{tenant}/v2/Groups/FTRESS?api-version=3

Copy

Sample request where the user attribute type "TEST2" is added to the root group "FTRESS"

{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "id": "FTRESS",
   "userAttributeTypes": [
        {
             "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
             "id": "ADDRESS1",
             "meta": {
                "resourceType": "UserAttributeType",
                "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/ADDRESS1",
                "version": "1"
             },
            "name": "Address Line 1"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
            "id": "FIRSTNAME",
            "meta": {
                "resourceType": "UserAttributeType",
                "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/FIRSTNAME",
                "version": "1"
            },
            "name": "First Name"
         },
        {
             "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
            "id": "LASTNAME",
            "meta": {
                "resourceType": "UserAttributeType",
                "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/LASTNAME",
                "version": "1"
            },
            "name": "Last Name"
        },
        {
            "id": "TEST2"
        }
    ]
}

Copy

Sample Response

{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "id": "FTRESS",
   "externalId": "FTRESS",
   "meta":    {
        "resourceType": "Group",
        "location": "https://[base-server-url]/configuration/tenant/v2/Groups/FTRESS",
        "version": "1"
    },
    "displayName": "ActivID Initial Setup",
    "members":    [
        {
            "type": "Group",
            "display": "ActivID Administrators",
            "value": "FTADMIN",
            "$ref": "https://[base-server-url]/configuration/tenant/v2/Groups/FTADMIN"
         },
        {
            "type": "Group",
            "display": "ActivID Prime Users",
            "value": "FTSETUP",
            "$ref": "https://[base-server-url]/configuration/tenant/v2/Groups/FTSETUP"
        },
        {
            "type": "Group",
            "display": "ActivID Setup",
            "value": "FTINIT",
            "$ref": "https://[base-server-url]/configuration/tenant/v2/Groups/FTINIT"
        }
    ],
    "userAttributeTypes":    [
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
            "id": "ADDRESS1",
            "meta": {
                "resourceType": "UserAttributeType",
                "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/ADDRESS1",
                "version": "1"
            },
            "name": "Address Line 1"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
            "id": "TEST2",
            "meta": {
                "resourceType": "UserAttributeType",
                "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/TEST2",
                "version": "1"
            },
            "name": "test2",
            "notes": "notes"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
            "id": "FIRSTNAME",
            "meta": {
                "resourceType": "UserAttributeType",
                "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/FIRSTNAME",
                "version": "1"
            },
            "name": "First Name"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:userattribute:Type"],
            "id": "LASTNAME",
            "meta": {
                "resourceType": "UserAttributeType",
                "location": "https://[base-server-url]/configuration/tenant/v2/User/AttributeType/LASTNAME",
                "version": "1"
            },
            "name": "Last Name"
        }
    ],
    "description": "ActivID initial users for default configuration and system reset"
}

Search for a Group

See Searching with the SCIM API.

Supported search criteria:

SCIM Attribute	Operators supported
id	eq
externalid	eq
displayName	eq
groupType	eq

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Groups/.search

Copy

Sample Request

[POST] /scim/{tenant}/v2/Groups/.search
{
 "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
 "filter": "id eq MyUser1"
}

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

You can use the and operator within the filters.

Note:

Logical operators are not supported.
Supported values for groupType for SCIM federated repositories:
- SECURITY_GROUP
- ADMINISTRATION_GROUP
Supported output:
- attributes
- excludedAttributes
Not supported:
- count
- startIndex
- sortBy
- sortOrder

For further information, see Searching with the SCIM API.

Delete a Group

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

Manage Groups in a SCIM Federated Repository

Microsoft Azure calls the standard Groups endpoints to manage groups.

Note:

PATCH /Groups can only be used on security groups to add/remove members.
PUT /Groups only supports administration groups.

Create a Security Group

With the extension set in the group attribute mapping (see Configure Microsoft Azure for Provisioning), Microsoft Azure creates Security Groups (but not Administration Groups).

Copy

Sample Request

POST /Groups
{
    "externalId": "uuid-1",
    "displayName": "Group1",
    "description": "azure",
    "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:Group":{
        "groupType":"SECURITY_GROUP"
    }
}

Copy

Sample Response

{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "id": "11952",
   "externalId": "uuid-3",
   "displayName": "Group1",
   "members": []
}

Search for Security Groups

You can search for security groups in SCIM federated repositories using the groupType filter where the possible values are SECURITY_GROUP or ADMINISTRATION_GROUP.

Copy

Sample Request

POST /Groups/.search
{
    "filter": "groupType eq SECURITY_GROUP"
}

Copy

Sample Response

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 1,
   "resources": [   {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "11733",
      "externalId": "uuid-1",
      "displayName": "Group1",
      "members": [],
      "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:Group": {"groupType": "SECURITY_GROUP"}
   }]
}

Patch a Security Group

You can patch a security to add or remove a member.

Copy

Sample Request

PATCH /Groups/<groupId>
{
    "Operations": [{
        "op": "Add",
        "path": "members",
        "value": [{
            "value": "<userId>"
        }]
    }]
}

Get a Security Group

Copy

Sample Request

GET /Groups/11733

Copy

Sample Response

{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
   "id": "11733",
   "externalId": "uuid-1",
   "displayName": "Group1",
   "members": [{
      "type": "User",
      "value": "11892",
      "$ref": "https://[base-server-url]/scim/tenant/v2/Users/11892"
   }],
   "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:Group": {"groupType": "SECURITY_GROUP"}
}