Scopes
- Kai Bjørnstad (Deactivated)
The concept of scope is introduced in the OAuth2 specification as: Access Token Scope. Scopes are a concept used in the specification to specify the access privileges when requesting and issuing an Access Token.
This is an important to control access both for end-users and for the various contexts to avoid the effect of having all-powerful Access Tokens, especially for lager domains with a high number of services/APIs and users.
As defined by the specification, scope values are a somewhat abstract. Scopes are a concept or mechanism for specify what access privileges are being requested for Access Tokens.
In other words, the scopes of an Access Token is what gives it context and access privileges. One could imagine a fully valid Access Token without any scopes associates, which should have limited use, because all related services requires the requests not only to have a valid access Token, but also the service specific scopes.
The value of the scope parameter is expressed as a list of space- delimited, case-sensitive strings. The strings are defined by the Buypass OpenID Provider.
It is important to note that the semantics of a scope value is always defined in context of a service/API and a context/Security Domain.
OIDC scopes
OIDC implements authentication as an extension to the OAuth 2.0 authorization process. Use of this extension is requested by clients by including the "openid" scope value in the authorization request. In other words, the intent of the client to use the OIDC protocol to verify the identity of the end-user.
OIDC allows for user information (Claims) to be returned in the ID Token and the userinfo endpoint (and from the introspect endpoint).
See use of the authorization endpoint for use of the standard OIDC scopes.
Standard scopes
OpenID Connect specifies a set of standard claims. These claims are user attributes and are intended to provide the application with user details such as email, name and address. In other words, the scopes authorises access to end-user data.
The basic claim returned for the "openid" scope is the sub claim.
The OIDC specification further defines scopes specific for the OIDC claims API: Requesting Claims using Scope Values.
Examples of standard scopes are:
scope=openid profile email phone
Custom scopes
The OIDC specification can easily be extended with additional scopes given a OpenID Provider/context/Security Domain. The custom scopes can f.ex. control the return of custom claims (the same way as the standard scopes). The semantics meaning of a custom scope can be defined by the service owner.
See claims for documentation on scopes authorising Buypass specific claims.
API scopes
To enforce various forms of access privileges, services and APIs should define their own scopes according to the relevant functionality.
For example different scopes could be created to control read, write and delete functionality in the API:
| Functionality | Scope |
|---|---|
| Read data | myservice.data_read |
| Write/edit data | myservice.data_write |
| Delete data | myservice.data_delete |
When an API has define the scopes, the applications can request these defined permissions when they initiate an authorization flow/grant and include them in the Access Token as part of the scope request parameter.
See both the authorization endpoint and the token endpoint for requesting scopes (depending on the OIDC flow or OAuth2 grant in use).
For scopes authorising authorisations to services/apis, please consult the relevant API documentation.