--- title: OAuth 2.0 scopes description: OAuth 2.0 flows require scopes to limit the client's access to the resource owner's resources. component: pingam version: 7.2 page_id: pingam:oauth2-guide:oauth2-scopes canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-scopes.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-scopes.html section_ids: configure-scopes: Configure scopes in the consent screen special-oauth2-scopes: Special scopes --- # OAuth 2.0 scopes OAuth 2.0 flows require scopes to limit the client's access to the resource owner's resources. > **Collapse: What are scopes?** > > Scopes are a way to restrict client access to the resource owner's resources, as defined in the [OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/info/rfc6749). > > Scopes are not associated with data and, in practice, they are just concepts specified as strings that the resource server must interpret in order to provide the required access or resources to the client. The OAuth 2.0 framework does not define any particular value for scopes since they are dependent on the architecture of your environment. > > For example, a client may request the `write` scope, which the resource server may interpret as that the client wants to save some new information in the user's account, such as images or documents. > > A client can request one or more scopes, which AM may display in the consent screen. If the resource owner agrees to share access to their resources, scopes are included in the access token. For security reasons, AM only accepts scopes preconfigured in the Scope(s) or in the Default Scope(s) fields in the client profile (Realms > *Realm Name* > Applications > OAuth 2.0 > Clients > *Client Name* > Core). AM checks the requested scopes against the Scope(s) field of the client's profile. If the client requests a scope that is not preconfigured, AM returns an error, such as `Unknown/invalid scope(s)`. If a client does not request any scopes, AM uses the scopes configured in the Default Scope(s) field of the client's profile. If none are configured, AM uses those configured in the Default Scope(s) field of the OAuth 2.0 provider. If no scopes are configured by default, AM returns the `No scope requested` error. AM does not use the default scopes in any other circumstance. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The Client Registration Scope Allowlist field of the OAuth 2.0 provider restricts the scopes a client can register with. In that sense, it is used for OpenID Connect discovery and dynamic client registration *only*.You can use this field, however, to configure how AM presents the scopes in the AM consent screen. By default, scopes are not configured to display in the consent screen. You can either [disable the consent pages](allowing-clients-to-skip-consent.html), or configure the scopes for display as described [below](#configure-scopes). | Since scope names are arbitrary, in some cases, they would not be descriptive enough for the resource owner to understand their purpose. In other cases, you may not want the resource owner to see a particular scope because it is for internal uses only. ## Configure scopes in the consent screen You can configure the AM consent screen to show, for each scope, one of the following options: | The scope itself | A localized description | Neither the scope nor a description | | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | ![The OAuth 2.0 AM user interface consent screen requesting access to the write scope.](_images/oauth2-xui-scope-only.png) | ![The OAuth 2.0 AM user interface consent screen showing the English description of a scope.](_images/oauth2-xui-scope-description.png) | ![The OAuth 2.0 AM user interface consent screen not showing scopes or descriptions](_images/oauth2-xui-no-scope.png) | Configure how scopes appear in the consent screen by client or by realm (in the OAuth 2.0 provider service). For examples, see the Client Registration Scope Allowlist field in the provider's [Advanced](../reference/global-services-configuration.html#global-oauth-oidc-advanced) reference section or the Scope(s) field in [Core Properties](oauth2-register-client.html#configure-oauth2-oidc-client). Note that client-level configuration overrides the configuration that is set at the provider level. ## Special scopes AM reserves the following special scopes that *cannot be added during dynamic client registration*: * am-introspect-all-tokens Add this scope to the Scopes(s) field in a client profile to let the client introspect tokens issued to other clients, as long as all clients are registered in the same realm. For example: 1. Client A is registered in the `/customers/NA` realm, and it is issued a token there. 2. Client B is registered in the `/customers` realm. It cannot introspect Client A's token because they are not in the same realm. Client B can only introspect tokens from other clients registered in the `/customers` realm. * am-introspect-all-tokens-any-realm Add this scope to the Scopes(s) field in a client profile to let the client introspect tokens issued to other clients, as long as they are registered in the realm of the introspecting client, or in a subrealm of it. For example: 1. Client A is registered in the `/customers/NA` realm, and it is issued a token there. 2. Client B is registered in the `/customers` realm. It can introspect Client A's token because the `/customers/NA` realm is a subrealm of the `/customers` realm. Client B can introspect tokens for any client registered in the `/customer` realm, or any subrealm of it. For security reasons, give these scopes only to the clients that need them. Related information: * For examples of requesting scopes from the authorization server, see any of the grant flows in [OAuth 2.0 grant flows](oauth2-implementing-flows.html). * To create your own implementation of the scope handler, see [Customize OAuth 2.0 with plugins](customizing-oauth2-scopes.html). * To configure AM to grant scopes dynamically by evaluating authorization policies at runtime, see [Authorization and policy decisions](../authorization-guide/what-is-authz-decision.html) and [Dynamic OAuth 2.0 authorization](../authorization-guide/oauth2-authorization.html).