README.md 6.67 KB
Newer Older
Ben Waters's avatar
initial  
Ben Waters committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
= Django CAS =

`django_gmucas` is a [http://www.ja-sig.org/products/cas/ CAS] 1.0 and CAS 2.0
authentication backend for [http://www.djangoproject.com/ Django] at George Mason University. It allows
you to use Django's built-in authentication mechanisms and `User` model while
adding support for CAS.

It also includes a middleware that intercepts calls to the original login
and logout pages and forwards them to the CASified versions, and adds
CAS support to the admin interface.

This is solely meant for GMU usage since the settings have been changed for Geoge Mason University's CAS authentication system. This is a fork of https://bitbucket.org/cpcc/django-cas/src. Credit to its authors at CPCC. Maintained by GMU SRCT.


== Installation ==

Run `python setup.py install`, or place the `django_gmucas` directory in your
`PYTHONPATH` directly. (Note: If you're using Python 2.4 or older, you'll need
to install [http://pypi.python.org/pypi/elementtree/ ElementTree] to use
CAS 2.0 functionality.)

Now add it to the middleware and authentication backends in your settings.
Make sure you also have the authentication middleware installed. Here's what
mine looks like:

{{{
MIDDLEWARE_CLASSES = (
    'django.middleware.common.CommonMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django_cas.middleware.CASMiddleware',
    'django.middleware.doc.XViewMiddleware',
)

AUTHENTICATION_BACKENDS = (
    'django.contrib.auth.backends.ModelBackend',
    'django_cas.backends.CASBackend',
)
}}}

Optional settings include:

    * `CAS_ADMIN_PREFIX`: The URL prefix of the Django administration site.
      If undefined, the CAS middleware will check the view being rendered to
      see if it lives in `django.contrib.admin.views`.
    * `CAS_EXTRA_LOGIN_PARAMS`: Extra URL parameters to add to the login URL
      when redirecting the user.
    * `CAS_IGNORE_REFERER`: If `True`, logging out of the application will
      always send the user to the URL specified by `CAS_REDIRECT_URL`.
    * `CAS_LOGOUT_COMPLETELY`: If `False`, logging out of the application
      won't log the user out of CAS as well.
    * `CAS_REDIRECT_URL`: Where to send a user after logging in or out if
      there is no referrer and no next page set. Default is `/`.
    * `CAS_RETRY_LOGIN`: If `True` and an unknown or invalid ticket is
      received, the user is redirected back to the login page.
    * `CAS_VERSION`: The CAS protocol version to use. `'1'` and `'2'` are
      supported, with `'2'` being the default.

Make sure your project knows how to log users in and out by adding these to
your URL mappings:

{{{
(r'^login/$', 'django_gmucas.views.login'),
(r'^logout/$', 'django_gmucas.views.logout'),
}}}

Users should now be able to log into your site (and staff into the
administration interface) using CAS.


== Managing Access to the Admin Interface ==

At the moment, the best way to give a user access to the admin interface is
by doing one of the following:

    * Create the initial superuser account with a username that matches the
      desired user. `django_cas` will be able to make use of the existing
      user.
    * Similarly, create database fixtures for the superusers, and load them
      when deploying the application.
    * Ask the user to sign in to the application and, as an admin, log into
      the admin interface and change their access through the Users table.


== Populating User Data ==

To add user data, subclass `CASBackend` and specify that as your
application's backend.

For example:

{{{
from django_cas.backends import CASBackend

class PopulatedCASBackend(CASBackend):
    """CAS authentication backend with user data populated from AD"""

    def authenticate(self, ticket, service):
        """Authenticates CAS ticket and retrieves user data"""

        user = super(PopulatedCASBackend, self).authenticate(
            ticket, service)

        # Connect to AD, modify user object, etc.

        return user
}}}


== Preventing Infinite Redirects ==

Django's current implementation of its `permission_required` and
`user_passes_test` decorators (in `django.contrib.auth.decorators`) has a
known issue that can cause users to experience infinite redirects. The
decorators return the user to the login page, even if they're already logged
in, which causes a loop with SSO services like CAS.

`django_cas` provides fixed versions of these decorators in
`django_cas.decorators`. Usage is unchanged, and in the event that this issue
is fixed, the decorators should still work without issue.

For more information see http://code.djangoproject.com/ticket/4617.


== Customizing the 403 Error Page ==

Django doesn't provide a simple way to customize 403 error pages, so you'll
have to make a response middleware that handles `HttpResponseForbidden`.

For example, in `views.py`:

{{{
from django.http import HttpResponseForbidden
from django.template import RequestContext, loader

def forbidden(request, template_name='403.html'):
    """Default 403 handler"""

    t = loader.get_template(template_name)
    return HttpResponseForbidden(t.render(RequestContext(request)))
}}}

And in `middleware.py`:

{{{
from django.http import HttpResponseForbidden

from yourapp.views import forbidden

class Custom403Middleware(object):
      """Catches 403 responses and renders 403.html"""

      def process_response(self, request, response):

          if isinstance(response, HttpResponseForbidden):
             return forbidden(request)
          else:
             return response
}}}

Now add `yourapp.middleware.Custom403Middleware` to your `MIDDLEWARE_CLASSES`
setting and create a template named `403.html`.

== CAS 2.0 support ==

The CAS 2.0 protocol is supported in the same way that 1.0 is; no extensions
or new features from the CAS 2.0 specification are implemented. `elementtree`
is required to use this functionality. (`elementtree` is also included in
Python 2.5's standard library.)

Note: The CAS 3.x server uses the CAS 2.0 protocol. There is no CAS 3.0
protocol, though the CAS 3.x server does allow extensions to the protocol.


== Differences Between Django CAS 1.0 and 2.0 ==

Version 2.0 of `django_cas` breaks compatibility in some small ways, in order
simplify the library. The following settings have been removed:

    * `CAS_LOGIN_URL` and `CAS_LOGOUT_URL`: Version 2.0 is capable of
      determining these automatically.
    * `CAS_POPULATE_USER`: Subclass `CASBackend` instead (see above).
    * `CAS_REDIRECT_FIELD_NAME`: Django's own `REDIRECT_FIELD_NAME` is now
      used unconditionally.