mozilla-django-oidc

A lightweight authentication and access management library for integration with OpenID Connect enabled authentication services.

Documentation

The full documentation is at .

Design principles

• Keep it as minimal/lightweight as possible
• Store as few authn/authz artifacts as possible
• Allow custom functionality by overriding the authentication backend
• Mainly support OIDC authorization code flow
• Allow shipping Mozilla-centric authn/authz features
• Test against all supported Python/Django version
• E2E tested and audited by Mozilla InfoSec

Running Unit Tests

Use tox to run as many different versions of Python you have. If you don't have tox installed (and executable) already you can either install it in your system Python or . Once installed, simply execute in the project root directory.

$ tox

tox will do the equivalent of installing virtual environments for every combination mentioned in the tox.ini file. If your system, for example, doesn't have python3.4 those tox tests will be skipped.

For a faster test-rinse-repeat cycle you can run tests in a specific environment with a specific version of Python and specific version of Django of your choice. Here is such an example:

$ virtualenv -p /path/to/bin/python3.8 venv
$ source venv
(venv) $ pip install -r requirements/requirements_dev.txt
(venv) $ DJANGO_SETTINGS_MODULE=tests.settings django-admin test

Measuring code coverage, continuing the steps above:

(venv) $ pip install coverage
(venv) $ DJANGO_SETTINGS_MODULE=tests.settings coverage run --source mozilla_django_oidc `which django-admin` test
(venv) $ coverage report
(venv) $ coverage html
(venv) $ open htmlcov/index.html

Local development

The local development setup is based on Docker so you need the following installed in your system:

• docker
• docker-compose

You will also need to edit your hosts file to resolve testrp and testprovider hostnames to 127.0.0.1.

Running test services

To run the testrp and testprovider instances run the following:

(venv) $ docker-compose up -d testprovider testrp

Then visit the testing django app on: http://testrp:8081.

The library source code is mounted as a docker volume and source code changes are reflected directly in. In order to test a change you need to restart the testrp service.

(venv) $ docker-compose stop testrp
(venv) $ docker-compose up -d testrp

Running integration tests

Integration tests are mounted as a volume to the docker containers. Tests can be run using the following command:

(venv) $ docker-compose run --service-ports testrunner

Linting

All code is checked with in continuous integration. To make sure your code still passes all style guides install flake8 and check:

$ flake8 mozilla_django_oidc tests

You can also run linting with tox:

$ tox -e lint

Finally you can use pre-commit hooks to run linting and formatting before you commit your code:

(venv)  $ pre-commit install

Releasing a new version

mozilla-django-oidc releases are hosted in PyPI. Here are the steps you need to follow in order to push a new release:

• Make sure that HISTORY.rst is up-to-date focusing mostly on backwards incompatible changes.

  Security vulnerabilities should be clearly marked in a "Security issues" section along with a level indicator of:

  • High: vulnerability facilitates data loss, data access, impersonation of admin, or allows access to other sites or components

    Users should upgrade immediately.

  • Medium: vulnerability endangers users by sending them to malicious sites or stealing browser data.

    Users should upgrade immediately.

  • Low: vulnerability is a nuissance to site staff and/or users

    Users should upgrade.

• Bump the project version and create a commit for the new version.

  • You can use bumpversion for that. It is a tool to automate this procedure following the semantic versioning scheme.
    • For a patch version update (eg 0.1.1 to 0.1.2) you can run bumpversion patch.
    • For a minor version update (eg 0.1.0 to 0.2.0) you can run bumpversion minor.
    • For a major version update (eg 0.1.0 to 1.0.0) you can run bumpversion major.

• Create a signed tag for that version

  Example:

  git tag -s 0.1.1 -m "Bump version: 0.1.0 to 0.1.1"
  

• Push the signed tag to Github

  Example:

  git push origin 0.1.1
  

The release is pushed automatically to PyPI using a travis deployment hook on every new tag.

License

This software is licensed under the MPL 2.0 license. For more info check the LICENSE file.

