Rate this page

Scopes

A scope is a string that identifies a specific unit of access that may be granted to an OAuth 2 or OpenID Connect client. Scopes must be mutually understood by the client, the authorization/authentication server, and the resource server.

When dealing with user data handled by the Data Governance Broker, a scope is typically bound to a particular resource type and a particular set of attributes, defined by one or more SCIM attribute paths, plus one or more operation type.

For example, when using the Data Governance Broker’s example starter schema, the email scope represents read-only access to the emails attribute of the currently authenticated user.

Types of scopes

When defining a scope in the Data Governance Broker configuration, the administrator may choose between three different scope types.

Scope type Description
Generic scope A scope that is not associated with a resource type or attribute.
Authenticated identity scope A scope that is associated with one or more attributes for the identity resource type. Applies to a single user only.
Resource scope A scope that is associated with one or more attributes for an arbitrary resource type. Applies to any resource of the specified resource type.

Generic scopes are typically used in conjunction with a third-party resource server. They have no intrinsic meaning to the Data Governance Broker but can be referenced by the Data Governance Broker’s policy engine when making authorization decisions.

The remaining two scope types represent more well-defined relationships with the Data Governance Broker’s schema. Each is associated with a specific resource type, a specific set of attributes, and a specific set of operations against those attributes. The operation types are:

  • retrieve
  • modify
  • create
  • delete
  • search

Authenticated identity scopes are implicitly associated with the identity resource type. (The identity resource type is the resource type that represents users who can authenticate to the Data Governance Broker.) When the Data Governance Broker is used as both an authentication server and a resource server, this is the scope type most commonly used by clients. A client in possession of an access token for an authenticated identity scope has access to data belonging to the authenticated user over the Broker’s SCIM or UserInfo services. Authenticated identity scopes do not grant access to date for any user other than the user associated with the access token.

Resource scopes apply to any single specific resource type — not necessarily the identity resource type — and may be further constrained to apply to a sub-resource type. A resource scope grants access to attributes across all resources of the configured resource type rather than just the currently authenticated user. For that reason, the Data Governance Broker’s default policies restrict the conditions under which resource scopes will be granted; either of the following two conditions must be true:

  1. The OAuth 2 grant type is client credentials.
  2. The authenticated user has an entitlements attribute with a value of admin.

The two conditions suggest the use cases for which resource scopes may typically be used:

  1. The client is a privileged application that requires the ability to search across a set of user data, without prior user consent.
  2. The user is a privileged user, such as an administrator or customer support representative.

Resource scopes therefore provide a means of operating on data across more than a single authenticated user while still allowing the extent of access to be constrained to specific resource types and attributes.

Standard scopes

With the exception of two predefined scopes, openid and offline_access (see the note below), the scopes that the Data Governance Broker will accept are entirely defined by the configuration that you or the Data Governance Broker administrator choose and should be a function of your application’s use cases and your organization’s security requirements.

If your Data Governance Broker is set up to use the example starter schema, then a set of scopes defined by the OpenID Connect standard will be configured for you. Because these scopes have defined semantics, it may be useful for your Data Governance Broker to support them for the sake of interoperability, even if you use a different schema. You would need to configure the scopes’ resource attributes as necessary to support your schema, of course.

Scope Description
profile Represents read-only access to a user’s profile attributes, such as their name and username.
email Represents read-only access to a user’s email address.
address Represents read-only access to a user’s physical address.
phone Represents read-only access to a user’s telephone number.

Two predefined scopes have special meaning to the Data Governance Broker and, when requested, invoke special behaviors. These are the openid and offline_access scopes, defined by the OpenID Connect standard.

Scope Description
openid Marks an OAuth 2 request as an OpenID Connect request. This is a prerequisite to obtaining an ID token.
offline_access Indicates that the client expects to receive a refresh token.

In typical cases, when a client makes an OAuth 2 or OpenID Connect request, the Data Governance Broker prompts the user to authorize the request, presenting the access request according to the scopes desired by the client. If the user approves the request, then the server records a consent record.

This behavior is configurable, however, and the Data Governance Broker may be configured so that specific scopes do not require approval when requested by specific clients. This can be desirable, for example, if the client belongs to the same organization running the Data Governance Broker; this avoids giving the impression that the organization is asking for permission to ask for data that the user perceives to already be handled by the same organization. In such a case, the organization may have already secured consent for data access through the use of an end user license agreement, for example.

When consents are recorded, these records may be accessed and managed after the fact via the Data Governance Broker’s SCIM consent APIs. These are documented in detail by the API reference.

Configuring scopes

The Data Governance Broker must be configured for each scope that a client intends to use. A client may only request scopes that have been registered to the client in the configuration.

Scopes are associated with clients in the Data Governance Broker configuration using Permitted Scope objects. A Permitted Scope represents the relationship between a client and a scope, indicating the conditions needed for a scope to be granted for the client’s use. These conditions are:

Permitted scope property Description
Optional Whether or not the scope must be granted by the end user in order for an OAuth 2 or OpenID Connect request to succeed. If true, the Data Governance Broker’s Auth UI will allow the user to decline authorization for the scope while still being able to approve the request as a whole.
Consent Required Whether or not the user is to be prompted to grant consent for this scope. If false, the Data Governance Broker’s Auth UI will not list the scope when presenting the user with an authorization decision, and a consent record will not be saved. As long as the OAuth 2 or OpenID Connect request succeeds, the scope will be automatically granted to the client.
Required ACR An ACR that must be satisfied for the scope to be granted to the client. This can be set to ensure that a scope is only granted when certain authentication requirements have been met.

