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.
Notes :
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] We propose to call them private scopes.
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.
Embed additional declarations into the identity token
Note that the authentication server is transparent with respect to non-reserved scopes and "non-standard" declarations (claims) : it is up to the protected resource to define what must be done with it within the framework of a given application.
OAuthSD offers three complementary approaches for incorporating additional declarations into the identification token :
1. OAuthSD : scope "privileges"
This scope is unique to OAuthSD as part of the OpenID Connect flows.
The scope "privileges" includes the claims "scope" and "profil" [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.
2. 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.
3. For developers : a technique to programmatically embed additional declarations in the JWT token
In addition to the previous techniques, OAuthSD allows to incorporate additional declarations into the JWT token. Although we present this method last, it is arguably the one that will be of most interest to developers. DnC applies this technique to realize DnC SaaS.
i-Tego SaaS : a system to deliver applications as a service
i-Tego SaaS couples an online sales system to an OIDC server (OAuthSD of course) in order to lease services online .
The leased software is configured as a client application of the OIDC server.
At the time of end-user authentication, the Authorize controller identification module calls the online sales system to verify that the user is up to date with their payments.
This step also allows define end user privileges on the application, for example :
validation of any application options taken with the subscription,
limited rights (consultation only ...) during a grace period after expiry,
etc.
The privileges are incorporated into the payload of the ID Token in the form of additional declarations. The names of the declarations and the values transmitted are specific to the application in question.
RSS 2.0