Scope configuration

Scopes represent the data or actions that an application can access or perform. You can define the scopes and create a fine-grained policy to limit access. Social networks such as Facebook and Google define a large number of scopes to limit access to only the parts of the applications that users need to access. Examples of such scopes include profile, email, user_likes, and user_posts.

Scopes limit the opportunities for abuse, because they are linked to an access token that is issued to an application on behalf of a user. A client-credentials access token is not issued on behalf of a user, but on behalf of the application.

An application needs to request the scopes during the authorization flow. A user is optionally presented with a consent screen, to allow the application to use certain scopes. The consent screen is particularly for scenarios where the a third party manages the application. You are probably familiar with consent screens if you have logged in to a website using one of your social media accounts. The first time you log in, you need to give consent to share your personal data with the third-party application or website.

An application can have two types of scopes: default and additional. Default scopes are automatically assigned if a client does not request any scopes. During an authorization request, an application can request both additional and default scopes. Each application configuration can define various default and additional scopes. When an application requests a scope that is either not assigned to the application or does not exist, the request is rejected.

Configure scopes

To configure a scope in the admin console go to Configuration, App configuration, and select the Scopes tab.

A scope represents an action to be executed or data to be accessed by the application. The Scope identifier field reflects this action or data, so that it is easily identified or recognized. A possible value could be read or email. The scope identifier is used in OAuth flows when an access token is requested or validated.

The Required authentication level restricts access to a scope. The value must be a positive number. The Identity Provider sets the initial authentication level of the user. During an authorization request, if the user's current authentication level is lower than the required level, the user is redirected to the configured authentication server. When an application requests multiple scopes, the value for the highest scope level is required.

The Service endpoint checks whether the user is authorized to access that scope. It can be linked to a subscription or purchased product so that users who don't have a certain subscription or product are denied access to an application. An example endpoint value is: https://example.com/scopes/read. This field is not required.

The Verification failed endpoint is the endpoint that the user is redirected to when the user is not authorized to access the scope. For example, you can use this field to send the user to a page where an upgrade or subscription offer is made. This field is not required.

The Persistent consent check box indicates the type of the scope. Persistent scopes are scopes for which the user should give consent during the first authorization request. With non-persistent scopes, user consent is required for each authorization request. This option is checked by default for new scope configurations.

The Descriptions fields can be used to provide details that are communicated when the user gives consent for this scope. You can set a description for all supported languages. To change the default language, change the order of the supported locales in the admin console: System → General → Supported Locales.