Skip to main content

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

Project description

===================
mozilla-django-oidc
===================

.. image:: https://badge.fury.io/py/mozilla-django-oidc.svg
:target: https://badge.fury.io/py/mozilla-django-oidc

.. image:: https://travis-ci.org/mozilla/mozilla-django-oidc.svg?branch=master
:target: https://travis-ci.org/mozilla/mozilla-django-oidc

.. image:: https://codecov.io/gh/mozilla/mozilla-django-oidc/branch/master/graph/badge.svg
:target: https://codecov.io/gh/mozilla/mozilla-django-oidc

.. image:: https://circleci.com/gh/mozilla/mozilla-django-oidc/tree/master.svg?style=svg
:target: https://circleci.com/gh/mozilla/mozilla-django-oidc/tree/master

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


Documentation
-------------

The full documentation is at `<https://mozilla-django-oidc.readthedocs.io>`_.


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 `<https://pypi.python.org/pypi/pipsi>`_.
Once installed, simply execute in the project root directory.

.. code-block:: shell

$ 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:


.. code-block:: shell

$ 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:

.. code-block:: shell

(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:

.. code-block:: shell

(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.

.. code-block:: shell

(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:

.. code-block:: shell

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

Linting
-------

All code is checked with `<https://pypi.python.org/pypi/flake8>`_ in
continuous integration. To make sure your code still passes all style guides
install ``flake8`` and check:

.. code-block:: shell

$ flake8 mozilla_django_oidc tests

.. note::

When you run ``tox`` it also does a ``flake8`` run on the main package
files and the tests.

You can also run linting with ``tox``:

.. code-block:: shell

$ tox -e lint


Releasing a new version
------------------------

``mozilla-django-oidc`` releases are hosted in `PyPI <https://pypi.python.org/pypi/mozilla-django-oidc>`_.
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 <http://semver.org/>`_.

* 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 <https://git-scm.com/book/tr/v2/Git-Tools-Signing-Your-Work>`_ 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`_

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`cookiecutter-djangopackage`: https://github.com/pydanny/cookiecutter-djangopackage




History
-------

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``.


.. _`@anlutro`: https://github.com/anlutro

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


.. _`@GermanoGuerrini`: https://github.com/GermanoGuerrini
.. _`@puiterwijk`: https://github.com/puiterwijk

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.


Project details


Download files

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

Source Distribution

mozilla-django-oidc-1.1.0.tar.gz (25.9 kB view hashes)

Uploaded Source

Built Distribution

mozilla_django_oidc-1.1.0-py2.py3-none-any.whl (17.1 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page