Activity - Configure access to PingOne services using scopes


Access PingOne services through scopes

The scopes specified in an authorization request identify the resources that the client application or end user can access. The PingOne platform includes administrator, user, and openid scopes that grant access to PingOne resources.

Administrator scopes are identified by the env portion of the scope name (for example, p1:read:env:population). The requested resource must be in the same environment as the application’s environment.

Self scopes are identified by the self portion of the scope name (for example, p1:reset:self:userPassword). 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.

Openid scopes are user scopes that provide specific user claims allowed in an id_token or in a userinfo authorization request.

PingOne platform scopes

The PingOne platform supports the following scope types: an environment scope, identified by the env portion of the scope name, and a user scope, identified by the self portion of the scope name.

PingOne administrator scopes

Environment scopes can be thought of as administrator or privileged application scopes. These scopes are used in a client_credentials grant type for non-interactive applications. For example, the p1:read:env:population scope, when included in an authorization request, generates access tokens that enable read access privileges to populations resources. The following sample shows a client_credentials authorization request with administrator scopes to create and read populations.

curl --request POST \
 --url 'https://auth.pingone.com/{environmentID}/as/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --user 'client_id:client_secret' \
 --data 'scope=p1:create:env:population p1:read:env:population&grant_type=client_credentials'

Tokens generated from this request give administrators the ability to create populations and retrieve population resource data.

PingOne user scopes

Self scopes can be thought of as user scopes that provide privileges to specific actions so that users can interact with their own profile data. An example of a commonly used self scope is p1:reset:self:userPassword, which allows users to reset their own password.

Self scopes are used with authorization_code or implicit grant types for web, native, or single-page applications. The p1:reset:self:userPassword scope, when included in an authorization request, generates access tokens that give users the permission to run the password reset action on their own user profile. The following sample shows an authorization_code authorization request that includes the self 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:self:userPassword&acr_values=Single_Factor'

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

OpenId Connect scopes

When an application’s protocol attribute is set to OPENID_CONNECT, standard OpenID Connect scopes control the user claims that are included in the ID token or an access token.

PingOne supports the following OpenId Connect scopes:

  • openid

    A required scope that tells the authorization server of an incoming OpenID Connect request.

  • profile

    An optional scope that provides access to the user’s default profile claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.

  • email

    An optional scope that provides access to the user’s email claims: email and email_verified.

  • address

    An optional scope that provides access to the user’s address claims: countryCode, locality, postalCode, region, and streetAddress.

  • phone

    An optional scope that provides access to the user’s phone claims: phone_numberand phone_number_verified.

Note: OpenId Connect scopes can be included in an access token along with scopes from another resource.

Use the openid scope to authenticate users only

An OpenID Connect authentication request that specifies only the openid scope returns an access token that does not enable access to any PingOne services. This type of request is used with an id_token response type to authenticate users only, with no additional user claims encoded in the token. The following sample shows an implicit authorization request that returns an id_token, which cannot be used to access PingOne APIs.

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

Note: You must include openid in your requested scopes when acquiring an access token through the implicit or authentication_code flows, particularly 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.

PingOne platform scopes and endpoint operations

The following table shows the administrator and user scopes for the specified PingOne API endpoint operation.

Endpoint operation Admin scope User scope
GET /environments/{environmentId}/applications p1:read:env:application
GET /environments/{environmentId}/applications/{id} p1:read:env:application
GET /environments/{environmentId}/activities p1:read:env:activity
GET /environments/{environmentId}/activities/{activityId} p1:read:env:activity
PUT /environments/{environmentId}/branding p1:update:env:branding
DELETE /environments/{environmentId}/branding p1:delete:env:branding
GET /environments/{environmentId}/users/{userId}/devices p1:read:env:device p1:read:self:device
POST /environments/{environmentId}/users/{userId}/devices p1:create:env:device p1:create:self:device
GET /environments/{environmentId}/users/{userId}/devices/{deviceId} p1:read:env:device p1:read:self:device
POST /environments/{environmentId}/users/{userId}/devices/{deviceId} p1:update:env:device p1:update:self:device
DELETE /environments/{environmentId}/users/{userId}/devices/{deviceId} p1:delete:env:device p1:delete:self:device
GET /environments p1:read:env:environment
GET /environments/{id} p1:read:env:environment
POST /environments/{envId}/images p1:create:env:image
GET /environments/{envId}/images/{imageId} p1:read:env:image
DELETE /environments/{envId}/images/{imageId} p1:delete:env:image
GET /organizations p1:read:org:organization
GET /organizations/{id} p1:read:org:organization
GET /organizations/{id}/environments p1:read:env:environment
GET /environments/{environmentId}/users/{userId}/password p1:read:env:userPassword
POST /environments/{environmentId}/users/{userId}/password p1:validate:env:userPassword p1:validate:self:userPassword
PUT /environments/{environmentId}/users/{userId}/password p1:reset:env:userPassword p1:reset:self:userPassword, p1:set:env:userPassword
GET /environments/{environmentId}/passwordPolicies p1:read:env:passwordPolicy
GET /environments/{environmentId}/passwordPolicies/{policyId} p1:read:env:passwordPolicy
PUT /environments/{environmentId}/passwordPolicies/{policyId} p1:update:env:passwordPolicy
GET /environments/{environmentId}/populations p1:read:env:population
POST /environments/{environmentId}/populations p1:create:env:population
GET /environments/{environmentId}/populations/{populationId} p1:read:env:population
PUT /environments/{environmentId}/populations/{populationId} p1:update:env:population
DELETE /environments/{environmentId}/populations/{populationId} p1:delete:env:population
GET /environments/{envId}/resources p1:read:env:resource
GET /environments/{envId}/resources/{id} p1:read:env:resource
GET /environments/{environmentId}/schemas p1:read:env:schema
GET /environments/{environmentId}/schemas/{schemaId} p1:read:env:schema
GET /environments/{environmentId}/schemas/{schemaId}/attributes p1:read:env:schema
POST /environments/{environmentId}/schemas/{schemaId}/attributes p1:update:env:schema
GET /environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId} p1:read:env:schema
PUT /environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId} p1:update:env:schema
DELETE /environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId} p1:update:env:schema
PATCH /environments/{environmentId}/schemas/{schemaId}/attributes/{attributeId} p1:update:env:schema
GET /environments/{envId}/resources/{resId}/scopes p1:read:env:scope
GET /environments/{envId}/resources/{resId}/scopes/{id} p1:read:env:scope
GET /environments/{envId}/scopes p1:read:env:scope
GET /environments/{environmentId}/signOnPolicies p1:read:env:signOnPolicy
GET /environments/{environmentId}/signOnPolicies/{policyId} p1:read:env:signOnPolicy
GET /environments/{environmentId}/signOnPolicies/{policyId}/actions p1:read:env:signOnPolicy
GET /environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId} p1:read:env:signOnPolicy
PUT /environments/{environmentId}/signOnPolicies/{policyId}/actions/{actionId} p1:update:env:signOnPolicy
GET /environments/{environmentId}/userActivities p1:read:env:activity
GET /environments/{environmentId}/users p1:read:env:user
POST /environments/{environmentId}/users p1:create:env:user p1:import:env:user
GET /environments/{environmentId}/users/{userId} p1:read:env:user p1:read:self:user
PUT /environments/{environmentId}/users/{userId} p1:update:env:user p1:update:self:user
DELETE /environments/{environmentId}/users/{userId} p1:delete:env:user
PATCH /environments/{environmentId}/users/{userId} p1:update:env:user p1:update:self:user
GET /environments/{environmentId}/users/{userId}/enabled p1:read:env:user
PUT /environments/{environmentId}/users/{userId}/enabled p1:update:env:userEnabled
GET /environments/{environmentId}/users/{userId}/mfaEnabled p1:read:env:user
PUT /environments/{environmentId}/users/{userId}/mfaEnabled p1:update:env:userMfaEnabled p1:update:self:userMfaEnabled
GET /environments/{environmentId}/users/{userId}/population p1:read:env:population
PUT /environments/{environmentId}/users/{userId}/population p1:update:env:population