Django Shib Auth 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`:

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

Add the authentication backend:

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

Add the middleware to process requests:

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

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

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

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

Map Shibboleth's return attributes to your user model:

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:

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:

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

.htaccess Setup

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

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

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

Subclassing ShibauthRitMiddleware ------------------------------

ShibauthRitMiddleware has a few hooks that you can utilize to get customized behavior. To use these create a middleware.py file and add the following:

from shibauth_rit.middleware import ShibauthRitMiddleware as middleware
from shibauth_rit.middleware import ShibauthRitValidationException


class ShibauthRitMiddleware(middleware):

    def make_profile(self, user, shib_meta):
        """
        This is here as a stub to allow subclassing of ShibauthRitMiddleware
        to include a make_profile method that will create a Django user profile
        from the Shib provided attributes.  By default it does nothing.
        """
        pass

    def setup_session(self, request):
        """
        If you want to add custom code to setup user sessions, you can extend this.
        """
        pass

    def handle_parse_exception(self, shib_meta):
        """
        This is a stub method that can be subclassed to handle what should happen when a parse
        exception occurs. If you raise ShibauthRitValidationException it will need to be caught
        further up to prevent an internal server error (HTTP 500). An example of this would be if
        you require an email address and RIT Shibboleth doesn't return one, what should you do?
        """
        pass

Replace pass with any custom code you want to run. Then make sure to modify your MIDDLEWARE or MIDDLEWARE_CLASSES attribute to include the path to your custom middleware and replace this packages.

MIDDLEWARE = (
    ...
    yourapp.backends.ShibauthRitMiddleware,
    ...
)

Running Tests

To do a simple test run with your current config

$ python runtests.py

To comprehensively test the suite across versions of python and django

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

Credits

Tools used in rendering this package:

• Cookiecutter
• cookiecutter-djangopackage