--- title: Manage groups description: The following sections show the REST calls to create, read, update, and delete groups, and to assign groups to users. component: platform version: 8 page_id: platform:sample-setup:manage-groups canonical_url: https://docs.pingidentity.com/platform/8/sample-setup/manage-groups.html page_aliases: ["platform-setup-guide:manage-groups.adoc"] section_ids: manage-groups-rest-authentication: Authentication for REST create-a-group: Create a group using_the_admin_ui: Using the Admin UI using_rest: Using REST list-groups: List groups add-users-to-group: Add users to a group add-members-statically: Add group members statically using_rest_2: Using REST using_the_ui: Using the UI add-members-dynamically: Add group members dynamically querying-user-groups: Query a user's group memberships remove-group-member: Remove a member from a group using_rest_3: Using REST using_the_ui_2: Using the UI delete-group: Delete a group --- # Manage groups The following sections show the REST calls to create, read, update, and delete groups, and to assign groups to users. They are set up to use the default configuration for groups as a managed object type, discussed in [Groups](groups.html); if you made further customizations to your configuration, your calls may vary. ## Authentication for REST When you set up Advanced Identity Software as described in this documentation, you configure PingIDM to act as a resource server for PingAM OAuth 2.0 clients. The PingIDM OAuth 2.0 clients present a bearer access token to PingIDM when requesting an operation, and PingIDM makes the request to PingAM to introspect the token and reach an authorization decision. To provision identities, use the `idm-provisioning` client, whose client secret shown in this documentation is `openidm`. The `idm-provisioning` client uses the client credentials grant to request an access token from PingAM: ```bash curl \ --request POST \ --data "grant_type=client_credentials" \ --data "client_id=idm-provisioning" \ --data "client_secret=openidm" \ --data "scope=fr:idm:*" \ "http://am.example.com:8081/am/oauth2/realms/root/realms/alpha/access_token" { "access_token": "", "scope": "fr:idm:*", "token_type": "Bearer", "expires_in": 3599 } ``` Use the bearer *access\_token* to authorize REST calls to PingIDM to provision identity data, such as groups. ## Create a group ### Using the Admin UI 1. From the navigation bar, click Identities > Manage > Groups. 2. On the Groups page, click New Group. 3. 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/group` context path. The following example creates a group named `employees`, with ID `employees`: ```bash 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" }' \ "http://openidm.example.com:8080/openidm/managed/group?_action=create" { "_id": "employees", "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028", "name": "employees", "condition": null, "description": "Group that includes temporary and permanent employees" } ``` To get an *access\_token*, see [Authentication for REST](#manage-groups-rest-authentication). You can also omit `?_action=create` and achieve the same result: ```bash 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" }' \ "http://openidm.example.com:8080/openidm/managed/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/group` endpoint. The following example shows the `employees` group that you created in the previous example: ```bash curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://openidm.example.com:8080/openidm/managed/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 get an *access\_token*, see [Authentication for REST](#manage-groups-rest-authentication). To list the managed groups in the Admin UI, select Identities > Manage > Groups. If you have a large number of groups, use the search box to display only the groups you want. ## 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](https://docs.pingidentity.com/pingidm/8/objects-guide/relationships.html). 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 Admin UI as follows: #### Using REST Use one of these methods to add group members over REST. To get an *access\_token*, see [Authentication for REST](#manage-groups-rest-authentication): * Add the user as a group member. The following example adds the user with ID `808cca7b-6c7f-40e5-b890-92b7b6eda08c` as a member of the group you created, `employees`: ```bash curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "_ref":"managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refProperties":{} }' \ "http://openidm.example.com:8080/openidm/managed/group/employees/members?_action=create" { "_id": "393916e8-e43b-4e83-b372-7816b5e18fac", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-4792", "_ref": "managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refResourceCollection": "managed/user", "_refResourceId": "808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refProperties": { "_id": "393916e8-e43b-4e83-b372-7816b5e18fac", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-4792" } } ``` | | | | - | --------------------------------------------------------------------------------------------------------------- | | | 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 `employees2` group to the same user: ```bash 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/group/employees2"} } ]' \ "http://localhost:8080/openidm/managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c" { "_id": "808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_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/group", "_refResourceId": "employees", "_ref": "managed/group/employees" }, { "_refResourceCollection": "managed/group", "_refResourceId": "employees2", "_ref": "managed/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, see *Set semantic arrays* in [Patch operation: add](https://docs.pingidentity.com/pingidm/8/crest/crest-patch.html#crest-patch-add). * Update the group's `members` property to refer to the user. The following sample command makes the user a member of the group you created: ```bash 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/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c"} } ]' \ "http://openidm.example.com:8080/openidm/managed/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 relationship properties (`*_ref`) in your query. The following example lists the members of the group you created: ```bash curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://openidm.example.com:8080/openidm/managed/group/employees?_fields=name,members" { "_id": "employees", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-4160", "name": "employees", "members": [{ "_ref": "managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refResourceCollection": "managed/user", "_refResourceId": "808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refProperties": { "_id": "245c9009-a812-4d54-ae6c-02756243f7cb", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-4898" } }] } ``` #### 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 configuration.For more information, see [Create and modify object types](https://docs.pingidentity.com/pingidm/8/objects-guide/creating-modifying-managed-objects.html). | To add a condition to a group using the 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 whose members are only users who live in France, meaning their `country` property is set to `FR`: ```bash curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "description": "Group for employees resident in France", "condition": "/country eq \"FR\"" }' \ "http://openidm.example.com:8080/openidm/managed/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" } ``` To get an *access\_token*, see [Authentication for REST](#manage-groups-rest-authentication). When a conditional group is created or updated, PingIDM 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 a user who is a member of two groups: ```bash curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://openidm.example.com:8080/openidm/managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c/groups?_queryFilter=true&_fields=_ref/*,name" { "result": [ { "_id": "38a23ddc-1345-48d6-b753-ad97f472a90e", "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1692", "_refResourceCollection": "managed/group", "_refResourceId": "employees", "_refResourceRev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028", "name": "employees", "_ref": "managed/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/group", "_refResourceId": "supervisors", "_refResourceRev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1965", "name": "supervisors", "_ref": "managed/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 get an *access\_token*, see [Authentication for REST](#manage-groups-rest-authentication). To view a user's group membership in the Admin UI: 1. Select Identities > Manage > Users, then select the user whose groups you want to see. 2. Select the Groups tab. If you have a large number of groups, use the search box to display only the groups you want. ## 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 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. To get an *access\_token*, see [Authentication for REST](#manage-groups-rest-authentication): * 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 a group from a user. Note that ID required in the DELETE request is not the ID of the group but the reference `_id` of the relationship: ```bash curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "http://openidm.example.com:8080/openidm/managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c/groups/e450a32c-e289-49e3-8de5-b0f84e07c740" { "_id": "e450a32c-e289-49e3-8de5-b0f84e07c740", "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2122", "_ref": "managed/group/employees", "_refResourceCollection": "managed/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:```bash curl \ --header "Authorization: Bearer " \ --header "Content-type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request PATCH \ --data '[ { "operation" : "remove", "field" : "/groups", "value" : { "_ref": "managed/group/0bf541d3-e7da-478a-abdd-41cdb74b2cbb", "_refResourceCollection": "managed/group", "_refResourceId": "0bf541d3-e7da-478a-abdd-41cdb74b2cbb", "_refProperties": { "_id": "8174332d-b448-4fe1-b507-b8e4751e08ba", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-5015" } } } ]' \ "http://openidm.example.com:8080/openidm/managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c" { "_id": "808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-5245", "userName": "demo", "customAttribute": "Testing 1, 2…​", "accountStatus": "active", "givenName": "Demo", "sn": "User", "mail": "demo@example.com" } ``` | * 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 group to obtain the ID of the relationship, then removes the user's membership from that group: ```bash curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://openidm.example.com:8080/openidm/managed/group/employees/members?_queryFilter=true&_fields=_ref/*,name" { "result": [{ "_id": "ef3261cd-a66f-4d3e-aad8-c0850e0b4a0e", "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-2430" "_refResourceCollection": "managed/user", "_refResourceId": "808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refResourceRev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-5245", "_ref": "managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refProperties": { "_id": "245c9009-a812-4d54-ae6c-02756243f7cb", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-4898" } }], "resultCount": 1, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 } curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "http://openidm.example.com:8080/openidm/managed/group/employees/members/245c9009-a812-4d54-ae6c-02756243f7cb" { "_id": "245c9009-a812-4d54-ae6c-02756243f7cb", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-4898", "_ref": "managed/user/808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refResourceCollection": "managed/user", "_refResourceId": "808cca7b-6c7f-40e5-b890-92b7b6eda08c", "_refProperties": { "_id": "245c9009-a812-4d54-ae6c-02756243f7cb", "_rev": "ce85fb00-1c27-47da-9d7a-8b6d4fcedb16-4898" } } ``` ### 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 Groups tab, select the group that 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 that 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 group you created: ```bash curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "http://openidm.example.com:8080/openidm/managed/group/employees" { "_id": "employees", "_rev": "ae6e63c4-94f5-463b-8bef-7a359b8e3004-1028", "name": "employees", "condition": null, "description": "Group that includes temporary and permanent employees" } ``` To get an *access\_token*, see [Authentication for REST](#manage-groups-rest-authentication). To delete a group using the Admin UI, select Identities > Manage > Groups, select the group you want to remove, then Delete Group.