Manage groups

The following sections show the REST calls to create, read, update, and delete groups, and to assign groups to users.

Create a group

Using the Identity Cloud admin UI

From the navigation bar, click Identities > Manage > Groups.
On the Groups page, click New Group.
On the New Group page, enter a name and description, and click Save.

Using REST

To create a group, send a PUT or POST request to the /openidm/managed/realm-name_group context path. The following example creates a group named employees, with ID employees:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "name": "employees",
  "description": "Group that includes temporary and permanent employees"
}' \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group?_action=create"
{
  "_id": "employees",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028",
  "name": "employees",
  "condition": null,
  "description": "Group that includes temporary and permanent employees"
}

You can also omit ?_action=create and achieve the same result:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "name": "employees2",
  "description": "Second group that includes temporary and permanent employees"
}' \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group"
{
  "_id": "employees2",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1053",
  "name": "employees2",
  "condition": null,
  "description": "Second group that includes temporary and permanent employees"
}

List groups

To list groups over REST, query the openidm/managed/realm-name_group endpoint. The following example shows the employees group that you created in the previous example:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group?_queryFilter=true"
{
  "result": [
    {
      "_id": "employees",
      "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028",
      "name": "employees",
      "condition": null,
      "description": "Group that includes temporary and permanent employees"
    },
    {
      "_id": "employees2",
      "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1053",
      "name": "employees2",
      "condition": null,
      "description": "Second group that includes temporary and permanent employees"
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

To list the managed groups in the Identity Cloud admin UI, select Identities > Manage > Groups.

Add users to a group

You add users to a group through the relationship mechanism. Relationships are essentially references from one managed object to another; in this case, from a user object to a group object. For more information about relationships, refer to Relationships between objects.

You can add group members statically or dynamically.

To add members statically, you must do one of the following:

Update the value of the user’s groups property to reference the group.
Update the value of the group’s members property to reference the user.

Dynamic groups use the result of a condition or script to update a user’s list of groups.

Add group members statically

Add a user to a group statically, using the REST interface or the Identity Cloud admin UI as follows:

Using REST

Use one of these methods to add group members over REST:

Add the user as a group member. The following example adds user scarter as a member of the employees group:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "_ref":"managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4"
}' \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group/employees/members?_action=create"
{
  "_id": "7ab79f9b-70cc-4205-acec-e675a55c9bcf",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1479",
  "_ref": "managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4",
  "_refResourceCollection": "managed/realm-name_user",
  "_refResourceId": "d5b52064-6571-488a-8d85-440a99ed00d4",
  "_refProperties": {
    "_id": "7ab79f9b-70cc-4205-acec-e675a55c9bcf",
    "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1479"
  }
}

This is the preferred method as it does not incur an unnecessary performance cost for groups with many members.

Update the user’s groups property.

The following example adds the employees group to user scarter:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[
  {
    "operation": "add",
    "field": "/groups/-",
    "value": {"_ref" : "managed/realm-name_group/employees2"}
  }
]' \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4"
{
  "_id": "d5b52064-6571-488a-8d85-440a99ed00d4",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1569",
  "country": null,
  "telephoneNumber": null,
  "mail": "scarter@example.com",
  "memberOfOrgIDs": [],
  "city": null,
  "displayName": null,
  "assignedDashboard": [],
  "effectiveAssignments": [],
  "postalCode": null,
  "description": null,
  "profileImage": null,
  "expireAccount": null,
  "accountStatus": "active",
  "aliasList": [],
  "kbaInfo": [],
  "inactiveDate": null,
  "activeDate": null,
  "consentedMappings": [],
  "sn": "Carter",
  "effectiveGroups": realm-name_group",
      "_refResourceId": "employees",
      "_ref": "managed/realm-name_group/employees"
    },
    {
      "_refResourceCollection": "managed/realm-name_group",
      "_refResourceId": "employees2",
      "_ref": "managed/realm-name_group/employees2"
    }
  ],
  "preferences": null,
  "organizationName": null,
  "givenName": "Sam",
  "stateProvince": null,
  "userName": "scarter",
  "postalAddress": null,
  "effectiveRoles": [],
  "activateAccount": null
}

When you update a user’s existing groups array, use the - special index to add the new value to the set. For more information, refer to Set semantic arrays in Patch Operation: Add.

Update the group’s members property to refer to the user.

