--- title: Scopes and scope management description: OAuth allows you to constrain the privileges associated with an access token, and scopes allow you to define the privileges requested and granted. component: pingfederate version: 13.0 page_id: pingfederate:administrators_reference_guide:pf_scopes_and_scope_management canonical_url: https://docs.pingidentity.com/pingfederate/13.0/administrators_reference_guide/pf_scopes_and_scope_management.html revdate: April 30, 2026 section_ids: static-scopes-versus-dynamic-scopes: Static scopes versus dynamic scopes scope-groups: Scope groups scope-group-expansion: Scope group expansion common-scopes-and-exclusive-scopes: Common scopes and exclusive scopes openid-connect: OpenID Connect per-client-scope-management: Per-client scope management section_N10197_N1002A_N10001: Dynamic scopes dynamic-scope-evaluation: Dynamic scope evaluation example: Example dynamic-scope-evaluation-and-per-client-scope-management: Dynamic scope evaluation and per-client scope management example-2: Example section_N10752_N1002A_N10001: Description for scopes and scope groups dynamic-scopes-and-consent-user-interface: Dynamic scopes and consent user interface coordinating-with-developers: Coordinating with developers related-links: Related links --- # Scopes and scope management OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* allows you to constrain the privileges associated with an access token *(tooltip: \
\

A data object by which a client authenticates to a resource server and lays claim to authorizations for accessing particular resources.\

