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.
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.
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 |
|
CREATE |
|
REPLACE |
|
PATCH |
To update groups in a SCIM federated repository:
|
DELETE |
|
SEARCH |
|
Create a Group
Accept: application/scim+json
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"
}
}
}
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.
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
[PUT] /Groups/{id}
Accept: application/scim+json
The following parameters can be updated:
-
displayName
-
description
Sample Request
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName" : "Business Online Banking 001",
"description" : "Sample for Business Online Banking 001"
}
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.
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.
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"
}
]
}
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 |
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.
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:
Accept: application/scim+json
Manage Groups in a SCIM Federated Repository
Microsoft Azure calls the standard Groups endpoints to manage groups.
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).
Sample Request
POST /Groups
{
"externalId": "uuid-1",
"displayName": "Group1",
"description": "azure",
"urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:Group":{
"groupType":"SECURITY_GROUP"
}
}
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.
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.
Sample Request
PATCH /Groups/<groupId>
{
"Operations": [{
"op": "Add",
"path": "members",
"value": [{
"value": "<userId>"
}]
}]
}
Get a Security Group
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"}
}