PingOne Platform APIs

Custom Admin Roles

A custom admin role is an environment-level resource that consists of a set of permissions that can be edited by administrators. A custom role can be assigned to an individual user, group, worker application, or PingFederate Gateway for a specific jurisdiction (scope). The jurisdiction can be at the organization level, environment level, or population level. The role assignment also specifies the assignee, the actor who is assigned the role for the designated jurisdiction.

Administrators must have the Custom Role Admin permissions to create, update, and delete custom roles. The Org Admin and the Custom Role Admin roles include these permissions.

Custom admin role assignments

Role assignments for custom roles follow these common scenarios:

  1. The admin assigns the custom role to someone in the same environment because they have that custom role.

  2. The admin assigns a custom role to someone in the same environment because the role they have is specified in the canBeAssignedBy attribute of the custom role.

  3. The admin assigns a custom role to someone in a different environment because the role and actor exist in a different environment. This is possible because the admin assigning has scope (jurisdiction) over the different environment through a PingOne role, which is specified in the custom role’s canBeAssignedBy property.

To summarize these scenarios, the actor can assign a custom role to others for a specific jurisdiction only if one or more of the following conditions are true:

  • The actor already has the same role for the jurisdiction or parent jurisdiction.

  • The actor has a role that is specified in the canBeAssignedBy property of the custom role for the jurisdiction or parent jurisdiction.

For additional examples on assigning custom roles, refer to Custom Roles Scenarios In the PingOne Admin Guide.

Custom admin role restrictions

There are additional restrictions for using custom admin roles (these restrictions do not apply to the built-in roles).

  • Custom admin roles are not supported for PingOne Davinci at this time.

  • Custom admin roles can only be assigned at the organization level to users, groups, applications, and gateways in the administrators environment.

  • Custom roles created in any non-administrators environment can only be assigned against resources within that environment (or the entire environment).

Roles and Permissions

Refer to PingOne Role Permissions for the PingOne roles and their permissions.

Refer to PingFederate SSO admin permissions for the applicable PingFederate roles.

Filtering data

The Read All Custom Admin Roles request supports SCIM filtering expressions. The query filter can be appended to the request URL to fine-tune the response data. For example, the following filter returns only the custom roles:

GET {{apiPath}}/environment/{{envID}}/roles?filter=%28type+eq+%22CUSTOM%22%29

These SCIM operators can be applied to the following attributes:

eq (equal to)

Supported attributes: type

Custom administrator roles data model

Property Type Required? Mutable? Description

applicableTo

String[]

Required

Immutable

The scope types to which the role can be applied. Options are ORGANIZATION, ENVIRONMENT, POPULATION, and APPLICATION.

canAssign

Object

Read only

Immutable

A relationship that specifies if an actor is assigned the current custom role for a jurisdiction, then the actor can assign any of this set of roles to another actor for the same jurisdiction or sub-jurisdiction. This capability is dreived from the canBeAssignedBy property.

canBeAssignedBy

Object

Required

Mutable

A relationship that determines whether a user assigned to one of this set of roles for a jurisdiction can assign the current custom role to another user for the same jurisdiction or sub-jurisdiction.

description

String

Optional

Mmutable

The description of the role.

environment.id

String

N/A

Read-only

The environment resource’s unique identifier associated with the resource.

id

String

N/A

Read-only

The resource’s unique identifier.

name

String

Required

Mutable

The role name.

permissions

String

Required

Mutable

The set of permissions assigned to the role.

type

String

N/A

Read only

A value that indicates whether the role is a built-in role or a custom role. Options are PLATFORM and CUSTOM.

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.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.
Related topics