Commit 262f98fd authored by Benjamin S Waters's avatar Benjamin S Waters
Browse files

fixing readmes

parent 137a8a47
= Django CAS = Django CAS
---
`django_gmucas` is a [http://www.ja-sig.org/products/cas/ CAS] 1.0 and CAS 2.0 `django_gmucas` is a [CAS](http://www.ja-sig.org/products/cas/) 1.0 and CAS 2.0
authentication backend for [http://www.djangoproject.com/ Django] at George Mason University. It allows authentication backend for [Django](http://www.djangoproject.com/) at George Mason University. It allows
you to use Django's built-in authentication mechanisms and `User` model while you to use Django's built-in authentication mechanisms and `User` model while
adding support for CAS. adding support for CAS.
...@@ -12,7 +13,8 @@ CAS support to the admin interface. ...@@ -12,7 +13,8 @@ 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. 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 == Installation
---
Run `python setup.py install`, or place the `django_gmucas` directory in your 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 `PYTHONPATH` directly. (Note: If you're using Python 2.4 or older, you'll need
...@@ -23,20 +25,20 @@ Now add it to the middleware and authentication backends in your settings. ...@@ -23,20 +25,20 @@ Now add it to the middleware and authentication backends in your settings.
Make sure you also have the authentication middleware installed. Here's what Make sure you also have the authentication middleware installed. Here's what
mine looks like: mine looks like:
{{{ ::
MIDDLEWARE_CLASSES = (
'django.middleware.common.CommonMiddleware', MIDDLEWARE_CLASSES = (
'django.contrib.sessions.middleware.SessionMiddleware', 'django.middleware.common.CommonMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.sessions.middleware.SessionMiddleware',
'django_cas.middleware.CASMiddleware', 'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.middleware.doc.XViewMiddleware', 'django_gmucas.middleware.CASMiddleware',
) 'django.middleware.doc.XViewMiddleware',
)
AUTHENTICATION_BACKENDS = (
'django.contrib.auth.backends.ModelBackend', AUTHENTICATION_BACKENDS = (
'django_cas.backends.CASBackend', 'django.contrib.auth.backends.ModelBackend',
) 'django_gmucas.backends.CASBackend',
}}} )
Optional settings include: Optional settings include:
...@@ -57,24 +59,23 @@ Optional settings include: ...@@ -57,24 +59,23 @@ Optional settings include:
supported, with `'2'` being the default. supported, with `'2'` being the default.
Make sure your project knows how to log users in and out by adding these to Make sure your project knows how to log users in and out by adding these to
your URL mappings: your URL mappings::
{{{ (r'\^login/$', 'django_gmucas.views.login'),
(r'^login/$', 'django_gmucas.views.login'), (r'\^logout/$', 'django_gmucas.views.logout'),
(r'^logout/$', 'django_gmucas.views.logout'),
}}}
Users should now be able to log into your site (and staff into the Users should now be able to log into your site (and staff into the
administration interface) using CAS. administration interface) using CAS.
== Managing Access to the Admin Interface == Managing Access to the Admin Interface
---
At the moment, the best way to give a user access to the admin interface is At the moment, the best way to give a user access to the admin interface is
by doing one of the following: by doing one of the following:
* Create the initial superuser account with a username that matches the * Create the initial superuser account with a username that matches the
desired user. `django_cas` will be able to make use of the existing desired user. `django_gmucas` will be able to make use of the existing
user. user.
* Similarly, create database fixtures for the superusers, and load them * Similarly, create database fixtures for the superusers, and load them
when deploying the application. when deploying the application.
...@@ -82,32 +83,32 @@ by doing one of the following: ...@@ -82,32 +83,32 @@ by doing one of the following:
the admin interface and change their access through the Users table. the admin interface and change their access through the Users table.
== Populating User Data == Populating User Data
---
To add user data, subclass `CASBackend` and specify that as your To add user data, subclass `CASBackend` and specify that as your
application's backend. application's backend.
For example: For example::
{{{ from django_gmucas.backends import CASBackend
from django_cas.backends import CASBackend
class PopulatedCASBackend(CASBackend): class PopulatedCASBackend(CASBackend):
"""CAS authentication backend with user data populated from AD""" """CAS authentication backend with user data populated from AD"""
def authenticate(self, ticket, service): def authenticate(self, ticket, service):
"""Authenticates CAS ticket and retrieves user data""" """Authenticates CAS ticket and retrieves user data"""
user = super(PopulatedCASBackend, self).authenticate( user = super(PopulatedCASBackend, self).authenticate(
ticket, service) ticket, service)
# Connect to AD, modify user object, etc. # Connect to AD, modify user object, etc.
return user return user
}}}
== Preventing Infinite Redirects == Preventing Infinite Redirects
---
Django's current implementation of its `permission_required` and Django's current implementation of its `permission_required` and
`user_passes_test` decorators (in `django.contrib.auth.decorators`) has a `user_passes_test` decorators (in `django.contrib.auth.decorators`) has a
...@@ -115,39 +116,35 @@ known issue that can cause users to experience infinite redirects. The ...@@ -115,39 +116,35 @@ 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 decorators return the user to the login page, even if they're already logged
in, which causes a loop with SSO services like CAS. in, which causes a loop with SSO services like CAS.
`django_cas` provides fixed versions of these decorators in `django_gmucas` provides fixed versions of these decorators in
`django_cas.decorators`. Usage is unchanged, and in the event that this issue `django_gmucas.decorators`. Usage is unchanged, and in the event that this issue
is fixed, the decorators should still work without issue. is fixed, the decorators should still work without issue.
For more information see http://code.djangoproject.com/ticket/4617. For more information see http://code.djangoproject.com/ticket/4617.
== Customizing the 403 Error Page == Customizing the 403 Error Page
---
Django doesn't provide a simple way to customize 403 error pages, so you'll Django doesn't provide a simple way to customize 403 error pages, so you'll
have to make a response middleware that handles `HttpResponseForbidden`. have to make a response middleware that handles `HttpResponseForbidden`.
For example, in `views.py`: For example, in `views.py`::
from django.http import HttpResponseForbidden
{{{ from django.template import RequestContext, loader
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) def forbidden(request, template_name='403.html'):
return HttpResponseForbidden(t.render(RequestContext(request))) """Default 403 handler"""
}}}
And in `middleware.py`: t = loader.get_template(template_name)
return HttpResponseForbidden(t.render(RequestContext(request)))
{{{ And in `middleware.py`::
from django.http import HttpResponseForbidden from django.http import HttpResponseForbidden
from yourapp.views import forbidden from yourapp.views import forbidden
class Custom403Middleware(object): class Custom403Middleware(object):
"""Catches 403 responses and renders 403.html""" """Catches 403 responses and renders 403.html"""
def process_response(self, request, response): def process_response(self, request, response):
...@@ -156,12 +153,12 @@ class Custom403Middleware(object): ...@@ -156,12 +153,12 @@ class Custom403Middleware(object):
return forbidden(request) return forbidden(request)
else: else:
return response return response
}}}
Now add `yourapp.middleware.Custom403Middleware` to your `MIDDLEWARE_CLASSES` Now add `yourapp.middleware.Custom403Middleware` to your `MIDDLEWARE_CLASSES`
setting and create a template named `403.html`. setting and create a template named `403.html`.
== CAS 2.0 support == CAS 2.0 support
---
The CAS 2.0 protocol is supported in the same way that 1.0 is; no extensions 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` or new features from the CAS 2.0 specification are implemented. `elementtree`
...@@ -172,9 +169,10 @@ Note: The CAS 3.x server uses the CAS 2.0 protocol. There is no CAS 3.0 ...@@ -172,9 +169,10 @@ 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. protocol, though the CAS 3.x server does allow extensions to the protocol.
== Differences Between Django CAS 1.0 and 2.0 == Differences Between Django CAS 1.0 and 2.0
---
Version 2.0 of `django_cas` breaks compatibility in some small ways, in order Version 2.0 of `django_gmucas` breaks compatibility in some small ways, in order
simplify the library. The following settings have been removed: simplify the library. The following settings have been removed:
* `CAS_LOGIN_URL` and `CAS_LOGOUT_URL`: Version 2.0 is capable of * `CAS_LOGIN_URL` and `CAS_LOGOUT_URL`: Version 2.0 is capable of
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment