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 less 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.5 venv
$ source venv
(venv) $ pip install -r requirements/requirements_dev.txt
(venv) $ DJANGO_SETTINGS_MODULE=tests.settings django-admin.py 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.py` 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

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

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.