Skip to main content

Custom edX authentication backends and pipeline steps

Project description

auth-backends CI Codecov

This package contains custom authentication backends, views, and pipeline steps used by edX services for single sign-on.

This package is compatible with Python 3.8, Django 2.2 and Django 3.0

We currently support OAuth 2.0 authentication. Support for OpenID Connect (OIDC) was removed as of version 3.0. Use version 2.x if you require OIDC and are not able to migrate to OAuth2.


The auth_backends package can be installed from PyPI using pip:

$ pip install edx-auth-backends




Adding single sign-on/out support to a service requires a few changes:

  1. Define settings
  2. Add the authentication backend
  3. Add the login/logout redirects

OAuth 2.0 Settings

Setting Purpose
SOCIAL_AUTH_EDX_OAUTH2_URL_ROOT LMS root, reachable from the application server (e.g. or http://edx.devstack.lms:18000)
SOCIAL_AUTH_EDX_OAUTH2_PUBLIC_URL_ROOT LMS root, reachable from the end user’s browser (e.g. or http://localhost:18000)
SOCIAL_AUTH_EDX_OAUTH2_JWS_HMAC_SIGNING_KEY (Optional) Shared secret for JWT signed with HS512 algorithm
SOCIAL_AUTH_EDX_OAUTH2_PROVIDER_CONFIGURATION_CACHE_TTL (Optional) Cache timeout for provider configuration. Defaults to 1 week.
SOCIAL_AUTH_EDX_OAUTH2_JWKS_CACHE_TTL (Optional) Cache timeout for provider’s JWKS key data. Defaults to 1 day.

OAuth2 Applications require access to the user_id scope in order for the EdXOAuth2 backend to work. The backend will write the user_id into the social-auth extra_data, and can be accessed within the User model as follows:

self.social_auth.first().extra_data[u'user_id']  # pylint: disable=no-member


We use a custom strategy that includes many of the default settings necessary to utilize single sign-on for edX services. This strategy should be used for all services to simplify configuration. If you need to override the defaults, you may still do so as you would with any social auth setting——prepend SOCIAL_AUTH_ to the setting name. Add the following to your Django settings to use the strategy:

SOCIAL_AUTH_STRATEGY = 'auth_backends.strategies.EdxDjangoStrategy'

Authentication Backend

Configuring the backend is simply a matter of updating the AUTHENTICATION_BACKENDS setting. The configuration below is sufficient for all edX services.


Authentication Views

In order to make use of the authentication backend, your service’s login/logout views need to be updated. The login view should be updated to redirect to the authentication provider’s login page. The logout view should be updated to redirect to the authentication provider’s logout page.

This package includes views and urlpatterns configured for OAuth 2.0. To use them, simply append/prepend oauth2_urlpatterns to your service’s urlpatterns in

from auth_backends.urls import oauth2_urlpatterns

urlpatterns = oauth2_urlpatterns + [
    url(r'^admin/', include(,

It is recommended that you not modify the login view. If, however, you need to modify the logout view (to redirect to a different URL, for example), you can subclass EdxOAuth2LogoutView for the view and LogoutViewTestMixin for your tests.


Call make test.

Publishing a Release

After a PR merges, create a new tag from master branch with a new version of the package and create a Github release using the new tag that will automatically publish the package to PyPi when a release is created.


The code in this repository is licensed under the AGPL unless otherwise noted.

Please see LICENSE.txt for details.

How To Contribute

Contributions are very welcome!

Please read How To Contribute for details.

Even though it was written with edx-platform in mind, the guidelines should be followed for Open edX code in general.

Reporting Security Issues

Please do not report security issues in public. Please email

Mailing List and IRC Channel

You can discuss this code on the edx-code Google Group or in the #edx-code IRC channel on Freenode.


3.1.0 (2020-05-08)

  • Added support for python 3.8
  • Removed support for Django versions older than 2.2

3.0.2 (2020-02-06)

Re-release of 3.0.0 with proper version, matching tag.

3.0.1 (2020-02-06)

Re-release of 3.0.0, although failed to update package version.

3.0.0 (2020-02-06)

  • Add support for Django 2 and drop support for some older versions (support changes from 1.8–1.11 to 1.11–2.2)
  • Remove (deprecated) OpenID Connect support
  • Test with Python 3.5, not 3.6, to match rest of edX code

2.0.2 (2019-08-12)

Two new commits that changed functionality:

  • Add EdXOAuth2.auth_complete_signal on auth_complete()
  • Store refresh_token in extra_data

2.0.1 (2019-05-13)

Create new Version for auth-backends for release

2.0.0 (2019-03-28)

EdXOAuth2 will retrieve and store user_id claim

The EdXOAuth2 backend will now pull the user_id from the JWT and store it in the UserSocialAuth.extra_data field.

BREAKING CHANGE: The user_id scope is now required when using the EdXOAuth2 backend for oAuth+SSO. This means that the oauth application must first be configured to have access to the user_id scope, which is not available by default.

1.2.2 (2019-01-31)

Updates to the EdXOAuth2 backend:

  • Supports the _PUBLIC_URL_ROOT social django setting.
  • logout_url() allows _LOGOUT_REDIRECT_URL to be undefined.

1.2.1 (2018-10-26)

Fix urlencode bug with EdXOAuth2 backend logout url

1.2.0 (2018-10-26)

Allow for logout redirect with EdXOAuth2 backend.

1.1.5 (2018-10-19)

Add logout_url property to EdXOAuth2 backend.

1.1.4 (2018-10-12)

Remove token validation from EdXOAuth2 backend.

1.1.3 (2018-01-04)

Added support to update email address.

social_core consider email field protected and won’t let it change. Added a pipeline function to update email address.

1.1.2 (2017-05-12)

Updated LoginRedirectBaseView to include querystring


Intervening releases not documented here; see Releases:

0.1.3 (2015-03-31)

  • Update required version of Python Social Auth to 0.2.3.

0.1.2 (2015-02-23)

  • Update required version of Python Social Auth to 0.2.2.

0.1.1 (2015-02-20)

  • Initial release.

Renzo Lucioni <> Troy Sankey <>

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for edx-auth-backends, version 4.0.0
Filename, size File type Python version Upload date Hashes
Filename, size edx_auth_backends-4.0.0-py2.py3-none-any.whl (29.3 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size edx-auth-backends-4.0.0.tar.gz (30.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page