\
)*, and scopes allow you to define the privileges requested and granted. PingFederate doesn't limit the number of scopes you can create, but large numbers of scopes can affect performance. ## Static scopes versus dynamic scopes 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`. ## Scope groups For ease of management and subsequent client interactions, PingFederate can 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. ## Scope group expansion 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) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)*-based access tokens or token introspection responses by default. You can optionally enable scope group expansion per access token management instance. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Regardless of whether you choose to expand scope groups, the **Request for Approval** window always presents the description of the requested scope groups, if any. | ## Common scopes and exclusive scopes PingFederate has the flexibility to manage common and exclusive scopes and scope groups. * Common scopes and scope groups Common scopes and scope groups are optional. If defined, they are available to all clients by default. As needed, you can restrict individual clients to a subset of common scopes or scope groups in their configurations. Clients created via the Dynamic Client Registration protocol can also be restricted to a subset of common scopes or scope groups based on the configuration on the **Scope Constraints** tab in **System > OAuth Settings > Client Settings**. The **Scope Constraints** configuration is shared across all clients registered through dynamic client registration. If a certain client requires a different set of common scopes or scope groups, modify the client configuration by using the administrative console, the administrative API, or the OAuth Client Management Service after the client has been created. * Exclusive scopes and scope groups Exclusive scopes and scope groups are optional. If defined, they are restricted from all clients by default. As needed, you can configure individual clients to allow a subset of exclusive scopes or scope groups in their configurations. Clients created with the Dynamic Client Registration protocol can also be configured to allow a subset of exclusive scopes or scope groups based on the **Scope Constraints** tab on the **System > OAuth Settings > Client Settings** window. The **Scope Constraints** configuration is shared across all clients registered via dynamic client registration. If a certain client requires a different set of exclusive scopes or scope groups, modify the client configuration by using the administrative console, the administrative API, or the OAuth Client Management Service after the client has been created. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | A scope or scope group is either a common scope or group, or an exclusive scope or group. Duplicate scopes and scope groups are not allowed. Scope and scope group values are case-sensitive. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Create scopes that are intended for the majority of clients as common scopes. Create scopes that should be limited to the minority of clients as exclusive scopes. | ## OpenID Connect If one or more clients support the OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* standard, add the following scopes to request specific sets of claims from the OpenID Provider: * `openid` * `address` * `email` * `phone` * `profile` | | | | - | ------------------------------------------------------------------------------ | | | If most clients are allowed to use these scopes, create them as common scopes. | ## Per-client scope management You can manage scope access on a client-to-client basis. The client settings are **Restrict Common Scopes** and **Exclusive Scopes**. * Restrict Common Scopes This setting determines whether all common scopes and scope groups should be made available to the client, or only a select few. When selected, the administrative console displays a list of existing common scopes and scope groups. Choose the common scopes and scope groups that are intended for the client. The rest, as well as any future common scopes and scope groups, become invalid for the client. If the client tries to use such scope or scope group, it will receive an `invalid_scope` error message from PingFederate. When cleared, all existing and future common scopes and scope groups are available to the client. This is the default behavior. * Exclusive Scopes This setting determines whether any exclusive scopes and exclusive scope groups should be made available to the client. When selected, the administrative console displays a list of existing exclusive scopes and scope groups. Choose the exclusive scopes and scope groups that are intended for the client. The rest, as well as any future exclusive scopes and scope groups, become invalid for the client. If the client tries to use such scope or scope group, it will receive an `invalid_scope` error message from PingFederate. When cleared, no exclusive scopes and scope groups are available to the client. This is the default behavior. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Both settings impact dynamic scope evaluation. Learn more in [Dynamic scope evaluation and per-client scope management](#dynamic-scope-evaluation-and-per-client-scope-management). | ## Dynamic 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: * A prefix followed by a wildcard, for example: `prefixTextValue*` * A wildcard followed by a suffix, for example: `*suffixTextValue` * A wildcard placed between a prefix and a suffix, for example: `prefixTextValue*suffixTextValue` 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. ## Dynamic scope evaluation 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. ## Example For example, you add the following dynamic scopes: | Common Scopes | Exclusive Scopes | | ------------- | --------------------- | | `*123` | `zSomeExclusiveScope` | | `*12345` | | | `a*c#123` | | | `ab*#123` | | | `xy*123` | | | `xy*` | | 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: * `xy#1` * `xy#12` * `xy#123` * `xy#1234` * `xy#12345` * `xy#123456` * `xyz` * `z123` * `z12345` * `abc#123` | Requested scope | Matched dynamic scope | Variable component from the requested scope | | --------------- | --------------------- | ------------------------------------------- | | `xy#1` | `xy*` | `#1` | | `xy#12` | `xy*` | `#12` | | `xy#123` | `xy*123` | `#` | | `xy#1234` | `xy*` | `#1234` | | `xy#12345` | `*12345` | `xy#` | | `xy#123456` | `xy*` | `#123456` | | `xyz` | `xy*` | `z` | | `z123` | `*123` | `z` | | `z12345` | `*12345` | `z` | | `abc#123` | `ab*#123` | `b` | 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. | Requested scope | Matched dynamic scope | Variable component from the requested scope | | --------------- | --------------------- | ------------------------------------------- | | `xyQ123` | `xy*123` | `Q` | | `xy*Q123` | `xy*123` | `*Q` | | `xyQ*123` | `xy*123` | `Q*` | | `xy**Q*123` | `xy*123` | `*Q` | If the client sends an authorization request with a requested scope of `xy*123`, it will receive an `invalid_scope` error from PingFederate. ## Dynamic scope evaluation and per-client scope management 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 checkbox 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 checkbox 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. ## Example For example, you update your previous sample scope configuration as in the following table. | Common Scopes | Exclusive Scopes | | ------------- | --------------------- | | `*123` | `xy*123` | | `*12345` | `zSomeExclusiveScope` | | `a*c#123` | | | `ab*#123` | | | `xy*` | | The following table describes the results when the client sends an authorization request with a requested scope of `xy#123`. | Per-client scope management settings | Result | Variable component from the requested scope | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | **Restrict Common Scopes**- Not selected.**Exclusive Scopes**- Not selected. | PingFederate matches the requested scope of `xy#123` to the common dynamic scope of `*123`.The exclusive dynamic scope of `xy*123` is not taken into consideration because the **Exclusive Scopes** checkbox is not selected. PingFederate does not consider any exclusive scopes and scope groups as eligible candidates in this scenario. | `xy#` | | **Restrict Common Scopes**- Not selected.**Exclusive Scopes**- Selected. * `zSomeExclusiveScope` is selected.No other exclusive scope is selected. | PingFederate returns an `invalid_scope` error message, because the exclusive dynamic scope of `xy*123` is not allowed based on the **Exclusive Scopes** configuration. | Not applicable. | | **Restrict Common Scopes**- Not selected.**Exclusive Scopes**- Selected. * `xy*123` is selected.It does not matter if any other exclusive scope is selected. | PingFederate matches the requested scope of `xy#123` to the exclusive dynamic scope of `xy*123`. | `#` | | **Restrict Common Scopes**- Selected. * `xy*` is selectedNo other common scope is selected.**Exclusive Scopes**- Not selected. | PingFederate returns an `invalid_scope` error message, because the common dynamic scope of `*123` is not allowed based on the **Restrict Common Scopes** configuration.The exclusive dynamic scope of `xy*123` is not taken into consideration because the **Exclusive Scopes** checkbox is not selected. PingFederate does not consider any exclusive scopes and scope groups as eligible candidates in this scenario. | Not applicable. | | **Restrict Common Scopes**- Selected. * `*123` is selectedIt does not matter if any other common scope is selected.**Exclusive Scopes**- Selected. * `xy*123` is selected.It does not matter if any other exclusive scope is selected. | PingFederate matches the requested scope of `xy#123` to the exclusive dynamic scope of `xy*123`, because `xy*123` is a better partial match than `*123`. | `#` | ## Description for scopes and scope groups 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 determine the text that appears on the **Request for Approval** window. * Default scope The default scope is the implied permissions when no scope and scope group values are indicated, or in addition to any scope or scope group values. If your organization requires a localized description, enter a unique alias in the **Default Scope Description** field, such as `oauth.approval.page.template.defaultScope`. Insert the same alias with the desired localized text in the applicable language resource files, located in `/pingfederate/server/default/conf/language-packs`. * Static scopes and scope groups You can enter simple descriptions or localize the descriptions by using the PingFederate localization framework. * Dynamic scopes You can enter simple descriptions. You can also use a mix of text and scope-description variables. `${scope}` represents the requested scope, and `${scope-var}` represents the variable component found in the requested scope. Suppose you added a dynamic scope with a pattern of `dynaGet67*10` and a scope description of `${scope} contains $\`. If a client requests a scope value of `dynaGet67eight910`, the resulting scope description is `dynaGet67eight910 contains eight9`. (`eight9` is the variable component found in the requested scope.) If your organization requires a localized description, enter a unique alias in the **Scope Description** field (for example, `oauth.approval.page.template.someDynamicScope`). Then insert the same alias with the desired localized text in the applicable language resource files, located in the `/pingfederate/server/default/conf/language-packs` directory. You may also use scope-description variables as part of the localized text. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Both scope-description variables are intended for dynamic scopes only. When they are used as descriptions for static scopes or scope groups, PingFederate shows them on the **Request for Approval** window. | ## Dynamic scopes and consent user interface 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. ## Coordinating with developers 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 resource server *(tooltip: \
\

In OAuth 2.0, a server that hosts protected resources and can accept and respond to resource requests from clients presenting a valid access token.\

\
)*. Applicable scope or scope group values require coordination with developers that are familiar with the details of the resource server 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. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The OpenID Provider configuration endpoint does not return exclusive static scopes, exclusive scope groups, common dynamic scopes, and exclusive dynamic scopes by default. You can optionally customize the response to include such scopes and scope groups as needed. | ## Related links * [Configuring dynamic client registration settings](help_clientsettingstasklet_oauthdynamicclientregistrationstate.html) * [Configuring scope constraints](help_clientsettingstasklet_oauthdynamicclientregistrationscopeconstraintsstate.html) * [Configuring OAuth clients](pf_configuring_oauth_clients.html) * [Localizing messages for end users](pf_local_message_end_users.html) * [External consent user interface](pf_external_consent_user_interfac.html) * [OpenID Connect Core 1.0 - Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) * [OpenID Provider configuration endpoint](../developers_reference_guide/pf_openid_provider_config_endpoint.html) * [Customizing a configuration endpoint response](pf_customiz_config_endpoint_response.html) * [Introspection endpoint](../developers_reference_guide/pf_introspec_endpoint.html)