Activity - Access services


Self-service platform API resources and scopes

The resources described in the following section are applicable only to users. They are granted on authorization_code and implicit authorization flows.

PingOne self-management scopes

The self-management scopes specified in an authorization request identify the resources that end user can access to perform self-management actions. These scopes use the following naming format to represent a self-management permission:

p1:<permission-action>:<permission-classifier>

For example, the self-management scope to read user information is p1:read:user.

The PingOne platform includes the following self-management scopes:

Scope Description
p1:read:user Users can retrieve their own user identity and all attributes.
p1:update:user Users can modify the attributes of their own user identity.
p1:update:userMfaEnabled Users can enable and disable multi-factor authentication for their own user identity.
p1:create:device Users can create multi-factor authentication devices for their own user identity.
p1:read:device Users can retrieve multi-factor authentication devices for their own user identity.
p1:update:device Users can update multi-factor authentication devices for their own user identity.
p1:delete:device Users can delete multi-factor authentication devices for their own user identity.
p1:read:userPassword Users can retrieve the password state for their own user identity.
p1:reset:userPassword Users can reset the password for their own user identity.
p1:validate:userPassword Users can validate the password for their own user identity.

Note: The requested user resource or user’s sub-resources must be the same as the user identified by the sub claim (the userId) in the access token. The requested resource must be in the same environment as the environment identified by the env claim in the access token.

User scopes enable self-service actions

User scopes provide privileges to specific actions, giving end users the ability to interact with their own profile data. An example of a commonly used user scope is p1:reset:userPassword. This scope, when included in an authorization request, generates access tokens that give users permission to run the self-service password reset action.

The following sample shows an authorization_code request that includes the reset password scope.

curl --request GET \
  --url 'https://auth.pingone.com/{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri=https://example.com&scope=p1:reset:userPassword'

Note: For more information about authorization requests, see Application authorization and authentication.

OpenID Connect (OIDC) scopes

Standard OpenID Connect scopes control which user claims are included in an id_token or in a userinfo response. Unlike other resources, scopes from this resource can be included in an access token along with scopes from another resource.

PingOne supports the following OIDC scopes:

Scope Description
profile This scope value requests access to the end-user’s default profile claims, which are: name, family_name, given_name, middle_name, preferred_username, picture, zoneinfo, locale, and updated_at.
email This scope value requests access to the email claim.
address This scope value request access to the address claim.
phone This scope value requests access to the phone_number claim.

Note: For id_token authorization requests, the openid scope is a required scope that tells the authorization server of an incoming OpenID Connect request.

OIDC scopes for user information

The following sample shows an implicit authorization request with an id_token response type. The scope parameter specifies the required openid scope. It also specifies the optional profile scope to provide access to the end-user’s default profile claims.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/as/authorize?client_id={clientId}&redirect_uri=https://example.com&response_type=id_token&scope=openid profile'

Note: You must include openid in your requested scopes if you want to use the access token to call the /userinfo endpoint and get a sub attribute in the response. Also, you can include additional OpenID Connect scopes in the scope parameter of the initial authorization request to add more user claims in the id_token and return more information about the user in the /userinfo response.

For more information about retrieving scopes for a specified resource, see Get scopes for a resource.

Administrator permissions and role assignments

Unlike user self-service applications, administrator applications use role assignments to determine the actions a user or client has access to 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.

Note: Worker applications can use a user-based grant type (implicit or authorization_code). This configuration lets you 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 (see Application role assignments and User role assignments). Users and clients cannot create or use clients that have more privileges than the worker application itself. For example, an actor with 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 a client has the Environment Admin role, an Identity Admin is not able to see the client secret.

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 (see the list of Identity Data Admin actions above). However, the worker application can give the same role assignment to another user or worker application. For more information about roles and role assignments, see Roles, Application role assignments, and User role assignments.