Activity - Configure access through scopes


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.