Manage groups
These sections show the REST calls to create, read, update, and delete groups, and to assign groups to users.
Create a group
Using the IDM admin UI
-
From the navigation bar, click Manage > Group.
-
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/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 '{ "_id": "employees", "name": "employees", "description": "Group that includes temporary and permanent employees" }' \ "http://<tenant-env-fqdn>/openidm/managed/group?_action=create" { "_id": "employees", "_rev": "0000000067dba53b", "name": "employees", "description": "Group that includes temporary and permanent employees" }
The following example creates a group with a system-generated ID:
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/group" { "_id": "444940e2-e0e8-4f02-98d5-30b3e74dbb98", "_rev": "0000000067dba53b", "name": "employees", "description": "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:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://<tenant-env-fqdn>/openidm/managed/group?_queryFilter=true" { "result": [ { "_id": "employees", "_rev": "0000000067dba53b", "name": "employees", "description": "Group that includes temporary and permanent employees" } ], ... }
To list the managed groups in the IDM admin UI, select Manage > Group.
If you have a large number of groups, select Advanced Filter to build a more complex query filter 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, see 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 groups’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 IDM 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/scarter", "_refProperties":{} }' \ "http://<tenant-env-fqdn>/openidm/managed/group/employees/members?_action=create" { "_id": "105cdbdb-a3c2-489b-9082-6e1aaff16d31", "_rev": "000000008a2c93f9", "_ref": "managed/realm-name_user/scarter", "_refResourceCollection": "managed/realm-name_user", "_refResourceId": "scarter", "_refProperties": { "_id": "105cdbdb-a3c2-489b-9082-6e1aaff16d31", "_rev": "000000008a2c93f9" } }
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/group/employees"} } ]' \ "http://<tenant-env-fqdn>/openidm/managed/realm-name_user/scarter" { "_id": "scarter", "_rev": "00000000788ed06a", "mail": "scarter@example.com", "givenName": "Steven", "sn": "Carter", "description": "Example User", "userName": "scarter", "telephoneNumber": "1234567", "accountStatus": "active", "memberOfOrgIDs": [], "effectiveRoles": [], "effectiveAssignments": [] }
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. -
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/scarter"} } ]' \ "http://<tenant-env-fqdn>/openidm/managed/group/employees" { "_id": "employees", "_rev": "0000000067dba53b", "name": "employees", "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 theemployees
group:curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://<tenant-env-fqdn>/openidm/managed/group/employees?_fields=*_ref,name" { "_id": "employees", "_rev": "0000000067dba53b", "name": "employees", "members": [ { "_ref": "managed/realm-name_user/scarter", "_refResourceCollection": "managed/realm-name_user", "_refResourceId": "scarter", "_refProperties": { "_id": "9a3c7b7f-29a8-4b56-99c3-698fd0cd6b65", "_rev": "00000000ae8194c1" } }, { "_ref": "managed/realm-name_user/bjensen", "_refResourceCollection": "managed/realm-name_user", "_refResourceId": "bjensen", "_refProperties": { "_id": "2a965519-5788-428c-92d1-19fac497db8f", "_rev": "000000001e1793bc" } } ] }
Using the UI
Use one of the following UI methods to add members to a group:
-
Update the user entry:
-
Select Manage > User and select the user that you want to add.
-
Select the Groups tab and click Add Groups.
-
Select the group from the dropdown list and click Add.
-
-
Update the group entry:
-
Select Manage > Group and select the group to which you want to add members.
-
Select the Members tab and click Add Members.
-
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 |
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/group?_action=create" { "_id": "fr-employees", "_rev": "00000000092faa7f", "condition": "/country eq \"FR\"", "name": "fr-employees", "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 therefore incur a significant performance cost when you create it. Ideally, you should 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/scarter/groups?_queryFilter=true&_fields=_ref/*,name" { "result": [ { "_id": "9a3c7b7f-29a8-4b56-99c3-698fd0cd6b65", "_rev": "00000000ae8194c1", "_refResourceCollection": "managed/group", "_refResourceId": "employees", "_refResourceRev": "0000000067dba53b", "name": "employees", "_ref": "managed/group/employees", "_refProperties": { "_id": "9a3c7b7f-29a8-4b56-99c3-698fd0cd6b65", "_rev": "00000000ae8194c1" } }, { "_id": "431f7a46-a5ca-4ad6-9d0e-666d5fad1be6", "_rev": "000000002df096de", "_refResourceCollection": "managed/group", "_refResourceId": "supervisors", "_refResourceRev": "00000000f220b6bf", "name": "supervisors", "_ref": "managed/group/supervisors", "_refProperties": { "_id": "431f7a46-a5ca-4ad6-9d0e-666d5fad1be6", "_rev": "000000002df096de" } }, ... ] }
To view a user’s group membership in the IDM admin UI:
-
Select Manage > User, then select the user whose groups you want to see.
-
Select the Groups 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 groups’s
members
property to remove the reference to that user.
You can use both of these methods over REST, or use the IDM 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 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. Note that 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/scarter/groups/9a3c7b7f-29a8-4b56-99c3-698fd0cd6b65" { "_id": "9a3c7b7f-29a8-4b56-99c3-698fd0cd6b65", "_rev": "00000000ae8194c1", "_ref": "managed/group/employees", "_refResourceCollection": "managed/group", "_refResourceId": "employees", "_refProperties": { "_id": "9a3c7b7f-29a8-4b56-99c3-698fd0cd6b65", "_rev": "00000000ae8194c1" } }
-
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/group/employees", "_refResourceCollection": "managed/group", "_refResourceId": "employees", "_refProperties": { "_id": "9a3c7b7f-29a8-4b56-99c3-698fd0cd6b65", "_rev": "00000000ae8194c1" } } } ]' \ "http://<tenant-env-fqdn>/openidm/managed/realm-name_user/scarter" { "_id": "scarter", "_rev": "000000007631d204", "mail": "scarter@example.com", "givenName": "Steven", "sn": "Carter", "description": "Created By CSV", "userName": "scarter", "telephoneNumber": "1234567", "accountStatus": "active", "memberOfOrgIDs": [], "effectiveRoles": [], "effectiveAssignments": [] }
-
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 bjensen’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/group/employees/members?_queryFilter=true&_fields=_ref/*,name" { "result": [ { "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72", "_rev": "00000000c25d994a", "_ref": "managed/realm-name_user/bjensen", "_refResourceCollection": "managed/realm-name_user", "_refResourceId": "bjensen", "_refProperties": { "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72", "_rev": "00000000c25d994a" } } ], ... } curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "http://<tenant-env-fqdn>/openidm/managed/group/employees/members/a5a4bf94-6425-4458-aae4-bbd6ad094f72" { "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72", "_rev": "00000000c25d994a", "_ref": "managed/realm-name_user/bjensen", "_refResourceCollection": "managed/realm-name_user", "_refResourceId": "bjensen", "_refProperties": { "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72", "_rev": "00000000c25d994a" } }
Using the UI
Use one of the following methods to remove a group member:
-
Select Manage > User 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 Selected Groups.
-
Select Manage > Group, and select the group whose members you want to remove.
Select the Members tab, select the member or members that that you want to remove, then select Remove Selected Members.
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/group/employees" { "_id": "employees", "_rev": "0000000067dba53b", "name": "employees", "description": "Group that includes temporary and permanent employees" }
To delete a group using the IDM admin UI, select Manage > Group, select the group you want to remove, then Delete Selected.