Credits

Tools used in rendering this package:

• Cookiecutter
• cookiecutter-djangopackage

History

4.0.1 (2024-03-12)

• Update configuration for readthedocs.
• Point HEAD to main branch.
• Update project's README file.

4.0.0 (2024-01-11)

• Added PKCE support in the authorization code flow. Thanks @themooer1 and @escattone
• Added support for Elliptic Curve JWT signing algorithms Thanks @atanunq
• Replace mock with unittest.mock Thanks @traylenator
• Add pre-commit hooks
• Add support for Python 3.11 and 3.12
• Add support for Django 4.2
• Document OIDC_USERNAME_ALGO Thanks @polyccon
• Add claims to custom username algorithm Thanks @EduardRosert
• Formatting fixes in the Documentation Thanks @EduardRosert
• Update token error response handling Thanks @dopry <https://github.com/dopry&gt;

Backwards-incompatible changes:

• Drop Python 3.7 support
• Drop Django 4.1 support

3.0.0 (2022-11-14)

• Gracefully handle www-authenticate header with missing error_description. Thanks @vinitsharswat and @adamj9431
• Lint project with black.
• Add support for Django 4
• Document OIDC_OP_JWKS_ENDPOINT. Thanks @yoctozepto
• Update typo in comments. Thanks @rabbit-aaron
• LOGIN_REDIRECT_URL now accepts a named url pattern. Thanks @dispiste
• Pass OIDC_AUTH_REQUEST_EXTRA_PARAMS to SessionRefresh Thanks @melanger
• Remove state from from session after failed authentication attempts Thanks @cfra
• Do not call auth.login() on session refresh. Thanks crgwbr

Backwards-incompatible changes:

• Drop Python 3.6 support
• Drop Django 2.x Support
• Drop Django 3.1 support

2.0.0 (2021-07-27)

• Make get_or_create_user compatible with custom scope configuration by moving scope specific code to describe_user_by_claims Thanks @cfra
• Add support for Django 3.2 Thanks @jannh
• Add configuration to opt in logout using GET
• Fix url encoding using escaped space characters
• Pass email as named argument in create_user
• Do not fail if JWK does not have a key ID Thanks @cfra
• Update middleware init to configure settings Thanks @dreynolds
• Add SessionAuthentication to DRF auth class Thanks @SpyTec

Backwards-incompatible changes:

• Drop Django 1.x support
• Drop Python2 support

1.2.4 (2020-08-19)

• Fix error in README.rst Thanks @der-gabe
• Fix JWKS handling when the same kid value is used across JWKs with different alg specified Thanks @davidjb
• Support regex patterns in OIDC_EXEMPT_URLS, to allow exempting session refreshes in SessionMiddleware for URLs matching the pattern Thanks @jwhitlock
• Move nonce outside of add_state_and_noce_to_session method.
• Change log level to info for the add_state_and_verifier_and_nonce_to_session.
• Session save/load management Thanks @Flor1an-dev
• Allow multiple parallel login sessions Thanks @istreeter

1.2.3 (2020-01-02)

• Add support for Django 3.x Thanks @jaap3
• Use new E2E testing images from mozilla namespace
• Remove support for EOL'ed Django versions

1.2.2 (2019-04-18)

• Add Mozilla code of conduct
• Allow overriding OIDC settings per class

1.2.1 (2019-01-22)

• Make verify_claims compatible with custom scope configuration.

1.2.0 (2019-01-09)

• Improve travis automation for PyPI releases
• Allow basic auth for OIDC token endpoint requests Thanks @anttipalola
• Replace phantomjs with firefox headless for e2e testing
• Add default email verification claim check Thanks @kerrermanisNL
• Remove compatibility code for unsupported Django versions
• Add settings to control redirect behavior Thanks @chrisbrantley

1.1.2 (2018-08-24)

• Fix JWKS handling when OP returns multiple keys Thanks @JustinAzoff

1.1.1 (2018-08-09)

