OAuth provides a mechanism to constrain the privileges associated with an access token, whereas scopes provide a way to more specifically define the privileges requested and granted. Generally, a client specifies the desired scopes when sending an authorization request to the authorization server. If the users (the resource owner) approves, the authorization server issues an access token with such scopes.
Static scopes versus dynamic scopes
As an authorization server, PingFederate
supports the concepts of static scopes and dynamic scopes. A static scope is defined by
using a text value; for example, read_bank_account. A dynamic scope is
defined by using a text value with a variable component represented by a wildcard; for
example, read_bank_account_txn:*. As illustrated, dynamic scopes address
the business requirement where clients want to request authorization by using scope values
with a variable component from one request to another. For instance, when a client sends an authorization request (or a token request if
authorization is not required) with a requested scope of
read_bank_account_txn:1234, because PingFederate is able to match the
requested scope to the dynamic scope pattern of read_bank_account_txn:*,
PingFederate can issue an access token with the requested scope
(read_bank_account_txn:1234).
Scope groups
For ease of management and subsequent client interactions, PingFederate provides the capability to create multiple groups of static scopes. Essentially, a scope group is a super scope that a client can reference in applicable OAuth 2.0 protocol interactions. Once authorized, clients may 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; multiple sub scopes are allowed. As needed, 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
When a client submits an authorization request, it can optionally include one or more scope values. If the request is authorized, PingFederate issues an access token to the client. As the client brings the access token to a resource server (RS) to access protected resources, the RS may contact PingFederate to validate the access tokens. Scope groups are not expanded in JWT-based access tokens or token introspection responses by default. As needed, 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 page always presents the description of the requested scope groups (if any).
Common scopes versus exclusive scopes
Furthermore, PingFederate provides the flexibility to manage scopes and scope groups in two buckets: common versus exclusive.
- 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.
- 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.
A scope (or a scope group) is either a common scope (or a common scope group) or an exclusive scope (or an exclusive group). Duplicate scopes and scope groups are not allowed. In addition, scope and scope group values are case-sensitive.
For scopes that are intended for the majority of clients, create them as common scopes. For scopes that should be limited to the minority of clients, create them as exclusive scopes.
OpenID Connect
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:
- openid
- address
- 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 controls whether all existing common scopes and scope groups (and those created in the future) or only the select few should be made available to the client.
- Exclusive Scopes
- This setting controls whether any exclusive scopes and scope groups should be made available to the client.
Both settings impact dynamic scope evaluation. For detailed information, refer to the Dynamic scope evaluation and per-client scope management section, found later in this topic.
Dynamic scopes
A dynamic scope is defined by using a text value with a variable component represented by a
wildcard, the asterisk character (*). 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
Only one variable component is permitted. Additionally, backslashes
(\) and double quotation marks (") are not
allowed in neither the prefix nor 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 request (or a token request if authorization is not required) 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 page with the description associated with the matched static scope or
scope group. At the end, 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 a partial match to one or more dynamic scopes, the
partial match with the highest number of matched characters in the prefix, the 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. Note that if PingFederate should
issue an access token, the token is issued with the requested scope, not the matched dynamic
scope pattern.
For example, suppose you added the following dynamic scopes:
| Common Scopes | Exclusive Scopes |
|---|---|
*123
|
zSomeExclusiveScope
|
*12345
|
|
a*c#123
|
|
ab*#123
|
|
xy*123
|
|
xy*
|
You also added a client without any common scope restrictions. (In other words, 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. For
instance, 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 follows:
| 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 whether 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 controls whether all existing common scopes and scope groups (and those created in the future) or only the select few should be made available to the client. You can use this setting to restrict certain common dynamic scopes so that they become invalid for a client.
The Exclusive Scopes setting controls whether any exclusive scopes and
scope groups should be made 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, for that matter) as candidates when it tries 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 become eligible candidates. If PingFederate matches a requested scope to an
exclusive dynamic scope, where such scope is not chosen to be available to the client,
PingFederate returns an invalid_scope error message to the client. This remains
true even if a lesser partial match to an available common dynamic scope.
For instance, suppose you updated your previous sample scope configuration as follows:
| Common Scopes | Exclusive Scopes |
|---|---|
*123
|
xy*123
|
*12345
|
zSomeExclusiveScope
|
a*c#123
|
|
ab*#123
|
|
xy*
|
The following table illustrates the expected results when the client sends an authorization
request with a requested scope of xy#123 based on various client configuration
scenarios.
| Per-client scope management settings | Result | Variable component from the requested scope |
|---|---|---|
Restrict Common Scopes
Exclusive Scopes
|
PingFederate matches the requested scope of xy#123 to
the common dynamic scope of *123. Note that the
exclusive dynamic scope of |
xy#
|
Restrict Common Scopes
Exclusive Scopes
|
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
Exclusive Scopes
|
PingFederate matches the requested scope of xy#123 to
the exclusive dynamic scope of xy*123. |
#
|
Restrict Common Scopes
Exclusive Scopes
|
PingFederate returns an invalid_scope error message
because the common dynamic scope of *123 is not allowed
based on the Restrict Common Scopes
configuration.Note that the exclusive dynamic scope of
|
Not applicable. |
Restrict Common Scopes
Exclusive Scopes
|
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, you enter a value and a description for the scope or the scope group. The 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 control the text appears on the Request for Approval page.
- Default scope
- The default scope is the permissions implied when no scope and scope group values are indicated or in addition to any scope or scope group values.
- Static scopes and scope groups
- Similar to the default scope, you may enter simple descriptions or localize the descriptions by using the PingFederate localization framework.
- Dynamic scopes
- You may enter simple descriptions. You may also use a mix of text and scope-description variables. ${scope} represents the requested scope, whereas ${scope-var} represents the variable component found in the requested scope.
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 approach opens up the opportunity 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 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 may direct the developers to your PingFederate's 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. As needed, you can optionally customize the response to include such scopes and scope groups.