Identity Cloud

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

  1. From the navigation bar, click Manage > Group.

  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:

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 the employees 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:

    1. Select Manage > User and select the user that you want to add.

    2. Select the Groups tab and click Add Groups.

    3. Select the group from the dropdown list and click Add.

  • Update the group entry:

    1. Select Manage > Group 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, see [objects-guide:creating-modifying-managed-objects].

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:

  1. Select Manage > User, then select the user whose groups you want to see.

  2. Select the Groups tab.

  3. 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.

Copyright © 2010-2022 ForgeRock, all rights reserved.