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.

For the attributes of the base resource type, see urn:hid:scim:api:idp:2.0:PermissionSet.

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

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