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 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.
As opposed to internal PingOne groups, there are a few things external groups cannot do:
Errors will occur if:
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.
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.
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.
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.
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.
If you nest Group B inside of Group A, then users in Group B will now have access to App1 and App2, and Group A will still only have access to App1.
If you nest Group C into Group B, then Group C members will inherit access to App1 (via the nested relationship of Group B to Group A), inherit access to App2 (via the nested relationship of Group C to Group B), and will retain access to App3.
Group A - App1
Group B - App1 & App2
Group C - App1, App2, App3
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.
If you nest Group D in Group B, Group D inherits access to Group A and Group B apps.
If you nest Group B in Group D, creating a circular reference, then both Group B and Group C inherit 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
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.
Documentation for the following group membership searches can be found under Users/Group Membership:
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:
name
externalId
The SCIM operators eq
(equals), and sw
(starts with) can be used with the group property:
displayName
The SCIM operator eq
(equals) can be used with the following group properties:
id
population.id
sourceId
(only for external groups)You can also use SCIM filters with GET collection requests that return user data. See Users for the user properties and operators supported.
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. |
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 |
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. |