OEP-4: Application Authorization (Scopes)¶

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 do not currently have a cohesive strategy for creating or managing scopes across the Open edX platform and have reached a point where further maturity is 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

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: resource:action) for an application relative to an Open edX instance; should only describe broad application authorization (as opposed to, say, fine-grained user authorizations)
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.

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.

Reference Implementation¶

N/A (yet)

Rejected Alternatives¶

N/A

Change History¶

Footnotes