The following sample command makes scarter a member of the employees group:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[
  {
    "operation": "add",
    "field": "/members/-",
    "value": {"_ref" : "managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4"}
  }
]' \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group/employees"
{
  "_id": "employees",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028",
  "name": "employees",
  "condition": null,
  "description": "Group that includes temporary and permanent employees"
}

The members property of a group is not returned by default in the output. To show all members of a group, you must specifically request the members property. The following example lists the members of the employees group:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group/employees?_fields=name,members"
{
  "_id": "employees",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028",
  "name": "employees",
  "members": realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4",
      "_refResourceCollection": "managed/realm-name_user",
      "_refResourceId": "d5b52064-6571-488a-8d85-440a99ed00d4",
      "_refProperties": {
        "_id": "38a23ddc-1345-48d6-b753-ad97f472a90e",
        "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1692"
      }
    }
  ]
}

Using the UI

Use one of the following UI methods to add members to a group:

Update the user entry:
1. Select Identities > Manage > Users and select the user that you want to add.
2. Select the Group tab and click Add Groups.
3. Select the group from the dropdown list and click Add.
Update the group entry:
1. Select Identities > Manage > Groups and select the group to which you want to add members.
2. Select the Members tab and click Add Members.
3. Select the user from the dropdown list and click Add.

Add group members dynamically

To add a member to a group dynamically, use a condition, expressed as a query filter, in the group definition. If the condition is true for a particular member, that member is added to the group.

A group whose membership is based on a defined condition is called a conditional group. To create a conditional group, include a query filter in the group definition.

Properties that are used as the basis of a conditional group query must be configured as searchable and must be indexed in the repository configuration. To configure a property as searchable, update its definition in your managed object configuration. For more information, refer to [objects-guide:creating-modifying-managed-objects].

To add a condition to a group using the Identity Cloud admin UI, select Set up on the group Settings tab, then define the query filter that will be used to assess the condition.

To create a conditional group over REST, include the query filter as a value of the condition property in the group definition. The following example creates a group, fr-employees, whose members will be only users who live in France (whose country property is set to FR):

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "name": "fr-employees",
  "description": "Group for employees resident in France",
  "condition": "/country eq \"FR\""
}' \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group?_action=create"
{
  "_id": "fr-employees",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1898",
  "name": "fr-employees",
  "condition": "/country eq \"FR\"",
  "description": "Group for employees resident in France"
}

When a conditional group is created or updated, Identity Cloud assesses all managed users, and recalculates the value of their groups property, if they are members of that group. When a condition is removed from a group, that is, when the group becomes an unconditional group, all members are removed from the group. So, users who became members based on the condition, have that group removed from their groups property.

When a conditional group is defined in an existing data set, every user entry (including the mapped entries on remote systems) must be updated with the relationships implied by that conditional group. The time that it takes to create a new conditional group is impacted by the number of managed users affected by the condition.

In a data set with a very large number of users, creating a new conditional group can incur a significant performance cost when you create it. If possible, set up your conditional groups at the beginning of your deployment to avoid performance issues later.

Query a user’s group memberships