The following example shows how an application could be configured to use the various Permitted Scope properties:

# Register a client called 'Example App'.
dsconfig create-oauth2-client --client-name "Example App" \
  --set grant-type:authorization-code \
  --set redirect-url:https://example.com/callback
# Create a read-only 'birthday' scope
# (This scope will already exist if you've installed the Groovy Sign In Sample)
dsconfig create-oauth2-scope --scope-name birthday \
  --type authenticated-identity \
  --set "description:Read the user's birthDate attribute" \
  --set "consent-prompt-text:Wish you a happy birthday." \
  --set resource-operation:retrieve \
  --set resource-attribute:urn:pingidentity:schemas:sample:profile:1.0:birthDate
# Allow Example App to request the openid scope without requiring consent.
dsconfig create-permitted-scope --client-name "Example App" \
  --scope-name openid \
  --set consent-required:false
# Allow Example App to request the email scope. Consent is required, but the
# scope is not optional.
dsconfig create-permitted-scope --client-name "Example App" \
  --scope-name email
# Allow Example App to request the birthday scope. Consent is required, but
# the user may choose to decline authorization for the scope. The scope can
# only be granted if the 'MFA' ACR was satisfied during authentication.
dsconfig create-permitted-scope --client-name "Example App" \
  --scope-name birthday \
  --set optional:true \
  --set required-acr:MFA

When this client makes an OpenID Connect request, the user will see an authorization screen like the following after authenticating using multi-factor authentication:

Data Governance Broker authorization page

Note that the user has not been prompted to approve the openid scope, and the birthday scope may be deselected.

Selecting resource types and attributes

Configuring an authenticated identity scope or a resource scope requires that you understand the SCIM resource types and SCIM schema configured for the Data Governance Broker.

Let’s look at the birthday scope from the previous example:

dsconfig create-oauth2-scope --scope-name birthday \
  --type authenticated-identity \
  --set "description:Read the user's birthDate attribute" \
  --set "consent-prompt-text:Wish you a happy birthday." \
  --set resource-operation:retrieve \
  --set resource-attribute:urn:pingidentity:schemas:sample:profile:1.0:1.0:birthDate

Because this is an authenticated identity scope, the resource type is not explicitly configured. Implicitly, it will be the resource type marked as the Identity SCIM Resource Type in the Data Governance Broker’s Authentication Service configuration. If the Data Governance Broker was installed using the example starter schema, this will be the Users resource type.

This scope has a single resource attribute, though multiple resource attributes could be configured. Notice that the birthDate attribute is namespaced with a schema URN prefix. SCIM resource types are always designated with a core schema, plus zero or more schema extensions. If you look at the configuration for the Users resource type, you’ll see that the urn:pingidentity:schemas:sample:profile:1.0 schema is configured as a schema extension. Because of this, the birthDate attribute must be namespaced as urn:pingidentity:schemas:sample:profile:1.0:birthDate. If the urn:pingidentity:schemas:sample:profile:1.0 schema had been configured as the core schema, then it would be sufficient to reference the attribute without the schema URN prefix.

Let’s look at another example. Say that we’d like to write an application that allows a customer service representative to look up a user’s consent history. To configure a scope that will give our application the access that it needs, we’ll want to look at the API reference for the SCIM OAuth 2 Consent sub-resources as we set up the scope. Here are the questions that we need to answer while looking at the API reference:

  • What kind of scope should be used?
  • Which resource type and sub-resource type should be selected?
  • Which operation types should be selected?
  • Which attributes are needed?
  • Should consent be required?

And the answers are:

  • We should use a resource scope. This is a customer service application, so the application will need to look up any user, not the currently logged in user. (Note that the currently logged in user will be a customer service representative — we do not intend to access that person’s consent history.)
  • The resource type should be whichever resource type is configured as the identity resource type, because that is the resource type that represents end users with the ability to log in to the Data Governance Broker. With the example starter schema, this resource type would be Users. The sub-resource type should be Consent History.
  • We should choose the retrieve and search operation types. These are the only two operations that we expect our application to perform. In this case, the sub-resource that we’ll be working with doesn’t support any other operation types.
  • Looking at the table listing the fields of a consent history resource, we see that the available fields are schemas, meta, client, and scopes. We’ll want access to all of those fields, so we can either set the resource attribute to * (meaning all attributes) or client and scopes. (We don’t have to specify schemas and meta, because those attributes are always available.)
  • Finally, we don’t need to require consent. This is because the resources that we want to access do not belong to the user who will be interacting with the application, so it makes no sense to require the Data Governance Broker to prompt for consent.

Putting that all together, we get the following configuration.

# Assume that we have an OAuth2 Client called 'CSR App'.
# The 'consent_history' resource scope.
dsconfig create-oauth2-scope --scope-name consent_history_example \
  --type resource \
  --set "description:Search and view users' consent history." \
  --set "consent-prompt-text:Search and view users' consent history." \
  --set scim-resource-type:Users \
  --set "scim-sub-resource-type:Consent History" \
  --set resource-operation:retrieve \
  --set resource-operation:search \
  --set resource-attribute:client \
  --set resource-attribute:scopes
# Assign the 'consent_history' scope to 'CSR App'.
dsconfig create-permitted-scope --client-name "CSR App" \
  --scope-name consent_history \
  --set consent-required:false