OEP-42: Authentication#
OEP |
|
Title |
Authentication |
Last Modified |
2020-05-26 |
Authors |
Robert Raposa, Nimisha Asthagiri, Julia Eskew |
Arbiter |
Jinder Singh |
Status |
Accepted |
Type |
Best Practice |
Created |
2020-02-28 |
Review Period |
2020-04-30 - 2020-05-15 |
Summary#
Decision highlights:
Authentication is provided by an OAuth 2.0 implementation using JSON Web Tokens (JWTs) as OAuth tokens.
The LMS will be the single Identity Provider and will provide only asymmetrically signed JWTs.
JWTs can be sent via a request header, or using JWT Cookies for use with microfrontends.
Mobile authentication uses JWT Authentication.
Open edX supports social and other third-party authentication.
Useful tools:
To make authenticated requests, use OAuthAPIClient for Python and @edx/frontend-platform/auth for microfrontends.
To require authentication for a REST endpoint, use the JwtAuthentication class.
For more details on Open edX best practices around authentication, see the rest of the OEP.
Context#
Authentication in the Open edX platform has historically been complicated and inconsistent. A variety of efforts have been accomplished to attempt to simplify, consolidate, and standardize the methods of authentication used. To date, there has not yet existed a single reference for the variety of decisions made, as well as an index to documentation related to authentication.
Defined Terms#
Authentication (AuthN)#
Authentication is the verification of the identity of a user, which typically initiates at a “login” application point. Authentication is required whenever we need to identify a client/caller/user/etc.
Identity Provider (idP)#
From the Wikipedia article on Identity provider:
An Identity Provider, also known as Identity Assertion Provider, can:
provide identifiers for users looking to interact with a system
assert to such a system that such an identifier presented by a user is known to the provider
possibly provide other information about the user that is known to the provider
Independently Deployable Application (IDA)#
An Open edX specific term used to describe separate applications that make up a complete Open edX installation. Examples of IDAs are: LMS + Studio (edx-platform), Insights, ECommerce, Credentials, etc.
JSON Web Token (JWT)#
From JWT.io Introduction:
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA.
OAuth 2.0 (OAuth2)#
An authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. See a simplified oauth2 explanation by Aaron Parecki or dig into the full OAuth2 specification.
OpenID Connect (OIDC)#
Note
We are no longer using OpenID Connect. This definition is only to provide context for historical decisions to move away from OpenID Connect.
From OpenID Connect Discovery 1.0 document:
OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 [RFC6749] protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
Decisions#
There are a number of authentication related decisions that have been made. This OEP is meant to be updated over time as we gain more information, including links to other related Architectural Decision Records (ADRs).
OAuth2 and JWTs#
The currently supported and recommended method of authentication is an OAuth 2.0 implementation using JSON Web Tokens (JWTs) as OAuth tokens.
Here are a variety of details around this decision:
Standardize on the Django OAuth Toolkit (DOT) library to support our OAuth2 implementation.
Read the ADR on Django OAuth Toolkit (DOT).
JWT Authentication is the standard method of authentication in Open edX.
Use JWT and DOT to implement OAuth2. See the ADR to use JWTs as OAuth Tokens for more details on this decision.
JWTs are now the only fully supported type of access token.
All JWTs will be signed using “asymmetric” cryptographic keys, as detailed in this ADR on Asymmetric JWTs.
For authentication from our micro-frontends, a shared cookie is used to store the JWT and usable across IDAs, as detailed in this JWT Cookies ADR.
Implementation of all the OAuth2/JWT APIs supported by DOT in the LMS Identity Provider can be found in oauth_dispatch (edx-platform).
As of the Juniper Open edX release, the deprecated implementation of OAuth2 using OpenID Connect (OIDC) and the Django OAuth2 Provider (DOP) library has been fully removed. See this oauth_dispatch as router ADR for additional details of how this transition was implemented in edx-platform, and to better understand the history of
oauth_dispatch.
OAuth2 and Bearer Tokens#
This section refers to Bearer Tokens as documented in OAuth 2.0 RFC: Bearer Token Usage.
In this section, Bearer Tokens refers to tokens sent with “Bearer” in the Authorization request header. In contrast, our JWTs are sent using “JWT” in the Authorization request header. Note that the Authorization request header contains the credentials used to authenticate a user, even though it uses the term authorization.
All usage of Bearer tokens in Open edX has been deprecated. For mobile applications, see a more detailed explanation in oAuth2 and Mobile.
OAuth2 Token Security#
The communications between the browser, LMS, and IDA must all use Transport Layer Security (TLS) in order to keep the OAuth2 token secure, as anyone with the token can make a restricted IDA request.
This applies to all OAuth2 tokens, including those discussed in OAuth2 and JWTs and OAuth2 and Bearer Tokens.
Standardized Libraries and Utilities#
This section details a variety of authentication related libraries and utilities that Open edX has standardized on. It is important to keep to these standards in order to help keep Open edX more secure.
For any of the following solutions, it is important to avoid creating local alternatives inside an IDA. If a local alternative exists, it should either be deprecated and replaced by these standards, or requires an ADRs explaining why the exception is necessary and how the security of Open edX will continue to be ensured.
API Providers: Authentication Classes#
Django REST Framework (DRF) is the standard library used by Open edX to implement REST APIs in Python. Learn more about Authentication with Django REST Framework (DRF) here.
The following are all DRF Authentication classes.
Authentication Class |
Status |
|---|---|
JwtAuthentication (edx-drf-extensions) |
Supported |
SessionAuthentication (django-rest-framework) |
Supported |
BearerAuthentication (edx-drf-extensions) |
Deprecated |
BasicAuthentication (django-rest-framework) |
|
Note: Our JwtAuthentication class is a subclass of JSONWebTokenAuthentication, which can be found in drf-jwt, an open source fork of django-rest-framework-jwt that supports Django 2.2.
Authenticated API Clients#
The following are supported API clients that handle authentication using the supported methods documented in this OEP.
OAuthAPIClient (edx-rest-api-client): A Python client for making authenticated server-to-server calls.
@edx/frontend-platform/auth (frontend-platform): A JavaScript client for making authenticated calls from a micro-frontend.
OAuth Backend#
Open edX uses EdXOAuth2 (auth-backends) to provide SSO across IDAs using OAuth2. For more general information, see Specifying authentication backends in Django. This backend implementation uses the python-social-auth library.
Consequences#
Although some of the work required to make these decisions a reality have been completed, there is still a variety of outstanding work and clean-up to be done.
Since the LMS is the single authentication server, we need to remove the non-standard
JWT_ISSUERS.Read this ADR section on removing JWT_ISSUERs. The Ecommerce Service provides the largest obstacle to this effort.
Not all JWTs are yet signed with “asymmetric” keys.
Deprecation and removal of authentication libraries and utilities that are not part of our Standardized Libraries and Utilities. Because removal can be costly and may not always get prioritized, start with appropriately marking functions and classes as deprecated to help minimize the contagion factor.
References#
Change History#
2022-11-23#
Update for use of JWT in mobile applications
2021-08-23#
Introduced a link to mobile auth docs.
2020-05-26#
Improved summary and minor text updates.
2020-05-15#
Initial version of OEP was accepted.
Social (and Other) Authentication#
Open edX platform also supports several social authentication methods, such as Google, Facebook, and LinkedIn, along with other campus/business-specific authentication methods, including SAML. These external authentication methods are used to integrate or link your edX identity to another network identity. However, once the identity link is established and an Open edX account is created, the LMS still functions as usual as the idP for all satellite IDAs, and uses Open edX (non-social) authentication methods described above.
The code for supporting third party authentication (SAML, Google, Facebook, etc), where the initiating identity provider is _not_ the Open edX LMS, is located in third_party_auth (edx-platform). This implementation is supported by the python-social-auth library.