Home > OpenID Connect OAuth Server by DnC > Develop > Definition of scopes and generalities on their use by applications

Definition of scopes and generalities on their use by applications

The extent of the authorization is defined by the Scopes. This is probably the most open point of the standard and therefore a difficult concept to master for the developer of an application using OpenID Connect.

The ability to modulate authorization extent based on the client application and the end user is an exceptionally interesting feature of OAuthSD.

We often see in OIDC a simple SSO, but it misses all the power of the device: the JWT identity token combines inseparably and in a tamper-proof way the identity of the end user, that of the client application and the authorization extent.

OpenID Connect defines scopes in multiple places in the OAuth 2.0 documentation, yet does not give it the synthesis it deserves. The library OAuth2 Server Library for PHP developed by Brent Shaffer implements the scopes without the author presenting the philosophy. However, analyzing the code of this library makes it possible to complete the specification, to identify the main definitions and to propose a concept of use.

Four levels of scopes definition

1. Scopes supported by the server (Supported scopes)

In addition to the reserved and non-reserved scopes defined by OpenID Connect, the developer defines the particular scopes used by the applications. They are registered in the server configuration file (variable $supportedScopes).

The scope ’basic’ is also included in the configuration as the default scope.

Only these scopes can be used, the Authorize controller rejecting any request including a scope missing from this list.

2. Reserved Scopes

Reserved Scopes play a special role [1]. They are mainly used by the server to modify the flow behavior.

- openid: This scope is required for the application to work with OpenID Connect. If it is the only scope requested, the identification of the end user will be reduced to the claim sub.

- offline_access: OpenID Connect access requests include the refresh token only if the offline_access scope has been requested and granted.

- sli: this scope is required for the application to accept one-time identification (Single Login Identification, SLI) and silent re-authentication (Silent Re-Authentication, SRA) as we we implemented them in OAuthSD.

- kerberos: This scope authorizes the creation of an OAuthSD SLI session from authentication with Kerberos.

- The first two scopes are defined by the OAuth 2.0 standard, while the last two are introduced by OAuthSD.
- The reserved scopes do not give rise to consent from the end user, with the exception of scope offline_access.

3. Scopes available for an application (Available scopes)

These scopes are defined at the time of application registration on the server. They include :
- all or part of the reserved scopes,
- Non Reserved Scopes, which are defined by OpenID Connect or defined by the designer’s initiative. [2]

Subsequently, an application will NOT be able to use other scopes than those which have been registered thus. In particular, the Authorize controller verifies from the beginning of the process that the scopes requested in the request appear in the list of Scopes available for the application (Available scopes).

4. Granted scopes

An application transmits the scopes in the authorization request (call to Authorize endpoint). They must be in the list of Scopes available for an application.

Some of these scopes are Requested Scopes. A good understanding of the subject requires distinguishing two positions of the end user from the owner of the data, as defined by the OAuth 2.0 standard (see Portée de l’autorisation (Scope)). In summary, it is necessary to consider the scopes in two cases [3]:
- either the protected data is the property of the user, and the scopes must be understood as an access request of the application to this data: the application will have to obtain the consent of the user for to pursue,
- or the application (in the broad sense) "owns" the protected data, and the scopes must be understood as an authorization granted by the application.

In the second case (if the data belongs to the application) an application can modulate the privileges granted to the user according to the profile of the latter which is translated by the scopes.

If the application does not provide for modulating granted privileges, the designer can use the allowed scopes or the default scope.

Once the authentication has been performed (and, if necessary, the scopes have been accepted by the end user), the scopes become granted scopes.

OAuthSD: scope "privileges"

This scope is unique to OAuthSD as part of the OpenID Connect flows.

The scope "privileges" includes the claims "scope" and "profile" [4] which correspond to the eponymous fields of the table users.

It is up to a third party application to determine the values ​​to be assigned to the "scope" claim. For this, OAuthSD offers two interface techniques:
- Add additional claims to the JWT token,
- Use an HTTP Rest service .

If an application presents the "privileges" scope to the Authorize controller, the "profile" and "scope" declarations will be embedded in the UserInfos data. In this respect, it is a granted scope (Granted Scope) in the same way as the "basic", "email" and so on. that control access to the data in the users table.

In addition to this standard behavior, these statements will be embedded in the payload of the identity token.
Thus the identity of the application, the end user and its authorization staves is perfectly established by the signature of the JWT token.

Using the scope "privileges" claim "scope" for granting privileges in applications

OAuthSD groups the end user information in the users table. The field ’scope’ is of the type text and can therefore accommodate any kind of data to describe the profile of the user or give the list of his privileges. For example, you can create a ’profiler’ data object and store it in Json format.

In addition to this technique, OAuthSD allows to Add additional claims to the JWT token.

Remind that the authentication server is transparent compared to Non Reserved Scopes and "non-standard" claims: it is up to the protected resource to define what should be done according to a given application.


[1So special that they have nothing to do with a scope of authorization, but appear rather as a way to set the flow. Perhaps there is a conceptual flaw in OpenID Connect?

[2How much should we extend the definition of scopes? We discuss the issue here: /web/-OpenID-Connect-UserInfo-.html. Facebook defines a hundred scopes! But, from the perspective of controlling access to web-services and APIs, the use of scopes can go much further than the mere modulation of Userinfo. Google makes extensive use of scopes to allow access to different APIs. GitHub uses scopes to modulate user access to different features. These are proprietary applications and therefore a very particular implementation of OpenID Connect that shows two things: OpenID connect is much more than an SSO; In contrast to the idea of ​​a universal authentication system (allowing access to any application with a single identifier), control of access to applications and data can only be done in a corporate realm.

[3As expected by the standard: see Portée de l’autorisation (Scope).

[4Note that the claim "profile" and the scope "profile" must be distinguished. The definition of the scopes is well entangled!