Skip to main content

Integrate Shibboleth Authentication with your RIT projects

Project description

=============================
Django Shib Auth RIT
=============================

.. image:: https://badge.fury.io/py/django-shibauth-rit.svg
:target: https://badge.fury.io/py/django-shibauth-rit

.. image:: https://travis-ci.org/audiolion/django-shibauth-rit.svg?branch=master
:target: https://travis-ci.org/audiolion/django-shibauth-rit

.. image:: https://codecov.io/gh/audiolion/django-shibauth-rit/branch/master/graph/badge.svg
:target: https://codecov.io/gh/audiolion/django-shibauth-rit

Integrate Shibboleth Authentication with your RIT projects

Quickstart
----------

Install Django Shib Auth RIT::

pip install django-shibauth-rit

Add it to your `INSTALLED_APPS`:

.. code-block:: python

INSTALLED_APPS = (
...
'shibauth_rit',
...
)

Add the authentication backend:

.. code-block:: python

AUTHENTICATION_BACKENDS = [
'shibauth_rit.backends.ShibauthRitBackend',
...
]

Add the middleware to process requests:

.. code-block:: python

# use MIDDLEWARE_CLASSES on Django 1.8
MIDDLEWARE = (
...
'django.contrib.auth.middleware.AuthenticationMiddleware',
'shibauth_rit.middleware.ShibauthRitMiddleware',
...
)

Add Django Shib Auth RIT's URL patterns:

.. code-block:: python

urlpatterns = [
...
url(r'^', include('shibauth_rit.urls')),
...
]

Set the `LOGIN_URL` setting to the login handler of RIT's Shibboleth installation:

.. code-block:: python

LOGIN_URL = 'https://<your-site-root>/Shibboleth.sso/Login'

Map Shibboleth's return attributes to your user model:

.. code-block:: python

SHIBAUTH_ATTRIBUTE_MAP = {
'uid': (True, 'username'),
'mail': (False, 'email'),
}

Shibboleth returns a number of attributes after a successful authentication. According to RIT's
docs the current attributes returned are:

.. code-block::
uid - the user's RIT username
givenName - the user's given (first) name
sn -the user's surname (last/family name)
mail - the user's email address (note that this can be null)
ritEduMemberOfUid - groups the account is a member of (Ex: forklift-operators, vendingmach-admins, historyintegrator, etc.)
ritEduAffiliation - multi-valued attribute showing relationship to RIT (Ex: Student, Staff, StudentWorker, Adjust, Retiree etc.)

Note: Additional attributes can be configured on a site-by-site basis. Please contact the ITS Service Desk with requests for additional attributes.

When you map attributes, you use a Tuple of `(Boolean, 'UserModelField')` where `Boolean` indicates if the field is `REQUIRED`. This should match your
User model's requirements. If your User model is as follow:

.. code-block:: python

class User(AbstractBaseUser, PermissionsMixin):
USERNAME_FIELD = 'email'
EMAIL_FIELD = 'email'

email = models.EmailField(_('email address'), unique=True, blank=True, null=True)
username = models.CharField(_('username'), unique=True, required=True, max_length=50)
name = models.CharField(_('Name of User'), blank=True, max_length=100)

Then `username` is a required attribute and should be `'uid': (True, 'username')` but email is not
required and should be `'mail': (False, 'email')`.

Note: If email is a required field on your model, shibboleth doesn't guarantee that `mail` will be populated so you will need to handle that exception. You can do this by subclassing `ShibauthRitBackend` and overriding `handle_parse_exception()` method. See [Subclassing ShibauthRitBackend]().

.htaccess Setup
---------------

This package requires your site to be hosted on RIT's servers. The .htaccess should look like this

.. code-block:: apache

# Ensure https is on. required for shibboleth auth
RewriteCond ${HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST} [R,L]

# Two options, lazy loading where people do not need to authenticate to get to your site
<If "%{HTTPS} == 'on'">
SSLRequireSSL
AuthType shibboleth
Require shibboleth
ShibRequestSetting requireSession false
ShibRedirectToSSL 443
</If>

# Or no lazy loading, strict requirement of shib authentication before accesing site
<If "%{HTTPS} == 'on'">
SSLRequireSSL
AuthType shibboleth
ShibRequireSession On
require valid-user
# see https://www.rit.edu/webdev/authenticating-and-authorizing-rit-users for other require options
</If>

This sets up some stuff with the Apache webserver so when people go to https://<your-site-root>/Shibboleth.sso/Login it initiates the redirect to RIT's Shibboleth logon. Don't put a url route there, though I think Apache would always pick it up before it got to your code, might as well not mess with it.

Context Processors
------------------

There are two context processors included which allow you to place `{{ login_link }}` or `{{ logout_link }}` in your templates for routing users to the login or logout page. These are available as a convenience and are not required. To activate, add the following to your settings:

.. code-block:: python

TEMPLATES = [
{
...
'OPTIONS': {
'context_processors': [
...
'shibauth_rit.context_processors.login_link',
'shibauth_rit.context_processors.logout_link',
...
],
},
...
},
]


Running Tests
-------------

To do a simple test run with your current config

.. code-block:: bash

$ python runtests.py

To comprehensively test the suite across versions of python and django

.. code-block:: bash

source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install tox
(myenv) $ tox


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

0.1.0 (2017-02-15)
++++++++++++++++++

* 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

django-shibauth-rit-1.1.0.tar.gz (12.8 kB view details)

Uploaded Source

Built Distribution

django_shibauth_rit-1.1.0-py2.py3-none-any.whl (16.4 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file django-shibauth-rit-1.1.0.tar.gz.

File metadata

File hashes

Hashes for django-shibauth-rit-1.1.0.tar.gz
Algorithm Hash digest
SHA256 44896b1afe5a7864c7f41a0e5b71694a36b40c216608ab93d905c639200244f1
MD5 9ce343fbd8be27589dcce1f833622a0c
BLAKE2b-256 41158a40063f439bf4c5aa290dfc167cf915e40f22c94ccc630cd98c1c6accfe

See more details on using hashes here.

Provenance

File details

Details for the file django_shibauth_rit-1.1.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for django_shibauth_rit-1.1.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 a407a24c133ce56ac76c63375b6d4d508b6c20b2b68eadad38ad14a8020068cf
MD5 de5fc5e0c2ccb403c3301b8f09c852dc
BLAKE2b-256 f064b03dbc078fd2ae5a609805e63ac5f2b20a1c0809b5d720cedf925013f43a

See more details on using hashes here.

Provenance

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