Background
The goal of this post is to look at the different approaches that exist for designing API scopes by examining some popular services and share guidelines for designing scopes in a consistent and manageable way.
Scopes used in popular services
Principles and guidelines
-
OAuth 2.0 is about delegated authorization (given by the user) for 3rd party apps. It’s not a replacement for authz checks in the API.
-
Resource providers are responsible to combine the incoming scopes and the actual user privileges to calculate the call’s effective permissions and make access control decisions accordingly.
-
Scope is a grouping of related claims.
-
Keep scopes simple and limited and at a level that makes sense to the users consenting.
-
Design scopes keeping in mind the types of client and their needs (use-cases). Avoid scope explosion.
-
Scopes should be used for making coarse-grained access decisions in API Gateway to avoid unwanted requests from reaching the service.
-
Adding fine-grained scopes limits the access of the token which is good from security point of view. But having too many fine-grained scopes adds to complexity and cognitive load and maintenance. There is a tradeoff involved and we should strive for the right balance when designing scopes.
-
Starting with minimal scopes and adding more over time as need arises is evolution. Starting with many and trying to remove even one is a breaking change.
-
Authorization decisions must be layered:
-
Check token validity.
-
Check scope.
-
Fine-grained (ACL/ABAC) authorization checks.
References and further reading
-
[Relation of Scope and Claims](https://info.citrite.net/oauth claims ontology: Using Claims in OAuth and How They Relate to Scopes)