The Groups service enables you to create collections of users having the same access to applications. You can create up to 100,000 groups per environment. There is no limit to the number of users that can belong to a group.

External groups {#groups-external-groups}

External groups are groups that originate outside of PingOne. An external group is created using a Just In Time (JIT) method by setting the memberOfExternalGroups property when adding a new user. See the Users data model for more information.

External group constraints

As opposed to internal PingOne groups, there are a few things external groups cannot do:

Errors will occur if:

Groups permissions {#groups-groups-permissions}

If you have the Identity Data Admin role, you can perform the following operations using the PingOne APIs:

If you have the Environment Admin or Client Application Developer role, you can read groups.

Creating groups {#groups-creating-groups}

Use POST /environments/{{envID}}/groups to create a new group.

By default, groups are created per environment. Groups can also optionally be created per population. Do this by specifying a value for population.id in the body of POST /environments/{{envID}}/groups. The population.id property is read-only after it is initially set and can be set in POST /environments/{{envID}}/groups only.

Adding users to a group {#groups-adding-users-to-a-group}

There are two ways to add users to a group. The first is to directly add them with the POST /environments/{{envID}}/users/{{userID}}/memberOfGroups operation. These members are included in both the directUserCounts and totalUserCounts properties.

The second method is to dynamically add users to a group with the userFilter filter property. You can use this filter with the POST /environments/{{envID}}/groups and PUT /environments/{{envID}}/groups/{{groupID}} operations. Place the filter in the body of the request as shown in the example below:

{
    ...
    "userFilter": "title eq \'Manager\'",
    ...
}

When the POST or PUT operations above are executed, all existing users that meet the filter criteria are dynamically added to the group. In addition, all subsequent new users that are added that meet the filter criteria are also added to the group. The filter supports all the operators and properties that are supported when searching user data. See Users for a complete list. Members added in this way are included in the totalUserCounts property, but not the directUserCounts property.

Removing users from a group {#groups-removing-users-from-a-group}

Members directly added to a group with the POST /environments/{{envID}}/users/{{userID}}/memberOfGroups operation are removed from the group with the DELETE /environments/{{envID}}/users/{{userID}}/memberOfGroups/{{groupID}} operation.

Members dynamically added to a group with the userFilter filter property are automatically removed from the group when the filter criteria is no longer met. You can do this by changing the filter criteria with PUT /environments/{{envID}}/groups/{{groupID}} or by changing the user data to no longer match the filter criteria. You cannot remove these members with the DELETE /environments/{{envID}}/users/{{userID}}/memberOfGroups/{{groupID}} operation.

Nesting groups {#groups-nesting-groups}

You can nest one group inside another. The members of the nested group dynamically become members of the parent group. Do this by specifying the ID of a group within the body of a POST {{apiPath}}/environments/{{envID}}/groups/{{groupID}}/memberOfGroups operation. Nesting a group essentially creates a child-parent relationship where members of the “child” group inherit the same properties and permissions as the “parent” group.

For example, assume an environment has three groups: Group A, Group B, and Group C. Each group has access to a single application: Group A has access to App1, Group B has access to App2, and Group C has access to App3.

Group A - App1
    Group B - App1 & App2
        Group C - App1, App2, App3

Creating circular references {#groups-circular-references}

You can nest parent groups inside their child groups. Continuing the example from the last section, let us assume you have another group, Group D. Group D has access to App4.

Group A - App1
    Group B - App1 & App2, App4
        Group C - App1, App2, App3, App4
        Group D - App1, App2, App4
            Group B - App1, App2, App4

Removing nested relationship {#groups-removing-nested-relationship}

Use the DELETE {{apiPath}}/environments/{{envID}}/groups/{{groupID}}/memberOfGroups/{{nestedGroupID}} operation to remove the nested relationship between two groups. Members directly assigned to each group remain unchanged.

Searching for group membership {#groups-searching-for-group-membership}

Documentation for the following group membership searches can be found under Users/Group Membership:

Filtering groups searches {#groups-filtering-groups-searches}

You can filter groups GET collection responses by applying a SCIM filtering expression to the request URL. For large collections, a filter expression appended to the query returns a targeted, more useful data set.

The SCIM operators eq (equals), sw (starts with), and, and or can be used with the following group properties:

The SCIM operators eq (equals), and sw (starts with) can be used with the group property:

The SCIM operator eq (equals) can be used with the following group properties:

You can also use SCIM filters with GET collection requests that return user data. See Users for the user properties and operators supported.

Groups data model {#groups-data-model}

Property Type Required? Mutable? Description
customData JSON blob Optional Mutable User-defined custom data.
description String Optional Mutable The group description.
displayName String Optional* Immutable *This is required when creating a new external group. For Just In Time (JIT) creation of external groups, it’s set when a user is created or updated with memberOfExternalGroups[].name set. See the Users data model for more information. For internal groups it is identical to name. Groups can be filtered by displayName.
directMemberCounts Object Optional Immutable An object containing a users (int) property. This property lists the number of users explicitly added to the group with POST /environments/{{envID}}/users/{{userID}}/memberOfGroups. Since these members were explicitly added to the group, they can be removed from the group with DELETE /environments/{{envID}}/users/{{userID}}/memberOfGroups/{{groupID}}.
environment.id String Required Immutable The unique identifier for the environment.
externalId String Optional Mutable A user-defined identifier for the group. Use this propertry to syncronize a group in PingOne with the same group in an external system. PingOne does not directly use this property. Search all groups for a specific external ID with a SCIM filter using GET /environments/{{envID}}/groups.
id String Required Immutable The unique identifier for the group. Search all groups for a specific group ID with a SCIM filter on GET /environments/{{envID}}/groups. Retrieve all the group IDs associated with a user with GET /environments/{{envID}}/users/{{userID}}?include=memberOfGroupIDs.
isAdmin Boolean N/A Read-only true indicates that admin role assignments are present for this group.
name String Required Immutable The group name. A group name can be reused across populations, but the same user cannot belong to multiple groups with the same group name. Population groups cannot share a group name with an environment group. Search all groups for a specific group name with a SCIM filter on GET /environments/{{envID}}/groups. Retrieve all the group names associated with a user with GET /environments/{{envID}}/users/{{userID}}?include=memberOfGroupNames. Use this operation to determine group membership in attribute mappings for claims and assertions.
population.id String Optional Immutable The unique identifier for the population. Set this property during group creation only. If set, membership to the group is restricted to a single population. For more information, see Creating groups. Search all groups for a specific population ID with a SCIM filter on GET /environments/{{envID}}/groups.
sourceId String Optional* Immutable *This is required when creating a new external group. For Just In Time (JIT) creation of external groups, it’s set when a user is created or updated with memberOfExternalGroups[].sourceId set. See the Users data model for more information. Groups that are provisioned set this property when the groups are created. Groups can be filtered by sourceId.
sourceType String Optional* Immutable *This is required when creating a new external group. This is set during user create or update operations by specifying memberOfExternalGroups[].sourceType. Currently, this can be only “GATEWAY” or “IDP”. See the Users data model for more information.
totalMemberCounts Object Optional Immutable An object containing a users (int) property. This property lists the total number of users added to the group. You must use GET /environments/{{envID}}/groups with the include=totalMemberCounts query parameter to retrieve this property. This property is not returned with a list of groups.
type String Optional Immutable Defines the relationship of nested group membership: DIRECT or INDIRECT.
userFilter String Optional Mutable A SCIM filter that determines which users are dynamically added to the group. Can only be used to add members of non-admin groups. For more information, see Adding users to a group and Removing users from a group.

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Service Event
groups GROUP.CREATED
groups GROUP.UPDATED
groups GROUP.DELETED
groups MEMBER_OF_GROUP.CREATED
groups MEMBER_OF_GROUP.DELETED
groups GROUP.NESTING_UPDATE
user MEMBER_OF_GROUP.CREATED
user MEMBER_OF_GROUP.DELETED

Groups response codes {#groups-response-codes}

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.