Skip to content

D
django-cas
Commit 2c3bf9e1 by Sebastian Annies
Options

tidy up readme

parent 69195d4c
Showing with 0 additions and 211 deletions
README.rst
......@@ -169,214 +169,3 @@ if request.GET.get('pgtIou',''):
from django_cas.views import proxy_callback
return proxy_callback(request)
2.0.3 README
------------
= Django CAS =
`django_cas` is a [http://www.ja-sig.org/products/cas/ CAS] 1.0 and CAS 2.0
authentication backend for [http://www.djangoproject.com/ Django]. 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.
== Installation ==
Run `python setup.py install`, or place the `django_cas` 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',
)
}}}
Set the following required setting in `settings.py`:
* `CAS_SERVER_URL`: This is the only setting you must explicitly define.
Set it to the base URL of your CAS source (e.g.
http://sso.some.edu/cas/).
Optional settings include:
* `CAS_PROXY_CALLBACK`: The URL given to the CAS server in order to
initialize a proxy ticket. The ticket granting ticket will be sent
to this URL. The url must be registered in urls.py and handled
by django_cas.views.proxy_callback, e.g:
(r'^accounts/login/casProxyCallback$', 'django_cas.views.proxy_callback')
* `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'^accounts/login/$', 'django_cas.views.login'),
(r'^accounts/logout/$', 'django_cas.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.
== CAS proxy tickets ==
Using CAS proxy tickets is quite a bit less trivial than ordinary tickets.
First of all the CAS server requires that the Django site can be accessed
via https, and it MUST have a properly signed certificate that the CAS
server can verify.
For the test-server this can be achieved using a tunneling application
such as stunnel. However this is not enough. The CAS proxy auhentication
requires that both the web browser and the CAS server simoultaneously can
make requests to the Django server, which the Django test server does not
support.
However, there is a Django app you can use to be able to start a threaded
test server hosted here:
http://github.com/jaylett/django_concurrent_test_server
== 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.
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