Resource Scopes

You can define a custom resource, such as https://api.photos.com that has associated scopes, such as edit:photos, upload:photos, and delete:photos. The POST {{apiPath}}/environments/{{envID}}/resources/{{resourceID}}/scopes endpoint defines a new scope associated with the https://api.photos.com custom resource, which is identified by the {{resourceID}} variable in the request URL. The new custom scope grants actors access to otherwise resources on the https://api.photos.com custom resource server.

The PingOne API is one of two predefined resources in the PingOne platform. The PingOne API resource has several predefined self-management scopes associated with it that grant users access to PingOne resources. The self-management scopes specified in an authorization request, such as p1:update:user or p1:reset:userPassword identify the resources that end user can access to perform self-management actions. For a list of PingOne API self-management scopes, refer to PingOne self-management scopes.

Scopes from the PingOne API resource (https://api.pingone.com), cannot be included in an access token with scopes from another custom resource such as https://api.photos.com. However, you can include the platform’s predefined OpenID Connect resource (openid) scopes in an access token along with scopes from PingOne. For more information about OpenID Connect scopes, refer to OpenID Connect (OIDC) scopes.

With custom resource scopes, the default application configuration allows scopes from one custom resource, with or without the platform’s predefined OpenID Connect resource (openid) scopes in an access token. However, if the appplication configuration sets the requestScopesForMultipleResourcesEnabled OIDC property to true, then the application accepts scopes from multiple custom resources. For example if Resource1 defines scopeR1-a and Resource2 defines scopeR2-a, then an authorize request for an app with requestScopesForMultipleResourcesEnabled enabled supports a scope parameter of:

--data-urlencode 'scope=openid scopeR1-a scopeR2-a'.

For use cases in which an application requests scopes from multiple custom resources, the following settings and attribute mappings must be consistent among custom resources for PingOne to complete the request:

Most PingOne API scopes cannot be modified. However, user scopes such as the p1:read:user and p1:update:user can be modified to add or remove user schema attributes. In addition, PingOne supports custom PingOne access control scopes that use the syntax p1:read:user:{suffix} and p1:update:user:{suffix} for these two platform scopes. These custom PingOne scopes designate a specific set of user schema attributes, which is often a subset of attributes that the user is allowed to read or update. For example, a p1:update:user:email-only scope could remove all other user schema attributes except the user’s email address. A user with this scope could update only their email address. All other visible attributes would not allow modification. For more information, refer to Access services through scopes and roles.

The following authorization request shows a authorization_code grant type, in which the p1:read:user scope is specified, ensuring that this permission is encoded into the returned access token:

You can specify more than one scope (from the same resource or from the openid resource) in the authorization request by adding additional scope names separated by spaces.

The examples that follow show common actions to find and manage resource scope entities. You need the Client Application Developer role to perform operations on resources entities.

For more information about scopes, refer to Configure access through scopes and roles.

If the resource’s type property is OPENID_CONNECT, you can add scopes to the resource that include custom mapped claims. The mappedClaims property in the POST {{apiPath}}/environments/{{envID}}/resources/{{openidResourceID}}/scopes request specifies the IDs of the resource attributes to add to the scope.

For example, the OpenID Connect profile scope includes the following predefined profile claims: name, given_name, family_name, middle_name, nickname, preferred_username, picture, zoneinfo, locale, updated_at, profile, website, gender, and birthdate. If you add the ID for a predefined claim that already exists in the scope, such as given_name, it is ignored in the response. However, if you add the predefined phone_number attribute to the profile scope, the ID for the phone_number attribute is returned in the mappedClaims property in the response.

You can add custom claims to an OpenID Connect scope that you define using the Create Resource Attribute endpoint. The create request can include the idToken and userInfo properties to designate (globally) whether the claim should be added to the ID token and returned by the userinfo endpoint. You can specify that the idToken anduserInfo properties are both true, one can be true and the other false, but both properties cannot be set to false.

Refer to Audit Reporting Events for the events generated.