auth-backends |CI|_ |Codecov|_
===================================
.. |CI| image:: https://github.com/openedx/auth-backends/workflows/Python%20CI/badge.svg?branch=master
.. _CI: https://github.com/openedx/auth-backends/actions?query=workflow%3A%22Python+CI%22
.. |Codecov| image:: http://codecov.io/github/edx/auth-backends/coverage.svg?branch=master
.. _Codecov: http://codecov.io/github/edx/auth-backends?branch=master
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.
Installation
------------
The `auth_backends` package can be installed from PyPI using pip::
$ pip install edx-auth-backends
Update ``INSTALLED_APPS``:
.. code-block:: python
INSTALLED_APPS = (
'social_django',
)
Configuration
-------------
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_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 <http://python-social-auth.readthedocs.io/en/latest/strategies.html>`_ 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:
.. code-block:: python
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.
.. code-block:: python
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`.
.. code-block:: python
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
--------------------
After a PR merges, create a new tag from ``master`` branch with a new version of the package and create a
`Github release <https://github.com/openedx/auth-backends/releases>`_
using the new tag that will automatically publish the package to PyPi when a release is created.
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 <https://github.com/openedx/.github/blob/master/CONTRIBUTING.md>`_ 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 <https://groups.google.com/forum/#!forum/edx-code>`_ or in the
``#edx-code`` IRC channel on Freenode.
.. :changelog:
History
=======
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
[unlisted]
----------
Intervening releases not documented here; see Releases:
https://github.com/openedx/auth-backends/releases?after=1.1.2
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 <renzo@edx.org>
Troy Sankey <tsankey@edx.org>
Raw data
{
"_id": null,
"home_page": "https://github.com/openedx/auth-backends",
"name": "edx-auth-backends",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "authentication edx",
"author": "edX",
"author_email": "oscm@edx.org",
"download_url": "https://files.pythonhosted.org/packages/b0/31/6300d3c2f0b9796b4ea7a171fd6ab827a235566b72946bb126d7e5bd4c7f/edx_auth_backends-4.4.0.tar.gz",
"platform": null,
"description": "auth-backends |CI|_ |Codecov|_\n===================================\n.. |CI| image:: https://github.com/openedx/auth-backends/workflows/Python%20CI/badge.svg?branch=master\n.. _CI: https://github.com/openedx/auth-backends/actions?query=workflow%3A%22Python+CI%22\n\n.. |Codecov| image:: http://codecov.io/github/edx/auth-backends/coverage.svg?branch=master\n.. _Codecov: http://codecov.io/github/edx/auth-backends?branch=master\n\nThis package contains custom authentication backends, views, and pipeline steps used by edX services for single sign-on.\n\nThis package is compatible with Python 3.8, Django 2.2 and Django 3.0\n\nWe 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.\n\nInstallation\n------------\n\nThe `auth_backends` package can be installed from PyPI using pip::\n\n $ pip install edx-auth-backends\n\nUpdate ``INSTALLED_APPS``:\n\n.. code-block:: python\n\n INSTALLED_APPS = (\n 'social_django',\n )\n\n\nConfiguration\n-------------\nAdding single sign-on/out support to a service requires a few changes:\n\n1. Define settings\n2. Add the authentication backend\n3. Add the login/logout redirects\n\n\nOAuth 2.0 Settings\n~~~~~~~~~~~~~~~~~~\n+----------------------------------------------------------+-------------------------------------------------------------------------------------------+\n| Setting | Purpose |\n+==========================================================+===========================================================================================+\n| SOCIAL_AUTH_EDX_OAUTH2_KEY | Client key |\n+----------------------------------------------------------+-------------------------------------------------------------------------------------------+\n| SOCIAL_AUTH_EDX_OAUTH2_SECRET | Client secret |\n+----------------------------------------------------------+-------------------------------------------------------------------------------------------+\n| SOCIAL_AUTH_EDX_OAUTH2_URL_ROOT | LMS root, reachable from the application server |\n| | (e.g. https://courses.stage.edx.org or http://edx.devstack.lms:18000) |\n+----------------------------------------------------------+-------------------------------------------------------------------------------------------+\n| SOCIAL_AUTH_EDX_OAUTH2_PUBLIC_URL_ROOT | LMS root, reachable from the end user's browser |\n| | (e.g. https://courses.stage.edx.org or http://localhost:18000) |\n+----------------------------------------------------------+-------------------------------------------------------------------------------------------+\n| SOCIAL_AUTH_EDX_OAUTH2_JWS_HMAC_SIGNING_KEY | (Optional) Shared secret for JWT signed with HS512 algorithm |\n+----------------------------------------------------------+-------------------------------------------------------------------------------------------+\n| SOCIAL_AUTH_EDX_OAUTH2_PROVIDER_CONFIGURATION_CACHE_TTL | (Optional) Cache timeout for provider configuration. Defaults to 1 week. |\n+----------------------------------------------------------+-------------------------------------------------------------------------------------------+\n| SOCIAL_AUTH_EDX_OAUTH2_JWKS_CACHE_TTL | (Optional) Cache timeout for provider's JWKS key data. Defaults to 1 day. |\n+----------------------------------------------------------+-------------------------------------------------------------------------------------------+\n\nOAuth2 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::\n\n self.social_auth.first().extra_data[u'user_id'] # pylint: disable=no-member\n\nStrategy\n~~~~~~~~\nWe use a custom `strategy <http://python-social-auth.readthedocs.io/en/latest/strategies.html>`_ that includes many of\nthe default settings necessary to utilize single sign-on for edX services. This strategy should be used for all\nservices to simplify configuration. If you need to override the defaults, you may still do so as you would with any\nsocial auth setting\u2014\u2014prepend `SOCIAL_AUTH_` to the setting name. Add the following to your Django settings to use the\nstrategy:\n\n.. code-block:: python\n\n SOCIAL_AUTH_STRATEGY = 'auth_backends.strategies.EdxDjangoStrategy'\n\nAuthentication Backend\n~~~~~~~~~~~~~~~~~~~~~~\nConfiguring the backend is simply a matter of updating the ``AUTHENTICATION_BACKENDS`` setting. The configuration\nbelow is sufficient for all edX services.\n\n.. code-block:: python\n\n AUTHENTICATION_BACKENDS = (\n 'auth_backends.backends.EdXOAuth2',\n 'django.contrib.auth.backends.ModelBackend',\n )\n\nAuthentication Views\n~~~~~~~~~~~~~~~~~~~~\nIn order to make use of the authentication backend, your service's login/logout views need to be updated. The login\nview should be updated to redirect to the authentication provider's login page. The logout view should be updated to\nredirect to the authentication provider's logout page.\n\nThis package includes views and urlpatterns configured for OAuth 2.0. To use them, simply append/prepend\n``oauth2_urlpatterns`` to your service's urlpatterns in `urls.py`.\n\n.. code-block:: python\n\n from auth_backends.urls import oauth2_urlpatterns\n\n urlpatterns = oauth2_urlpatterns + [\n url(r'^admin/', include(admin.site.urls)),\n ...\n ]\n\nIt is recommended that you not modify the login view. If, however, you need to modify the logout view (to redirect to\na different URL, for example), you can subclass ``EdxOAuth2LogoutView`` for\nthe view and ``LogoutViewTestMixin`` for your tests.\n\nTesting\n-------\n\nCall ``make test``.\n\nPublishing a Release\n--------------------\n\nAfter a PR merges, create a new tag from ``master`` branch with a new version of the package and create a\n`Github release <https://github.com/openedx/auth-backends/releases>`_\nusing the new tag that will automatically publish the package to PyPi when a release is created.\n\n\nLicense\n-------\n\nThe code in this repository is licensed under the AGPL unless otherwise noted.\n\nPlease see ``LICENSE.txt`` for details.\n\nHow To Contribute\n-----------------\n\nContributions are very welcome!\n\nPlease read `How To Contribute <https://github.com/openedx/.github/blob/master/CONTRIBUTING.md>`_ for details.\n\nReporting Security Issues\n-------------------------\n\nPlease do not report security issues in public. Please email security@openedx.org.\n\nMailing List and IRC Channel\n----------------------------\n\nYou can discuss this code on the `edx-code Google Group <https://groups.google.com/forum/#!forum/edx-code>`_ or in the\n``#edx-code`` IRC channel on Freenode.\n\n\n.. :changelog:\n\nHistory\n=======\n\n3.1.0 (2020-05-08)\n------------------\n- Added support for python 3.8\n- Removed support for Django versions older than 2.2\n\n3.0.2 (2020-02-06)\n------------------\n\nRe-release of 3.0.0 with proper version, matching tag.\n\n3.0.1 (2020-02-06)\n------------------\n\nRe-release of 3.0.0, although failed to update package version.\n\n3.0.0 (2020-02-06)\n------------------\n\n- Add support for Django 2 and drop support for some older versions (support changes from 1.8\u20131.11 to 1.11\u20132.2)\n- Remove (deprecated) OpenID Connect support\n- Test with Python 3.5, not 3.6, to match rest of edX code\n\n2.0.2 (2019-08-12)\n------------------\n\nTwo new commits that changed functionality:\n\n- Add EdXOAuth2.auth_complete_signal on auth_complete()\n- Store refresh_token in extra_data\n\n2.0.1 (2019-05-13)\n------------------\n\nCreate new Version for auth-backends for release\n\n2.0.0 (2019-03-28)\n------------------\n\nEdXOAuth2 will retrieve and store user_id claim\n\nThe EdXOAuth2 backend will now pull the user_id from the JWT and\nstore it in the UserSocialAuth.extra_data field.\n\nBREAKING CHANGE: The user_id scope is now required when using the\nEdXOAuth2 backend for oAuth+SSO. This means that the oauth\napplication must first be configured to have access to the user_id\nscope, which is not available by default.\n\n1.2.2 (2019-01-31)\n------------------\n\nUpdates to the EdXOAuth2 backend:\n\n- Supports the _PUBLIC_URL_ROOT social django setting.\n- logout_url() allows _LOGOUT_REDIRECT_URL to be undefined.\n\n1.2.1 (2018-10-26)\n------------------\n\nFix urlencode bug with EdXOAuth2 backend logout url\n\n1.2.0 (2018-10-26)\n------------------\n\nAllow for logout redirect with EdXOAuth2 backend.\n\n1.1.5 (2018-10-19)\n------------------\n\nAdd logout_url property to EdXOAuth2 backend.\n\n1.1.4 (2018-10-12)\n------------------\n\nRemove token validation from EdXOAuth2 backend.\n\n1.1.3 (2018-01-04)\n------------------\n\nAdded support to update email address.\n\nsocial_core consider email field protected and won't let it change.\nAdded a pipeline function to update email address.\n\n1.1.2 (2017-05-12)\n------------------\n\nUpdated LoginRedirectBaseView to include querystring\n\n[unlisted]\n----------\n\nIntervening releases not documented here; see Releases:\n\nhttps://github.com/openedx/auth-backends/releases?after=1.1.2\n\n\n0.1.3 (2015-03-31)\n------------------\n\n- Update required version of Python Social Auth to 0.2.3.\n\n0.1.2 (2015-02-23)\n------------------\n\n- Update required version of Python Social Auth to 0.2.2.\n\n0.1.1 (2015-02-20)\n------------------\n\n- Initial release.\n\n\nRenzo Lucioni <renzo@edx.org>\nTroy Sankey <tsankey@edx.org>\n",
"bugtrack_url": null,
"license": "AGPL",
"summary": "Custom edX authentication backends and pipeline steps",
"version": "4.4.0",
"project_urls": {
"Homepage": "https://github.com/openedx/auth-backends"
},
"split_keywords": [
"authentication",
"edx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b8fdee16fc00d11247acbcfcc7b1cf308a049a88de5a5af552857b1c026dbd3",
"md5": "8fc0cf6f0c8457cc8e694ab3b90e775c",
"sha256": "0be8885ed3111379b40cfd4abb18c3d9888cb984a0797aa4ce58d902b578ebf4"
},
"downloads": -1,
"filename": "edx_auth_backends-4.4.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "8fc0cf6f0c8457cc8e694ab3b90e775c",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 29165,
"upload_time": "2024-09-10T08:06:02",
"upload_time_iso_8601": "2024-09-10T08:06:02.070919Z",
"url": "https://files.pythonhosted.org/packages/1b/8f/dee16fc00d11247acbcfcc7b1cf308a049a88de5a5af552857b1c026dbd3/edx_auth_backends-4.4.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b0316300d3c2f0b9796b4ea7a171fd6ab827a235566b72946bb126d7e5bd4c7f",
"md5": "c4b023d74d8267b03214584c91643394",
"sha256": "372dcb708675e23b1ab12e024791a2777a31b55d65ab41c5b679f303b366f3f1"
},
"downloads": -1,
"filename": "edx_auth_backends-4.4.0.tar.gz",
"has_sig": false,
"md5_digest": "c4b023d74d8267b03214584c91643394",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31887,
"upload_time": "2024-09-10T08:06:03",
"upload_time_iso_8601": "2024-09-10T08:06:03.757044Z",
"url": "https://files.pythonhosted.org/packages/b0/31/6300d3c2f0b9796b4ea7a171fd6ab827a235566b72946bb126d7e5bd4c7f/edx_auth_backends-4.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-10 08:06:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openedx",
"github_project": "auth-backends",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "edx-auth-backends"
}
JSON
