Scopes configuration

Scopes are a representation of the data or actions that an application can access or perform. The scopes can be freely defined by you and therefore access can be limited by creating a fine-grained policy. Social networks such as Facebook and Google have defined a large number of scopes to limit access to certain applications only to the parts that they really need access to. Examples of such scopes are: profile, email, user_likes, user_posts.

This way the opportunity for abuse can be greatly limited. Scopes are linked to an access token that is issued to an application on behalf of an end-user. In case of a client credentials access token it is not on behalf of a user but only on behalf of the application. In order to request scopes an application needs to request them during the authorization flow. A user will be optionally presented with a consent screen to allow the application to use certain scopes. The consent screen is particularly for scenarios where the application is managed by a third-party. 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 login you need to give consent to share your personal data with the third-party application / 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. Both additional and default scopes can be requested by an application during an authorization request. Each application configuration can have various default and additional scopes defined. When an application requests a scope that is either not assigned to this application or does not exist the request will be rejected.

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

Add scope

Configure scopes

A scope represents an action to be executed or data to be accessed by the application. The Scope identifier field should reflect this action or data so it can be easily identified or recognised. A possible value could be: read or email.

The Service endpoint field contains the endpoint to check if the end-user is authorized to access that scope. It can be linked to a subscription or purchased product so users not having a certain subscription or product can be denied access to an application. An example endpoint value is: https://example.com/scopes/read. This field is not required. To use this scope validation a custom scope validation service implementation is required which can be configured via a Docker Compose environment variable.

The Verification failed endpoint field contains the endpoint the user will be redirected to when the user is not authorized to access the scope. When no value is defined the user will be redirected to the default as defined via a Docker Compose environment variable. This field can for instance be used to sent the user to a page where an upgrade or subscription offer is made. This field is not required.

The Required authentication level field indicates the required authentication level of the user. The value must be a number larger than 0. If during an authorization request the current authentication level of the end-user is lower than the required level, the user will be redirected to the configured authentication server. To use this functionality the user should have a configured authentication server. To use this functionality the user should have an authentication level set by the Identity Provider. When multiple scopes are requested by an application and all scopes contain an authentication level the highest value for all scopes will be used.

The Usage limit is the number of times an access token for this scope can be used. When the value is 0, the access token usage is unlimited. If a limit is set, no refresh token will be provided. When multiple scopes are requested by an application all containing a usage limit the lowest value for all scopes will be used.

The Persistent consent checkbox indicates the type of the scope. Persistent scopes are scopes that user should give consent during the first authorization request. With non persistent scopes user consent is required each authorization request. This option is checked by default in a new scope configuration form.

The Descriptions fields can be used to provide an explanation for the end-user which details are communicated upon giving consent for this scope. A description can be set for all supported languages. In order to change the default language a Docker Compose environment variable needs to be changed.