PingFederate provides the flexibility to manage scopes and scope groups in two buckets, common versus exclusive. Common scopes and scope groups are optional. If defined, they are available to all clients. As needed, you can restrict individual clients to a subset of common scopes or scope groups on a client-by-client basis in their client configurations. Exclusive scopes and scope groups are also optional. If defined, they are restricted from all clients by default. However, you can grant individual clients access to one or more exclusive scopes or scope groups in their client configurations. Furthermore, you have the options to create static scopes, static scope groups, and dynamic scopes. Scope groups allows clients to request a super scope and optionally downgrade to a subset of it at a later time. 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 detailed information about scopes, see Scopes and scope management.

You manage scopes, scope groups, and the default scope description using the OAuth Server > Scope Management configuration wizard. Configuration steps for common and exclusive scopes (and scope groups) are identical, with the exception of the configuration screens, which are Common Scopes and Exclusive Scopes.

Note:

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.

Tip:

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. As needed, you may organize common (or exclusive) static scopes into common (or exclusive) scope groups.

  1. Go to the OAuth Server > Scope Management screen.
  2. On the Common Scopes screen (or the Exclusive Scopes screen), configure any number of common (or exclusive) static scopes.
    1. Enter a static scope value and its description under Scope Value and Scope Description.
      Scope Value
      Scope value is case-sensitive. A requested scope value of email does not match a configured static scope value of Email.
      Note:

      Do not use backslashes (\) or double quotation marks (") in the Scope Value field.

      Scope Description
      If PingFederate is configured to handle consent approval and your organization requires a localized description, enter a unique alias in the Scope Description field (for example, oauth.approval.page.template.someScope); then insert the same alias with the desired localized text in the applicable language resource files, located in the <pf_install>/pingfederate/server/default/conf/language-packs directory.
    2. Click Add.
    3. Repeat to define additional static scopes.
      Display order does not matter.
  3. On the Common Scopes screen (or the Exclusive Scopes screen), configure any number of common (or exclusive) dynamic scopes.
    1. Enter a dynamic scope pattern and its description under Scope Value and Scope Description.
      Scope Value
      You must use a case-sensitive text value with 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
      Note:

      Only one variable component is permitted. Additionally, backslashes (\) and double quotation marks (") are not allowed in neither the prefix nor the suffix.

      Scope Description
      You may enter a simple description. 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.
      Suppose you added a dynamic scope with a pattern of dynaGet67*10 and a scope description of ${scope} contains ${scope-var}. 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 <pf_install>/pingfederate/server/default/conf/language-packs directory. You may also use scope-description variables as part of the localized text.
      Note:

      Both scope-description variables are intended for dynamic scopes only. When they are used as description for static scopes or a scope groups, PingFederate show them as is on the Request for Approval page.

      In general, if your organization requires additional information specific to the users or application-specific scope-processing logic, you can configure PingFederate to use an external web application to handle consent approval.

    2. Select the check box under Dynamic.
    3. Click Add.
    4. Repeat to define additional dynamic scopes.
      Display order does not matter.
  4. On the Common Scopes screen (or the Exclusive Scopes screen), configure any number of common (or exclusive) scope groups.
    1. Enter a scope group value and its description under Scope Group Value and Scope Group Description.
      Scope Group Value
      Generally speaking. all scope groups are defined as static scope groups. The partial-matching concept is intended for dynamic scopes only and does not apply to scope groups. Like static scope values, scope group values are case-sensitive as well.
      Note:

      Do not use backslashes (\) or double quotation marks (") in the Scope Group Value field.

      Scope Group Description
      If PingFederate is configured to handle consent approval and your organization requires a localized description, enter a unique alias in the Scope Group Description field (for example, oauth.approval.page.template.someScopeGroup); then insert the same alias with the desired localized text in the applicable language resource files, located in the <pf_install>/pingfederate/server/default/conf/language-packs directory.
    2. Select at least one static scope under Sub Scopes.
      The administrative console filters out dynamic scopes because the scope-grouping capability is reserved for static scopes only.
    3. Click Add.
    4. Repeat to define additional scope groups.

      Display order does not matter.

  5. Optional: On the Common Scopes screen (or the Exclusive Scopes screen), use the Edit, Update, and Cancel workflow to make or undo a change to an existing entry.
    Use the Delete and Undelete workflow to remove an existing entry or cancel the removal request.
    CAUTION:

    Updating or removing a scope or scope group value in production can cause runtime errors when a client request specifies the scope or scope group using the previously defined value. In addition, errors can occur when the requesting client is restricted to a scope or scope group that no longer exists unless the affected client configuration is also updated.

  6. On the Default Scope screen, enter a description for the 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.

    If PingFederate is configured to handle consent approval and your organization requires a localized description, enter a unique alias in the Default Scope Description field (for example, oauth.approval.page.template.defaultScope); then insert the same alias with the desired localized text in the applicable language resource files, located in the <pf_install>/pingfederate/server/default/conf/language-packs directory.

  7. Click Save to keep your configuration.

Scopes and scope groups represent access to resources or APIs on the resource server (RS). 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.

Note:

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 individual scopes and scope groups.