--- title: Manage groups description: You can manage groups over REST or by using the Advanced Identity Cloud admin console. component: pingoneaic page_id: pingoneaic:idm-objects:manage-groups canonical_url: https://docs.pingidentity.com/pingoneaic/idm-objects/manage-groups.html keywords: ["Data Object Model", "Groups", "REST API"] section_ids: create-a-group: Create a group using_rest: Using REST using_the_advanced_identity_cloud_admin_console: Using the Advanced Identity Cloud admin console list-groups: List groups using_rest_2: Using REST using_the_advanced_identity_cloud_admin_console_2: Using the Advanced Identity Cloud admin console add-users-to-group: Add users to a group add-members-statically: Add group members statically using_rest_3: Using REST using_the_advanced_identity_cloud_admin_console_3: Using the Advanced Identity Cloud admin console add-members-dynamically: Add group members dynamically using_rest_4: Using REST using_the_advanced_identity_cloud_admin_console_4: Using the Advanced Identity Cloud admin console querying-user-groups: Query a user's group memberships using_rest_5: Using REST using_the_advanced_identity_cloud_admin_console_5: Using the Advanced Identity Cloud admin console remove-group-member: Remove a member from a group using_rest_6: Using REST using_the_advanced_identity_cloud_admin_console_6: Using the Advanced Identity Cloud admin console delete-group: Delete a group using_rest_7: Using REST using_the_advanced_identity_cloud_admin_console_7: Using the Advanced Identity Cloud admin console --- # Manage groups You can manage groups over REST or by using the Advanced Identity Cloud admin console. You can perform the following actions with groups: * [Create a group](#create-a-group) * [List groups](#list-groups) * [Add users to a group](#add-users-to-group) * [Query a user's group memberships](#querying-user-groups) * [Remove a member from a group](#remove-group-member) * [Delete a group](#delete-group) ## Create a group You can create groups using REST or by using the Advanced Identity Cloud admin console. ### 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 " \ --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" }' \ "https:///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 " \ --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" }' \ "https:///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" } ``` ### Using the Advanced Identity Cloud admin console 1. From the navigation bar, click Identities > Manage > Alpha realm - Groups. 2. On the Groups page, click New Alpha realm - Group. 3. On the New Alpha realm - Group page, enter a name and description, and click Next. 4. Optionally, create a conditional filter to assign the group dynamically. Conditional filters are custom rules you create that, when met, assign the user to your group automatically. 5. Click Save. ## List groups ### Using REST 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 " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///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 } ``` ### Using the Advanced Identity Cloud admin console To list the managed groups in the Advanced Identity Cloud admin console, select Identities > Manage > Alpha realm - Groups. ## Add users to a group You add users to a group through the relationship mechanism. [Relationships](relationships.html) are references from one managed object to another; in this case, from a user object to a group object. For more information, refer to [Relationships between objects](relationships.html). You can add group members *statically* (manually) or *dynamically* (automated assigning through rules). To add members statically, 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 Advanced Identity Cloud admin console. #### Using REST Use one of the following 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 " \ --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" }' \ "https:///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 " \ --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"} } ]' \ "https:///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": [ { "_refResourceCollection": "managed/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](../developer-docs/crest/patch.html). * 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 " \ --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"} } ]' \ "https:///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 " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///openidm/managed/realm-name_group/employees?_fields=name,members" { "_id": "employees", "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028", "name": "employees", "members": [ { "_ref": "managed/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 Advanced Identity Cloud admin console Use one of the following UI methods to add members to a group: * Update the user entry: 1. Select Identities > Manage > Alpha realm - Users and select the user to add. 2. Select the Group tab and click Add Groups. 1. Select the group from the Groups list and click Save. * Update the group entry: 1. Select Identities > Manage > Alpha realm - 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 Members list and click Save. ### 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 member, they are added to the group. A conditional group is a group whose members are based on a defined condition, which you can specify when you [create](#create-a-group) or [modify](#manage-groups) a group. You can create a condition after you create the group as well. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You must configure the properties you use to create a conditional filter for a group as `searchable`. To configure a property as `searchable`, update its definition in your managed object configuration *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint.)*. You can find more information in [General purpose extension attributes](../identities/customize-object-types.html#use-general-purpose-extension-attributes). | When you create or update a conditional group, Advanced Identity Cloud performs the following actions: * Assesses all managed users * Recalculates the value of the user's `group` property. This only takes place if the user is a member of the group. * If you remove a condition from a group and members in the group are now not a part of the condition, all members are removed from the group and their `group` property is updated. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you define a conditional group in a data set, every user entry (including the mapped entries on remote systems) updates 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 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. | #### Using REST 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 " \ --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\"" }' \ "https:///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" } ``` #### Using the Advanced Identity Cloud admin console 1. Select Identities > Manage > Alpha realm - Groups and select the group to add a condition to. 2. Select the Settings tab and click Set up. 3. Toggle the box and define the query filter to assess the condition. 4. Click Save. ## Query a user's group memberships To list a user's groups, query their `groups` property. ### Using REST The following example shows that scarter is a member of two groups — the `employees` group and the `supervisors` group: ``` curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///openidm/managed/realm-name_user/d5b52064-6571-488a-8d85-440a99ed00d4/groups?_queryFilter=true&_fields=_ref/*,name" { "result": [ { "_id": "38a23ddc-1345-48d6-b753-ad97f472a90e", "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1692", "_refResourceCollection": "managed/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-8fbef-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 } ``` ### Using the Advanced Identity Cloud admin console 1. Select Identities > Manage > Alpha realm - Users, then select the user whose groups you want to check. 2. Select the Group tab. ## 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 by using the Advanced Identity Cloud admin console. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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 " \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "https:///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 " \ --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" } } } ]' \ "https:///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": [ { "_refResourceCollection": "managed/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 " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///openidm/managed/realm-name_group/employees/members?_queryFilter=true&_fields=_ref/*,name" { "result": [ { "_id": "ef3261cd-a66f-4d3e-aad8-c0850e0b4a0e", "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2430", "_refResourceCollection": "managed/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 " \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "https:///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 Advanced Identity Cloud admin console 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 | | | | - | ------------------------------------------------------------------------------ | | | Deleting a group removes all users in the group. This action cannot be undone. | ### Using REST 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 " \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "https:///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" } ``` ### Using the Advanced Identity Cloud admin console 1. Select Identities > Manage > Alpha realm - Groups. 2. Select the group to delete. 3. Click then Delete Alpha realm - Group. 4. A confirmation dialog displays. Click Delete.