To list a user’s groups, query their groups property. The following example shows that scarter is a member of two groups — the employees group, and the supervisors group:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4/groups?_queryFilter=true&_fields=_ref/*,name"
{
  "result": realm-name_group",
      "_refResourceId": "employees",
      "_refResourceRev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028",
      "name": "employees",
      "_ref": "managed/realm-name_group/employees",
      "_refProperties": {
        "_id": "38a23ddc-1345-48d6-b753-ad97f472a90e",
        "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1692"
      }
    },
    {
      "_id": "0fabd212-f0c2-4d91-91f2-2b211bb58e89",
      "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1974",
      "_refResourceCollection": "managed/realm-name_group",
      "_refResourceId": "supervisors",
      "_refResourceRev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1965",
      "name": "supervisors",
      "_ref": "managed/realm-name_group/supervisors",
      "_refProperties": {
        "_id": "0fabd212-f0c2-4d91-91f2-2b211bb58e89",
        "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1974"
      }
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

To view a user’s group membership in the Identity Cloud admin UI:

Select Identities > Manage > Users, then select the user whose groups you want to check.
Select the Group tab.
If you have a large number of groups, use the Advanced Filter option on the Group List page to build a custom query.

Remove a member from a group

To remove a static group membership from a user entry, do one of the following:

Update the value of the user’s groups property to remove the reference to the role.
Update the value of the group’s members property to remove the reference to that user.

You can use both of these methods over REST or use the Identity Cloud admin UI.

A delegated administrator must use PATCH to add or remove relationships.

Conditional group membership can only be removed when the condition is changed or removed, or when the group itself is deleted.

Using REST

Use one of the following methods to remove a member from a group:

DELETE the group from the user’s groups property, including the reference ID (the ID of the relationship between the user and the group) in the delete request.

The following example removes the employees group from user scarter. The ID required in the DELETE request is not the ID of the group but the reference _id of the relationship:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4/groups/e450a32c-e289-49e3-8de5-b0f84e07c740"
{
  "_id": "e450a32c-e289-49e3-8de5-b0f84e07c740",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2122",
  "_ref": "managed/realm-name_group/employees",
  "_refResourceCollection": "managed/realm-name_group",
  "_refResourceId": "employees",
  "_refProperties": {
    "_id": "e450a32c-e289-49e3-8de5-b0f84e07c740",
    "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2122"
  }
}

PATCH the user entry to remove the group from the array of groups, specifying the value of the group object in the JSON payload.

When you remove a group in this way, you must include the entire object in the value, as shown in the following example:

curl \
--header "Content-type: application/json" \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request PATCH \
--data '[
  {
    "operation" : "remove",
    "field" : "/groups",
    "value" : {
      "_ref": "managed/realm-name_group/employees",
      "_refResourceCollection": "managed/realm-name_group",
      "_refResourceId": "employees",
      "_refProperties": {
        "_id": "731120c0-a4e9-4e27-b201-7442169e8b7c",
        "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2218"
      }
    }
  }
]' \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4"
{
  "_id": "d5b52064-6571-488a-8d85-440a99ed00d4",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2387",
  "country": null,
  "telephoneNumber": null,
  "mail": "scarter@example.com",
  "memberOfOrgIDs": [],
  "city": null,
  "displayName": null,
  "assignedDashboard": [],
  "effectiveAssignments": [],
  "postalCode": null,
  "description": null,
  "profileImage": null,
  "expireAccount": null,
  "accountStatus": "active",
  "aliasList": [],
  "kbaInfo": [],
  "inactiveDate": null,
  "activeDate": null,
  "consentedMappings": [],
  "sn": "Carter",
  "effectiveGroups": realm-name_group",
      "_refResourceId": "supervisors",
      "_ref": "managed/realm-name_group/supervisors"
    }
  ],
  "preferences": null,
  "organizationName": null,
  "givenName": "Sam",
  "stateProvince": null,
  "userName": "scarter",
  "postalAddress": null,
  "effectiveRoles": [],
  "activateAccount": null
}

DELETE the user from the group’s members property, including the reference ID (the ID of the relationship between the user and the role) in the delete request.

The following example first queries the members of the employees group, to obtain the ID of the relationship, then removes scarter’s membership from that group:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group/employees/members?_queryFilter=true&_fields=_ref/*,name"
{
  "result": realm-name_user",
      "_refResourceId": "d5b52064-6571-488a-8d85-440a99ed00d4",
      "_refResourceRev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2432",
      "_ref": "managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4",
      "_refProperties": {
        "_id": "ef3261cd-a66f-4d3e-aad8-c0850e0b4a0e",
        "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2430"
      }
    }
  ],
  "resultCount": 1,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group/employees/members/ef3261cd-a66f-4d3e-aad8-c0850e0b4a0e"
{
  "_id": "ef3261cd-a66f-4d3e-aad8-c0850e0b4a0e",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2430",
  "_ref": "managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4",
  "_refResourceCollection": "managed/realm-name_user",
  "_refResourceId": "d5b52064-6571-488a-8d85-440a99ed00d4",
  "_refProperties": {
    "_id": "ef3261cd-a66f-4d3e-aad8-c0850e0b4a0e",
    "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2430"
  }
}

Using the UI

Use one of the following methods to remove a group member:

Select Identities > Manage > Users and select the user whose group or groups you want to remove.

Select the Group tab, select the group you want to remove, then select Remove.
Select Identities > Manage > Groups, and select the group whose members you want to remove.

Select the Members tab, select the member or members you want to remove, then select Remove.

Delete a group

To delete a group over the REST interface, simply delete that managed object. The following command deletes the employees group created in the previous section:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://<tenant-env-fqdn>/openidm/managed/realm-name_group/employees"
{
  "_id": "employees",
  "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028",
  "name": "employees",
  "condition": null,
  "description": "Group that includes temporary and permanent employees"
}

To delete a group using the Identity Cloud admin UI, select Identities > Manage > Group, select the group you want to remove, then Delete Group.