PingOne Advanced Identity Cloud

Manage groups

You can manage groups over REST or by using the Advanced Identity Cloud admin UI.

You can perform the following actions with groups:

Create a group

You can create groups using REST or by using the Advanced Identity Cloud admin UI.

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 <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"
}' \
"https://<tenant-env-fqdn>/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 <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"
}' \
"https://<tenant-env-fqdn>/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 UI

  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 <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/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 UI

To list the managed groups in the Advanced Identity Cloud admin UI, select Identities > Manage > Alpha realm - Groups.

Add users to a group

You add users to a group through the relationship mechanism. Relationships 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.

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

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 <token>" \
--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://<tenant-env-fqdn>/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 <token>" \
--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://<tenant-env-fqdn>/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.

  • 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/d5b52064-6571-488a-8d85-440a99ed00d4"}
  }
]' \
"https://<tenant-env-fqdn>/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 <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/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 UI

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 or modify 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. You can find more information in 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 <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\""
}' \
"https://<tenant-env-fqdn>/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 UI

  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 <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/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 UI

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

  • 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 <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/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 <token>" \
--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://<tenant-env-fqdn>/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 <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/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 <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/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 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 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 <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/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 UI

  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.