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; if you made further customizations to your configuration, your calls may vary.

Authentication for REST

When you set up the platform as described in this documentation, you configure IDM to act as a resource server for AM OAuth 2.0 clients. The IDM OAuth 2.0 clients present a bearer access token to IDM when requesting an operation, and IDM makes the request to AM 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 AM:

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": "<access_token>",
  "scope": "fr:idm:*",
  "token_type": "Bearer",
  "expires_in": 3599
}

Use the bearer access_token to authorize REST calls to IDM to provision identity data, such as groups.

Create a group

Using the 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/group context path.

The following example creates a group named employees, with ID employees:

curl \
--header "Authorization: Bearer <access_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://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.

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

curl \
--header "Authorization: Bearer <access_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://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:

curl \
--header "Authorization: Bearer <access_token>" \
--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.

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.

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:

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:

curl \
--header "Authorization: Bearer <access_token>" \
--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:

curl \
--header "Authorization: Bearer <access_token>" \
--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.

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:

curl \
--header "Authorization: Bearer <access_token>" \
--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:

curl \
--header "Authorization: Bearer <access_token>" \
--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.

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:

curl \
--header "Authorization: Bearer <access_token>" \
--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.

When a conditional group is created or updated, IDM 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:

curl \
--header "Authorization: Bearer <access_token>" \
--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.

To view a user’s group membership in the Admin UI:

Select Identities > Manage > Users, then select the user whose groups you want to see.
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:

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:

curl \
--header "Authorization: Bearer <access_token>" \
--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:

curl \
--header "Authorization: Bearer <access_token>" \
--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:

curl \
--header "Authorization: Bearer <access_token>" \
--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 <access_token>" \
--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:

curl \
--header "Authorization: Bearer <access_token>" \
--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.

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

ForgeRock Identity Platform 7.4

Manage groups

Authentication for REST

Create a group

Using the Admin UI

Using REST

List groups

Add users to a group

Add group members statically

Using REST

Using the UI

Add group members dynamically

Query a user’s group memberships

Remove a member from a group

Using REST

Using the UI

Delete a group