PingFederate Server

Defining scopes

PingFederate manages scopes and scope groups in common and exclusive buckets.

About this task

Common scopes and scope groups are optional. They are available to all clients by default. 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. 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.

You can also create static scopes, static scope groups, and dynamic scopes. Scope groups allow clients to request a "super scope" and optionally downgrade to a subset of it later. 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 can manage scopes, scope groups, and the default scope description from System → OAuth Settings on the Scope Management window. Configuration steps for common and exclusive scopes and scope groups are identical.

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.

Create scopes that are for the majority of clients as common scopes. Create scopes that are for a minority of clients as exclusive scopes. You can organize common or exclusive static scopes into common or exclusive scope groups.

Steps

  1. Go to System → OAuth Settings → Scope Management.

  2. On the Common Scopes or Exclusive Scopes tab, configure any number of common or exclusive static scopes.

    1. Enter a static scope value and a description in the Scope Value and Scope Description fields.

      Scope values are case-sensitive. A requested scope value of email does not match a configured static scope value of Email. Do not use backslashes (\) or double quotation marks (") in the Scope Value field.

      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 more information, see Description for scopes and scope groups.

    2. Click Add.

    3. Repeat to configure additional static scopes. Display order does not matter.

  3. On the Common Scopes or Exclusive Scopes tab, configure any number of common or exclusive dynamic scopes.

    1. Enter a dynamic scope pattern and a description in the Scope Value and Scope Description fields.

      You must use a case-sensitive text value with the asterisk character (*). For supported dynamic scope patterns, see Dynamic Scopes.

      You can enter a simple description, or you can use a mix of text and scope-description variables. For more information, see Description for scopes and scope groups.

      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 or Exclusive Scopes tab, 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.

      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 more information, see Description for scopes and scope groups.

      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. Do not use backslashes (\) or double quotation marks (") in the Scope Group Value field.

    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 or Exclusive Scopes tab, use the Edit, Update, and Cancel buttons to make or undo a change to an existing entry. Use the Delete and Undelete buttons to remove an existing entry or cancel the removal request.

    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. Errors can also 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 tab, enter a description for the default scope.

    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 more information, see Description for scopes and scope groups.

    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.

  7. Click Save.

Result

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

By default, the OpenID Provider configuration endpoint does not return exclusive static scopes, exclusive scope groups, common dynamic scopes, and exclusive dynamic scopes. You can customize the response to include such individual scopes and scope groups.