OEP-4: Application Authorization (Scopes)#
OEP |
|
Title |
Application Authorization (Scopes) |
Last Modified |
2020-05-13 |
Author |
Eddie Fagin (eddie@edx.org) |
Arbiter |
Dave Ormsbee (dave@edx.org) |
Status |
Approved |
Type |
Architecture |
Created |
2016-06-20 |
Abstract#
Open edX application authorization guidelines.
The Open edX platform currently has the capability to act as an OAuth2 [1] provider (which is distinctly different from its OAuth2 client capability i.e. the “login with Social Network X” feature).
Site admins can create long-lived OAuth2 client application keys that can in turn be exchanged for shorter-lived access and refresh tokens. These keys can optionally be scoped down to a custom list of available authorizations.
We did not have a cohesive strategy for creating or managing scopes across the Open edX platform and had reached a point where further maturity was required in this area.
This proposal puts forward a strategy that is is straightforward for both application developers (those who need to know about the available scopes) and Open edX platform admins and service teams (those who need to implement the restrictions).
The goals of the proposed strategy are to:
restrict the behavior of external applications that need to integrate with an Open edX deployment, in line with the principle of “least privilege”
enable more of those applications with low friction (optimize for ease of integration over ease of development)
centralize legislation of authorization platform-wide, but federate and decentralize enforcement
avoid dictating technology and protocol choices, but have clear guidance for implementation practices
See Scope and Filter Implementation for additional decisions around the implementation in Open edX.
Motivation#
The Open edX platform, in its current state, has a very limited mechanism for restricting the authorization of third-party applications to access user data. This limitation has dampened the ability of the platform to enable an ecosystem of third party applications.
Application developers have a harder time convincing their users that those users should grant these applications “access to everything the user can see and do”, especially for special purpose applications that only need a small slice of the user’s data to operate.
Instead of needing to trust both the platform and all applications built on the platform, our architecture should allow users to simply trust the platform’s ability to delegate very specific data sets to third-parties at the user’s request.
Rationale#
The discussion of scopes and application authorization has come up many times, but only recently have we (at edx.org) started to see a meaningful number of requests from external application developers that want to build on our platform.
For example, certain applications would like access to our edx.org course catalog for use cases like affiliate marketing and content repurposing. In this case, we want to be able to grant applications read-only access to our catalog, but not write access, and not access to any other resources (such as enrollments or user profiles).
Specification#
Data model#
Object |
Description |
---|---|
service user |
an Open edX account created solely for server-to-server integrations; can have multiple associated applications |
application |
an autonomous system that needs to integrate with an Open edX platform, owned by a single service user |
resource |
named grouping of related capabilities. Will generally (not always) be a noun like “catalog” |
action |
describes a high-level behavior and will generally be “read” or “write”, but resources may use non-standard definitions where absolutely necessary (should be the exception) |
scope |
a single authorization (naming convention: |
access token |
a temporary credential that grants a set of scopes to an application |
I sketched these relationships out in the diagram below. Note that instead of using “read/write” as actions, I noted the HTTP verbs instead, just to give a sense for the implementation details we’ve got in mind at this point. Same ideas though.
Governance#
Centralize the complete list of scopes but decentralize the associated metadata and definitions
The central documented list of scopes must be readily available to application developers and service owners, and kept up to date
Centralize application and token management but decentralize token enforcement
Centralize common implementation patterns as we encounter them (logging, enforcement, etc)
Access tokens may have one or more scopes associated to them by the central authorization service; tokens should be functionally opaque to applications
Scopes should cover all RESTful web API endpoints [2] within a service, and may also cover other endpoints as desired by the service team
Resources should not leak implementation details or internal names, i.e., instead of
otto_cart
, consider justcart
orshopping_cart
Resources should not, on the other hand, be too broad to be useful, i.e., instead of
courseware
, considerdiscussions
orcatalog
or whatever specific resource is of interest
Open questions#
How will we manage scope metadata, such as the human-readable “this is the permission you’re authorizing” text for the OAuth pop-up (and localization considerations)?
What is a good strategy for application lifecycle management, such as the recommended approval flow for key creation and revocation?
What work is required to implement this proposal across the Open edX platform, including (but not limited to) the edx-platform codebase?
Backward Compatibility#
There are no backwards compatibility issues with rolling out a centralized scopes list in our OAuth2 provider, or linking scopes to existing client applications.
However, there might be issues once we start enforcing scopes on individual service endpoints, as existing client applications that once might have had broader access may get suddenly cut off from data sources that we didn’t know were being used. We will need to spend time up front understanding current access patterns in order to estimate the impact of this potentially breaking change and in order to correctly retrofit scopes onto existing application keys.
Scope and Filter Implementation#
Additional decisions around scopes:
Use JWT as OAuth Tokens ADR: Details how scopes can add additional claims to the user’s JWT OAuth Token.
ADR on Enforcing Scopes in LMS APIs: Details how scopes are enforced in the LMS and other IDAs.
See OAUTH2_DEFAULT_SCOPES
and OAUTH2_PROVIDER['SCOPES']
for the current default and additional scopes defined in the LMS.
Filters provide an additional layer of authorization. Here are some related decisions:
ADR on Organization and Users as Filters in OAuth Tokens: This section of the ADR explains filters.
Filter |
ADR |
---|---|
content_org:<org_id> |
|
tpa_provider:<provider_id> |
|
user:me |
Rejected Alternatives#
N/A
Change History#
2020-03-23: Add Scope and Filter Implementation section.
Footnotes