Adapter for integrating Shibboleth with the Django authentication system
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
shibboleth
.gitignore
.travis.yml
Manifest.in
README.md
license.md
quicktest.py
setup.py

README.md

django-shibboleth-adapter

Middleware for using Shibboleth with Django. Requires Django 1.7 or above.

This is a fork of https://github.com/Brown-University-Library/django-shibboleth-remoteuser.

I forked it because, if I remember correctly, I didn't like some design choices with the login redirects.

This fork is not activley maintained and has some rough edges. Unless you run into the same problems that I had, you might be happer with the original project. It appears to be under active development.

Build Status

Installation and configuration

  • Copy the shibboleth folder from the repository into your django project folder and add shibboleth to your list of installed apps in your project's settings.py:
INSTALLED_APPS = (
  'django.contrib.admin',
  ...,
  'shibboleth',
  ...,
) 

You can also try to install properly via pip, but be aware I did not properly test this method.

pip install git+https://github.com/KonstantinSchubert/django-shibboleth-adapter.git

  • In settings.py :

  • Enable the RemoteUserBackend.

    AUTHENTICATION_BACKENDS += (
      'shibboleth.backends.ShibbolethRemoteUserBackend',
    )
  • Add the Django Shibboleth middleware. You must add the django.contrib.auth.middleware.ShibbolethRemoteUserMiddleware to the MIDDLEWARE_CLASSES setting after the django.contrib.auth.middleware.AuthenticationMiddleware. For example:

    MIDDLEWARE_CLASSES = (
    ...
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'shibboleth.middleware.ShibbolethRemoteUserMiddleware',
    ...
    )
  • Define the shibboleth user key. This is the shibboleth attribute that is used to identify the user. It becomes the user name in django.

    SHIBBOLETH_USER_KEY='<shibboleth-attribute>'
  • Map Shibboleth attributes to Django User model attributes via SHIBBOLETH_ATTRIBUTE_LIST. The exsting attributes can be found in the django documentation. You might want to extend them via inheritance.

SHIBBOLETH_ATTRIBUTE_LIST= [ { "shibboleth_key": "", "user_attribute" : "", "required" : }, { "shibboleth_key": "shib_user_email", "user_attribute" : "email", "required" : True }, ... ]


  Note: The Django user object has not many attributes. Note that all shibboleth attributes will be accessible in django via  the `META` dictionary in the `request` object. 

* Login and Logout url - set this to the login/Logout handler of your shibboleth installation. 
  In most cases, this will be something like:

  ```python
  SHIBBOLETH_LOGIN_URL = 'https://your_domain.edu/Shibboleth.sso/Login'
  SHIBBOLETH_LOGOUT_URL = 'https://your_domain.edu/Shibboleth.sso/Logout'
  • Set the django LOGIN_URL to the login-view provided by this package:

    LOGIN_URL = '/shib/login/'

    You can also manually set this this url in your templates. It is necessary to specify a redirect location using the url parameter next.

  • You can try to set the SHIBBOLETH_LOGOUT_REDIRECT_URL which defines where the user will be redirected after logout. You identity provider might ignore this setting.

  • Apache configuration - make sure the shibboleth attributes are available to the app. The shibboleth variables are passed into the HttpRequest.META dictionary via wsgi.

    <Location /app>
      AuthType shibboleth
      Require shibboleth
    </Location>
    

Verify configuration

If you would like to verify that everything is configured correctly, follow the next two steps below. It will create a route in your application at /yourapp/shib/ that echos the attributes obtained from Shibboleth. If you see the attributes you mapped above on the screen, all is good.

  • Add shibboleth to installed apps.

    INSTALLED_APPS += (
      'shibboleth',
    )
  • Add below to urls.py to enable the included sample view. This view just echos back the parsed user attributes, which can be helpful for testing.

    urlpatterns += patterns('',
      url(r'^shib/', include('shibboleth.urls', namespace='shibboleth')),
    )

##Optional ###Template tags

  • Template tags are included which will 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 not required. To activate add the following to settings.py.

     TEMPLATE_CONTEXT_PROCESSORS += (
        'shibboleth.context_processors.login_link',
        'shibboleth.context_processors.logout_link'
     )

###Persist django session when shibboleth session has ended

  • In many cases the shibboleth-session is managed by a short-lived session cookie, which means that the user is being logged out when the browser closes. There is also a django session, which by default lasts longer. In the default configuration, the django-shibboleth-adapter cancels the django session if it discovers that the shibboleth session has ended. If you want to override this setting, set
    SHIBBOLETH_DJANGO_SESSION_MAY_OUTLIVE_SHIBBOLETH_SESSION = True