This article will explore the benefit of using OAuth 2 scopes to manage access to APIs.
THE OAUTH 2 STANDARD
OAuth 2 is an open standard for privilege delegation.
The right to use a service is controlled via an “access token”. Access tokens may be freely exchanged between parties, can be revoked at any time and should be short lived.
Refresh tokens may be provided by a service to allow holders to request new access tokens. Refresh tokens should be securely stored and not leaked to other parties, are generally long lived and may also be revoked at any time.
The privileges, referred to as “scopes” by the standard, which a specific access token bestowed upon a holder are specified during its creation and cannot be modified thereafter.
The scopes which a client may request are specific to the context in which the access token will be used, example scenarios could be implementing separation of privilege or limited time privilege escalation.
OAuth 2 scopes provide a mechanism for a client to request specific permissions, examples could be read or write access to data or the ability to create or delete data. A client cannot exceed the permissions granted to it by the access token.
API MANAGEMENT
Due to its versatility and the power of scopes to specify and enforce access controls, OAuth 2 has found favour with social network API providers such as Facebook and LinkedIn as well as cloud service providers such as Microsoft, Google and Amazon.
Additionally, commercially available API Management solutions all utilise OAuth 2 as the mechanism by which to control access to the APIs they expose, a user must present a valid access token in order to call an API method.
USING SCOPES TO ENFORCE ACCESS CONTROL
At design time, when exposing an API via an API Manager, the API publisher will have the opportunity to specify whether one or more scopes should be applied to a particular method in order to control access to that API method.
If the publisher chooses to attach scopes to an API method then all of the specified scopes must be present in the access token of an API consumer in order to be allowed to call that method.
This requirement will be enforced at runtime by the API Manager.
WHY BASING ACCESS CONTROL DECISIONS ON SCOPES IS BETTER THAN USER IDENTITY
It may be tempting to suggest that since a caller has normally already been authenticated before being allowed to request access tokens, access control decisions could simply be enforced by using the identity information of the caller.
We strongly believe that OAuth 2 scopes provide a better solution for the following reasons:
1. Consider the case of an application, which due to a programming error or deliberate modification, attempts to take unauthorised actions on behalf of the user such as modifying data without the user’s consent.
In the case of control by access token, any attempt to take actions on behalf of a user which have not been authorised, and for which scopes have therefore not been provided, will be blocked by the API Manager since the requisite permissions are absent.
However, if the access decision were based solely on the rights that a user holds and the user is entitled to modify data then the operation would be successful as the system would have no way to know that the application is acting in a fraudulent manner.
2. Consider the case of a user who is acting in a given capacity and temporarily needs elevated access rights to perform a task.
In the case of control by access token, the system may provide a mechanism to request, authorise and obtain temporary elevated rights, which can be immediately activated and are guaranteed to be revoked soon after the task is completed via the use of an appropriately short lived access token, without any further interaction required by an party.
However, if access decisions are based on user rights, the user’s profile would need to be modified by a system administrator, the user may need to logout and back in to the application in order to activate the new rights and, once the task is completed, the system administrator must remember to remove the rights and ensure that they are immediately deactivated within the application, probably requiring the user to logout and in to the application once again.
This process is both more error prone and substantially more burdensome for the user as their workflow is interrupted in order to acquire and relinquish access rights.
SUMMARY
The OAuth 2 standard provides a powerful, flexible and extensible mechanism through which to implement access controls.
Careful consideration of the use of scopes during the design and publication phases of API exposition allow an API Manager to enforce access controls and block unauthorised requests from ever reaching the sensitive methods which it protects.
The use of scopes to enforce access controls provides a finer grained permission model, able to specify the precise operations which a user and/or an application acting on behalf of a user is permitted to undertake, a better security model than one based on simple user identity and a more fluid user experience.
