Skip to main content

An authentication backend for Django based on Polytechnique.org's auth-groupe-x SSO protocol.

Project description

django-authgroupex
==================

This library provides a Django authentication backend based on Polytechnique.org's auth-groupe-x SSO protocol.


Setup
=====

The django-authgroupex package requires only a minimal pair of settings to work:

.. code-block:: python

# Enable AuthGroupeX authentication backend
AUTHENTICATION_BACKENDS = (
'django_authgroupex.auth.AuthGroupeXBackend',
'django.contrib.auth.backends.ModelBackend', # Optional
)

# Read secret key from file
AUTHGROUPEX_KEY = open('authgroupex.key', 'r').readline()


It should also be included in your projects ``urls.py`` file:

.. code-block:: python

urlpatterns = patterns('',
# Usual suspects here
url(r'^xorgauth/', include('django_authgroupex.urls', namespace='authgroupex')),
)

.. note:: The app **must** be installed under the ``authgroupex`` namespace.



If you're using the ``django.contrib.admin`` app, you may also override its login form:

.. code-block:: python

from django.contrib import admin
admin.site.login_template = 'authgroupex/admin_login.html'

.. note:: This setting requires ``django_authgroupex`` to be part of your ``INSTALLED_APPS``.


Configuring django-authgroupex
==============================

django-authgroupex provides the following settings:

Connection
----------

* ``AUTHGROUPEX_KEY``: **Required**, the secret key used to connect to an AuthGroupeX-compatible server.

* ``AUTHGROUPEX_ENDPOINT``: The remote endpoint (an AuthGroupeX-compatible server).
Default: `https://www.polytechnique.org/auth-groupe-x/utf8`
* ``AUTHGROUPEX_FIELDS``: The list of profile fields to require upon connection; order matters.
Default: ``('username', 'firstname', 'lastname', 'email')``


Models
------

* ``AUTHGROUPEX_USER_MODEL``: Model storing users.
Default: ``auth.User``
* ``AUTHGROUPEX_GROUP_MODEL``: Model storing groups.
Default: ``auth.Group``

.. note:: The ``AuthGroupeXBackend`` authentication backend expects a
:class:`~django.contrib.auth.AbstractUser` subclass in that model.
This behaviour can be tuned by writing your own subclass, inheriting from
:class:`~django_authgroupex.auth.AuthGroupeXMixin`.

Permissions
-----------

django_authgroupex uses the 4 permissions from the AuthGroupeX SSO:

* :data:`~django_authgroupex.auth.PERM_USER`, for simple users
* :data:`~django_authgroupex.auth.PERM_GROUP_MEMBER`, for member of the related ``AUTHGROUPEX_GROUP``
* :data:`~django_authgroupex.auth.PERM_GROUP_ADMIN`, for admins of the related ``AUTHGROUPEX_GROUP``
* :data:`~django_authgroupex.auth.PERM_ADMIN`, for admins of the remote site


These (remote) permissions can be mapped to Django access rights through the following settings:

* ``AUTHGROUPEX_SUPERADMIN_PERMS``: A list of AuthGroupeX permissions that enable the
``is_admin`` flag on this server.
Default: ``()``
* ``AUTHGROUPEX_STAFF_PERMS``: A list of AuthGroupeX permissions that enable the
``is_staff`` flag on this server.
* ``AUTHGROUPEX_DISABLE_DEADS``: Whether a user connecting from a "dead" account should
be switched to ``is_active=False``
Default: ``False``
* ``AUTHGROUPEX_GROUP``: Name of the AuthGroupeX group to use for a single-group website.
Default: ``''``
* ``AUTHGROUPEX_MAP_GROUPS``: Dict mapping an AuthGroupeX permission to a local group name.
Default: ``{}``


URLs
----

The usual setup of django-authgroupex is to use
:meth:`~django_authgroupex.views.AuthGroupeXUniqueView.login_view` for authentication,
either as "login" page (thus enabling transparent authentication) or through a
"connect through X.org" link from the usual login page.

This behaviour can be tuned through the following settings:

* ``AUTHGROUPEX_RETURN_URL``: Name of the (local) return url for successful logins.
Default: ``settings.LOGIN_URL``
* ``AUTHGROUPEX_LOGIN_REDIRECT_URL``: Name of the URL to redirect the user to after a successful login without a ``?next=`` parameter
Default: ``settings.LOGIN_REDIRECT_URL``

If :meth:`~django_authgroupex.views.AuthGroupeXUniqueView.login_view` is used,
``AUTHGROUPEX_RETURN_URL`` **must** point to that view.

If :meth:`~django_authgroupex.views.AuthGroupeXBaseView.login_begin_view` and
:meth:`~django_authgroupex.views.AuthGroupeXBaseView.login_return_view` are used
``AUTHGROUPEX_RETURN_URL`` **must** point to ``login_return_view``.


Testing
=======

For testing purposes, it is advised to not use a production private key.

django_authgroupex has a special, "fake" mode for such cases.
That fake mode adds a couple of URLs handling a local endpoint where the end user can
choose custom values for requested fields.

Installation requires a couple of extra settings::

# settings.py
AUTHGROUPEX_FAKE = True
AUTHGROUPEX_ENDPOINT = 'authgroupex:fake_endpoint'
INSTALLED_APPS = (
'...',
'django_authgroupex',
)

The ``AUTHGROUPEX_FAKE`` setting will enable two views for handling fake requests:

- One validates the input (which can also be used to validate external clients)
- The second provides a dynamic form based on ``AUTHGROUPEX_FIELDS``, enabling users to
select their preferred response.

The ``AUTHGROUPEX_ENDPOINT`` setting should include the namespace at which ``django_authgroupex.urls`` was inserted.

Project details


Release history Release notifications

History Node

0.4.1

History Node

0.4.0

History Node

0.3.2

History Node

0.3.1

This version
History Node

0.3.0

History Node

0.2.2

History Node

0.2.1

History Node

0.2.0

History Node

0.1.0

Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
django_authgroupex-0.3.0.tar.gz (14.1 kB) Copy SHA256 hash SHA256 Source None Nov 21, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page