PingOne Platform APIs

Administrator permissions and role assignments

Unlike user self-service applications, administrator applications use role assignments to determine the actions a user or client can perform. For external API client applications, the access tokens do not use scopes to control access to resources. Instead, the actor’s role assignments determine resource access.

Worker application permissions

Administrator applications that interact with non-self Platform APIs are classified as a WORKER application type. This application type supports only the OPENID_CONNECT protocol. A worker application that uses the client_credentials grant type inherits the same role assignments as the user or application that created the application. These role assignments can be cross-environment, which allows access to APIs for other environments.

Worker applications can use a user-based grant type (implicit or authorization_code). With this configuration, you can assign only OIDC scopes to the application. When getting a token using a user-based grant type, the user’s role assignments are used. When getting a token using the client_credentials grant type, the application’s role assignments are used.

Role assignments determine access to APIs (refer to Application role assignments and User role assignments in the PingOne Platform API Reference. Users and clients cannot create or use clients that have more privileges than the worker application itself. For example, an actor with only the Identity Data Admin role cannot create a worker application that has Environment Admin privileges. Likewise, access to an application’s client secret is restricted based on the accessing user’s or application’s role assignments. If an actor has only the Identity Data Admin role, it is not able to see the client secret. Similar roles can have different privileges, or restrictions, based on the role’s scope. For example, an actor with an Environment Admin role over a single environment cannot access the client secret of an application with Environment Admin privileges over the entire organization.

PingOne roles include a set of permissions that allow access to PingOne resources. For example, the Identity Data Admin role grants access to PingOne resources for these user management actions:

  • Read, create, update, and delete user resources

  • Read, create, update, and delete device management resources

  • Assign identity resources

  • Bulk user import

  • Read, create, update and delete population resources

  • Update user password resources

  • Read user password state resources

  • Read password policy resources

  • Read audit reporting activities resources

  • Read schema resources

The actor (user or client) assigning roles to the application must have the permissions that they are trying to assign. In other words, the requesting user or client must have the same (or broader) role assignments as the target application’s role assignments. This prevents a lesser privileged user (such as a Client Application Developer) from creating a more privileged client_credentials application (such as an Environment Admin).

When retrieving access tokens for WORKER applications, the authorization service checks to make sure the user or client has at least one role assignment. If not, the token request is rejected. If at least one role assignment exists, the authorization service creates a token with no scopes except for the requested OIDC scopes. When accessing platform APIs with this token, it retrieves the actor’s entitlements, which ensures that clients and users can access only the resources that their role assignments allow.

Worker applications and environments

When a worker application with Environment Admin privileges creates a new environment, that application is given Identity Data Admin and Client Application developer role assignments for the new environment. Only the worker application can perform Identity Data Admin operations in that environment (refer to the list of Identity Data Admin actions above). However, the worker application can give the same role assignment to another user or worker application.

Access to a worker application’s client secret requires having a superset of the worker application’s role assignments. Initially, the worker application is granted all of the role assignments of the admin (or worker app) that created it, which gives the admin access to the worker application’s secret (or any other admin with a superset of those role assignments).

However, if the worker application ever gains new role assignments (for example, by creating a new environment and being granted role assignments to cover the new environment), then this may mean that the admin who originally created the worker application can no longer access its secret.

One way to address this condition is to make sure that if an environment is created by a worker application, then that worker application should grant the newly received role assignments to any admins who need access to the worker application’s secret.