PingOne Platform APIs

Groups

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.

Groups permissions

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

  • Create, read, update, and delete groups

  • Add users to groups

  • Delete users from groups

  • Read group memberships

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

Creating groups

Use POST {{apiPath}}/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 {{apiPath}}/environments/{{envID}}/groups. The population.id property is read-only after it is initially set and can be set in POST {{apiPath}}/environments/{{envID}}/groups only.

Once a group is created, the following conditions apply:

You cannot move the group:

  • From one population to another

  • From a population to an environment

  • From an environment to a population

If a user’s population changes, they are also removed from any group that contains them for this population.

Learn more about creating groups in Creating a group, in the PingOne Admin Guide. Learn more about assigning users to groups in Group Membership.

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.

  • 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
[source]

  • You cannot nest an environment-level group inside a population-level group.

  • You cannot nest groups with admin roles assigned.

Learn more about nested groups in Nested groups, in the PingOne Admin Guide.

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

  • 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

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

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

Learn more about searching for groups in Searching for groups, in the PingOne Admin Guide.

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:

  • 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)

For more information refer to Paging, ordering, and filtering collections.

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

Use Cases

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

Mutable

For Just In Time (JIT) creation of external groups, it’s set when a user is created or updated with memberOfExternalGroups[].name. Refer to 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 {{apiPath}}/environments/{{envID}}/users/{{userID}}/memberOfGroups. Since these members were explicitly added to the group, they can be removed from the group with DELETE {{apiPath}}/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 property to synchronize 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 {{apiPath}}/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 {{apiPath}}/environments/{{envID}}/groups. Retrieve all the group IDs associated with a user with GET {{apiPath}}/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 {{apiPath}}/environments/{{envID}}/groups. Retrieve all the group names associated with a user with GET {{apiPath}}/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, refer to Creating groups. Search all groups for a specific population ID with a SCIM filter on GET {{apiPath}}/environments/{{envID}}/groups.

sourceId

String

Optional

Immutable

For Just In Time (JIT) creation of external groups, it’s set when a user is created or updated with memberOfExternalGroups[].sourceId. Refer to 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

For Just In Time (JIT) creation of external groups, it’s set when a user is created or updated with memberOfExternalGroups[].sourceType. Currently, this can be only "GATEWAY" or "IDP". Refer to 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 {{apiPath}}/environments/{{envID}}/groups/{{groupID}} 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, refer to Group Membership.

Group events generated

Refer to Audit Reporting Events for the events generated.

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.
Related topics