1efabfece000f78bd0cd7cdf34665308510eb350
[django-cas-provider.git] / README.rst
1 ===================
2 django-cas-provider
3 ===================
4
5 ---------------------------------
6 Chris Williams <chris@nitron.org>
7 ---------------------------------
8
9 OVERVIEW
10 =========
11
12 django-cas-provider is a provider for the `Central Authentication 
13 Service <http://jasig.org/cas>`_. It supports CAS version 1.0. It allows 
14 remote services to authenticate users for the purposes of 
15 Single Sign-On (SSO). For example, a user logs into a CAS server 
16 (provided by django-cas-provider) and can then access other services 
17 (such as email, calendar, etc) without re-entering her password for
18 each service. For more details, see the `CAS wiki <http://www.ja-sig.org/wiki/display/CAS/Home>`_
19 and `Single Sign-On on Wikipedia <http://en.wikipedia.org/wiki/Single_Sign_On>`_.
20
21 INSTALLATION
22 =============
23
24 To install, run the following command from this directory:
25
26         ``python setup.py install``
27
28 Or, put cas_provider somewhere on your Python path.
29         
30 USAGE
31 ======
32
33 #. Add ``'cas_provider'`` to your ``INSTALLED_APPS`` tuple in *settings.py*.
34 #. In *settings.py*, set ``LOGIN_URL`` to ``'/cas/login/'`` and ``LOGOUT_URL`` to ``'/cas/logout/'``
35 #. In *urls.py*, put the following line: ``(r'^cas/', include('cas_provider.urls')),``
36 #. Create login/logout templates (or modify the samples)
37 #. Use 'cleanuptickets' management command to clean up expired tickets
38
39 SETTINGS
40 =========
41
42 CAS_TICKET_EXPIRATION - minutes to tickets expiration (default is 5 minutes)
43
44 PROTOCOL DOCUMENTATION
45 =====================
46
47 * `CAS Protocol <http://www.jasig.org/cas/protocol>`
48 * `CAS 1 Architecture <http://www.jasig.org/cas/cas1-architecture>`
49 * `CAS 2 Architecture <http://www.jasig.org/cas/cas2-architecture>`
50 * `Proxy Authentication <http://www.jasig.org/cas/proxy-authentication>`
51 * `CAS – Central Authentication Service <http://www.jusfortechies.com/cas/overview.html>`
52 * `Proxy CAS Walkthrough <https://wiki.jasig.org/display/CAS/Proxy+CAS+Walkthrough>`
53
54 PROVIDED VIEWS
55 =============
56
57 login
58 ---------
59
60 It has not required arguments.
61
62 Optional arguments:
63
64 * template_name - login form template name (default is 'cas/login.html')
65 * success_redirect - redirect after successful login if service GET argument is not provided 
66    (default is settings.LOGIN_REDIRECT_URL)
67 * warn_template_name - warning page template name to allow login user to service if he
68   already authenticated in SSO (default is 'cas/warn.html')
69
70 If request.GET has 'warn' argument - it shows warning message if user has already
71 authenticated in SSO instead of generate Service Ticket and redirect.
72
73 logout
74 -----------
75
76 This destroys a client's single sign-on CAS session. The ticket-granting cookie is destroyed, 
77 and subsequent requests to login view will not obtain service tickets until the user again
78 presents primary credentials (and thereby establishes a new single sign-on session).
79
80 It has not required arguments.
81
82 Optional arguments:
83
84 * template_name - template name for page with successful logout message (default is 'cas/logout.html')
85
86 validate
87 -------------
88
89 It checks the validity of a service ticket. It is part of the CAS 1.0 protocol and thus does
90 not handle proxy authentication.
91
92 It has not arguments. 
93
94 service_validate
95 -------------------------
96
97 It checks the validity of a service ticket and returns an XML-fragment response via CAS 2.0 protocol.
98 Work with proxy is not supported yet.
99
100 It has not arguments.
101
102