• Fix is_safe_url on Django 2.1
• Fix signature in authenticate method to be compatible with Django 2.1
• Remove legacy code for unsupported Django < 1.11 Thanks @SirTyson

1.1.0 (2018-08-02)

• Installation doc fixes Thanks @mklan
• Drop support for unsupported Django 1.8 and Python 3.3.
• Refactor authentication backend to make it easier to extend Required by DRF support feature.
• Add DRF support Thanks @anlutro
• Improve local docker environment setup
• Add flag to allow using unsecured tokens
• Allow using JWK with optional alg Thanks @Algogator

1.0.0 (2018-05-09)

• Add OIDC_AUTHENTICATION_CALLBACK_URL as a new configuration parameter
• Fail earlier when JWS algorithm does not OIDC_RP_SIGN_ALGO. Thanks @anlutro
• RS256 verification through settings.OIDC_OP_JWKS_ENDPOINT Thanks @GermanoGuerrini
• Refactor OIDCAuthenticationBackend so that token retrieval methods can be overridden in a subclass when you need to.

Backwards-incompatible changes:

• OIDC_OP_LOGOUT_URL_METHOD takes a request parameter now.
• Changed name of RefreshIDToken middleware to SessionRefresh.

0.6.0 (2018-03-27)

• Add e2e tests and automation
• Add caching for exempt URLs
• Fix logout when session refresh fails

0.5.0 (2018-01-10)

• Add Django 2.0 support
• Fix tox configuration

Backwards-incompatible changes:

• Drop Django 1.10 support

0.4.2 (2017-11-29)

• Fix OIDC_USERNAME_ALGO to actually load dotted import path of callback.
• Add verify_claims method for advanced authentication checks

0.4.1 (2017-10-25)

• Send bytes to josepy. Fixes python3 support.

0.4.0 (2017-10-24)

Security issues:

• High: Replace python-jose with josepy and use pyca/cryptography instead of pycrypto (CVE-2013-7459).

Backwards-incompatible changes:

• OIDC_RP_IDP_SIGN_KEY no longer uses the JWK json as dict but PEM or DER keys instead.

0.3.2 (2017-10-03)

Features:

• Implement RS256 verification Thanks @puiterwijk

Bugs:

• Use settings.OIDC_VERIFY_SSL also when validating the token. Thanks @GermanoGuerrini
• Make OpenID Connect scope configurable. Thanks @puiterwijk
• Add path host injection unit-test (#171)
• Revisit OIDC_STORE{ACCESS,ID}_TOKEN config entries
• Allow configuration of additional auth parameters

0.3.1 (2017-06-15)

Security issues:

• Medium: Sanitize next url for authentication view

0.3.0 (2017-06-13)

Security issues:

• Low: Logout using POST not GET (#126)

Backwards-incompatible changes:

• The settings.SITE_URL is no longer used. Instead the absolute URL is derived from the request's get_host().
• Only log out by HTTP POST allowed.

Bugs:

• Test suite maintenance (#108, #109, #142)

0.2.0 (2017-06-07)

Backwards-incompatible changes:

• Drop support for Django 1.9 (#130)

  If you're using Django 1.9, you should update Django first.

• Move middleware to mozilla_django_oidc.middleware and change it to use authentication endpoint with prompt=none (#94)

  You'll need to update your MIDDLEWARE_CLASSES/MIDDLEWARE setting accordingly.

• Remove legacy base64 handling of OIDC secret. Now RP secret should be plaintext.

Features:

• Add support for Django 1.11 and Python 3.6 (#85)
• Update middleware to work with Django 1.10+ (#90)
• Documentation updates
• Rework test infrastructure so it's tox-based (#100)

Bugs:

• always decode verified token before json.load() (#116)
• always redirect to logout_url even when logged out (#121)
• Change email matching to be case-insensitive (#102)
• Allow combining OIDCAuthenticationBackend with other backends (#87)
• fix is_authenticated usage for Django 1.10+ (#125)

0.1.0 (2016-10-12)

• First release on PyPI.