auth-backends 
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.12 and Django 5.2
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.
Installation
The auth_backends package can be installed from PyPI using pip:
$ pip install edx-auth-backends
Update INSTALLED_APPS:
INSTALLED_APPS = (
'social_django',
)Configuration
Adding single sign-on/out support to a service requires a few changes:
Define settings
Add the authentication backend
Add the login/logout redirects
OAuth 2.0 Settings
Setting |
Purpose |
|---|---|
SOCIAL_AUTH_EDX_OAUTH2_KEY |
Client key |
SOCIAL_AUTH_EDX_OAUTH2_SECRET |
Client secret |
SOCIAL_AUTH_EDX_OAUTH2_URL_ROOT |
LMS root, reachable from the application server (e.g. https://courses.stage.edx.org or http://edx.devstack.lms:18000) |
SOCIAL_AUTH_EDX_OAUTH2_PUBLIC_URL_ROOT |
LMS root, reachable from the end user’s browser (e.g. https://courses.stage.edx.org 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
Strategy
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_BACKENDS = (
'auth_backends.backends.EdXOAuth2',
'django.contrib.auth.backends.ModelBackend',
)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 urls.py.
from auth_backends.urls import oauth2_urlpatterns
urlpatterns = oauth2_urlpatterns + [
url(r'^admin/', include(admin.site.urls)),
...
]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.
Testing
Call make test.
Publishing a Release
Releases are published automatically by python-semantic-release whenever a PR merges to master. The new version number is derived from the conventional-commit subject lines (feat:, fix:, etc.) of the commits being merged, and semantic-release tags the release and publishes it to PyPI accordingly.
Do not manually create a tag or a Github release for a new version. A hand-cut tag will cause python-semantic-release to lose track of what it has already released, breaking future automated releases.
License
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.
Reporting Security Issues
Please do not report security issues in public. Please email security@openedx.org.
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.
1 maintainer
Metadata
1 maintainer
Release files for edx-auth-backends 5.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| edx_auth_backends-5.1.0.tar.gz | 100.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| edx_auth_backends-5.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 123.7 kB
Release files / edx_auth_backends-5.1.0.tar.gz
| Download URL | edx_auth_backends-5.1.0.tar.gz |
|---|---|
| Size | 100.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6443407c7fc5e0b7d84a52071f01d1e5e0c133dcb5e8d369f353419e0893a273
|
|
BLAKE2b-256 checksum How to use checksums |
7d00acf6d974f9f5686b924127ebde4c9e82878fec587d4950257b911e85cd46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / edx_auth_backends-5.1.0-py3-none-any.whl
| Download URL | edx_auth_backends-5.1.0-py3-none-any.whl |
|---|---|
| Size | 23.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d79080edf5947a5ba8adffaa863ecd4d991464bb750117959fedb27fdb73ce4a
|
|
BLAKE2b-256 checksum How to use checksums |
11ef7ed51681b0e29cac3d63c4935b4c39240c15c2d417d5ba5884207dc30cb3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency log
