Scopes and scope management

As an authorization server, PingFederate supports the concepts of static scopes and dynamic scopes. To define a static scope, use a text value such as read_bank_account. To define a dynamic scope, use a text value with a variable component represented by a wildcard, such as read_bank_account_txn:*. As illustrated, dynamic scopes allow clients to request authorization using scope values with a variable component from one request to another.

For example, with a requested scope of read_bank_account_txn:1234, PingFederate can match the requested scope to the dynamic scope pattern of read_bank_account_txn:* and can issue an access token with the requested scope of read_bank_account_txn:1234.

For ease of management and subsequent client interactions, PingFederate has the capability to create multiple groups of static scopes. A client can reference a scope group in applicable OAuth 2.0 protocol interactions. When authorized, clients can subsequently request access tokens with fewer permissions by presenting to the token endpoint a refresh token and the desired subset of scopes.

A scope group must contain at least one static scope, and multiple sub scopes are allowed. Multiple scope groups can share the same set of sub scopes. However, no scope group can contain another scope group or the default scope.

An authorization request can include one or more scope values. If the request is authorized, PingFederate issues an access token to the client. When the client brings the access token to a resource server to access protected resources, the resource server may contact PingFederate to validate the access tokens. Scope groups are not expanded in JSON web token (JWT)-based access tokens or token introspection responses by default. You can optionally enable scope group expansion per access token management instance.

PingFederate has the flexibility to manage common and exclusive scopes and scope groups.

If one or more clients support the OpenID Connect standard, add the following scopes for the purpose of requesting specific sets of claims from the OpenID Provider:

You can manage scope access on a client-to-client basis. The client settings are Restrict Common Scopes and Exclusive Scopes.

A dynamic scope is defined by using a text value with a variable component represented by an asterisk (*). PingFederate supports three dynamic scope patterns:

PingFederate only allows one variable component. Backslashes (\) and double quotation marks (") are not allowed in the prefix or the suffix.Multiple dynamic scopes are supported in conjunction with any number of static scopes and scope groups.

When a client sends an authorization or token request with a list of desired scopes, PingFederate validates the requested scopes against its configurations.

If PingFederate finds no match for the requested scopes, it returns an invalid_scope error message to the client.

If PingFederate matches the requested scope to an existing static scope or scope group, it checks the client configuration to determine whether such static scope or scope group is valid for the client. If it is, PingFederate proceeds further. For example, if PingFederate is configured to handle consent approval, it presents to the user the Request for Approval window with the description associated with the matched static scope or scope group. If PingFederate should issue an access token, the token is issued with the requested scope. If such static scope or scope group is not valid for the client, PingFederate returns an invalid_scope error message to the client.

If PingFederate finds no exact match but finds a partial match to one or more dynamic scopes, the partial match with the highest number of matched characters in the prefix, suffix, or both is the matched dynamic scope. In the event that two partial matches tie, the partial match with the highest number of characters matched in the prefix is the matched dynamic scope. PingFederate then checks the client configuration to determine whether such dynamic scope is valid for the client. If it is, PingFederate proceeds further. Otherwise, PingFederate returns an invalid_scope error message to the client. If PingFederate should issue an access token, the token is issued with the requested scope, not the matched dynamic scope pattern.

For example, you add the following dynamic scopes:

You also add a client without any common scope restrictions. This client can access all common scopes.

The following table illustrates the expected results when the client sends an authorization request with these scopes:

The minimum length of the variable component is one character. If the variable component contains two or more characters, it may also contain the asterisk character as well. Given the same common dynamic scopes and the same client configuration, requested scopes of xyQ123, xy*Q123, xyQ*123, xy**Q*123 will be matched as in the following table.

If the client sends an authorization request with a requested scope of xy*123, it will receive an invalid_scope error from PingFederate.

Depending on the configured dynamic scope patterns and if they are defined as common or exclusive dynamic scopes, per-client scope management settings can impact the results of scope evaluation.

The Restrict Common Scopes setting determines whether all common scopes and scope groups are available to the client, or only a select few. Use this setting to restrict certain common dynamic scopes.

The Exclusive Scopes setting determines whether any exclusive scopes and scope groups are available to the client. When this check box is not selected, PingFederate does not consider any exclusive dynamic scopes or any exclusive static scopes and scope groups when trying to match a requested scope against a list of configured scopes and scope groups. When the check box is selected, all exclusive scopes and scope groups are considered. If PingFederate matches a requested scope to an exclusive dynamic scope and such scope is not available to the client, PingFederate returns an invalid_scope error message to the client. This remains true for a lesser partial match to an available common dynamic scope.

For example, you update your previous sample scope configuration as in the following table.

The following table describes the results when the client sends an authorization request with a requested scope of xy#123.

When defining a scope or a scope group, enter a value and a description for the scope or the scope group. This description helps you identify the purpose of the scope or scope group at a later time. If PingFederate is configured to handle consent approval, the Scope Description, Scope Group Description, and Default Scope Description fields determines the text that appears on the Request for Approval window.

The default consent approval process and user interface in PingFederate are capable of handling dynamic scopes and their scope descriptions. While the scope description and the optional scope-description variables provide the basic controls to describe a given scope, PingFederate also supports the use of an external web application to prompt for authorization consent. This allows you to retrieve additional information specific to the users and apply application-specific scope-processing logic.

Regardless of whether a static scope, a scope group, or a dynamic scope is created as common or exclusive, a scope or a scope group represents access to a resource or API on the RS. Applicable scope or scope group values require coordination with developers that are familiar with the details of the RS OAuth implementation. For clients supporting the OpenID Connect protocol, you can direct the developers to your PingFederate OpenID Provider configuration endpoint to retrieve a list of common scopes and common scope groups.