9720936c914edf2ae44bf853eaee1197b2e152d4
[django-cas-provider.git] / README.rst
1 ===================
2 django-cas-provider
3 ===================
4
5 OVERVIEW
6 =========
7
8 django-cas-provider is a provider for the `Central Authentication Service <http://jasig.org/cas>`_. It supports CAS version 1.0 and parts of CAS version 2.0 protocol. It allows remote services to authenticate users for the purposes of Single Sign-On (SSO). For example, a user logs into a CAS server
9 (provided by django-cas-provider) and can then access other services (such as email, calendar, etc) without re-entering her password for each service. For more details, see the `CAS wiki <http://www.ja-sig.org/wiki/display/CAS/Home>`_ and `Single Sign-On on Wikipedia <http://en.wikipedia.org/wiki/Single_Sign_On>`_.
10
11 INSTALLATION
12 =============
13
14 To install, run the following command from this directory::
15
16     python setup.py install
17
18 Or, put `cas_provider` somewhere on your Python path.
19
20 If you want use CAS v.2 protocol or above, you must install `lxml` package to correct work.
21
22 UPDATING FROM PREVIOUS VERSION
23 ===============================
24
25 I introduced south for DB schema migration. The schema from any previous version without south is 0001_initial.
26 You will get an error:
27
28  Running migrations for cas_provider:
29   - Migrating forwards to 0001_initial.
30   > cas_provider:0001_initial
31  Traceback (most recent call last):
32  ...
33  django.db.utils.DatabaseError: relation "cas_provider_serviceticket" already exists
34
35 to circumvent that problem you will need to fake the initial migration:
36
37  python manage.py migrate cas_provider 0001_initial --fake
38
39
40 USAGE
41 ======
42
43 #. Add ``'cas_provider'`` to your ``INSTALLED_APPS`` tuple in *settings.py*.
44 #. In *settings.py*, set ``LOGIN_URL`` to ``'/cas/login/'`` and ``LOGOUT_URL`` to ``'/cas/logout/'``
45 #. In *urls.py*, put the following line: ``(r'^cas/', include('cas_provider.urls')),``
46 #. Create login/logout templates (or modify the samples)
47 #. Use 'cleanuptickets' management command to clean up expired tickets
48
49 SETTINGS
50 =========
51
52 CAS_TICKET_EXPIRATION - minutes to tickets expiration. Default is 5 minutes.
53
54 CAS_CUSTOM_ATTRIBUTES_CALLBACK - name of callback to provide dictionary with
55 extended user attributes (may be used in CAS v.2 or above). Default is None.
56
57 CAS_CUSTOM_ATTRIBUTES_FORMAT - name of custom attribute formatter callback will be
58 used to format custom user attributes. This package provide module `attribute_formatters`
59 with formatters for common used formats. Available formats styles are `RubyCAS`, `Jasig`
60 and `Name-Value. Default is Jasig style. See module source code for more details.
61
62 CAS_AUTO_REDIRECT_AFTER_LOGOUT - If False (default behavior, specified in CAS protocol)
63 after successful logout notification page will be shown. If it's True, after successful logout will
64 be auto redirect back to service without any notification.
65
66
67 PROTOCOL DOCUMENTATION
68 =====================
69
70 * `CAS Protocol <http://www.jasig.org/cas/protocol>`
71 * `CAS 1 Architecture <http://www.jasig.org/cas/cas1-architecture>`
72 * `CAS 2 Architecture <http://www.jasig.org/cas/cas2-architecture>`
73 * `Proxy Authentication <http://www.jasig.org/cas/proxy-authentication>`
74 * `CAS – Central Authentication Service <http://www.jusfortechies.com/cas/overview.html>`
75 * `Proxy CAS Walkthrough <https://wiki.jasig.org/display/CAS/Proxy+CAS+Walkthrough>`
76
77 PROVIDED VIEWS
78 =============
79
80 login
81 ---------
82
83 It has not required arguments.
84
85 Optional arguments:
86
87 * template_name - login form template name (default is 'cas/login.html')
88 * success_redirect - redirect after successful login if service GET argument is not provided
89    (default is settings.LOGIN_REDIRECT_URL)
90 * warn_template_name - warning page template name to allow login user to service if he
91   already authenticated in SSO (default is 'cas/warn.html')
92
93 If request.GET has 'warn' argument and user has already authenticated in SSO it shows
94 warning message instead of generate Service Ticket and redirect.
95
96 logout
97 -----------
98
99 This destroys a client's single sign-on CAS session. The ticket-granting cookie is destroyed,
100 and subsequent requests to login view will not obtain service tickets until the user again
101 presents primary credentials (and thereby establishes a new single sign-on session).
102
103 It has not required arguments.
104
105 Optional arguments:
106
107 * template_name - template name for page with successful logout message (default is 'cas/logout.html')
108
109 validate
110 -------------
111
112 It checks the validity of a service ticket. It is part of the CAS 1.0 protocol and thus does
113 not handle proxy authentication.
114
115 It has not arguments.
116
117 service_validate
118 -------------------------
119
120 It checks the validity of a service ticket and returns an XML-fragment response via CAS 2.0 protocol.
121 Work with proxy is not supported yet.
122
123 It has not arguments.
124
125
126 CUSTOM USER ATTRIBUTES FORMAT
127 ===========================
128
129 Custom attribute format style may be changed in project settings with 
130 CAS_CUSTOM_ATTRIBUTES_FORMAT constant. You can provide your own formatter callback
131 or specify existing in this package in `attribute_formatters` module.
132
133 Attribute formatter callback takes two arguments:
134
135 *  `auth_success` - `cas:authenticationSuccess` node. It is `lxml.etree.SubElement`instance;
136 *  `attrs` - dictionary with user attributes received from callback specified in 
137     CAS_CUSTOM_ATTRIBUTES_CALLBACK in project settings. 
138
139 Example of generated XML below::
140  
141      <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
142          <cas:authenticationSuccess>
143              <cas:user>jsmith</cas:user>
144
145              <!-- extended user attributes wiil be here -->
146
147              <cas:proxyGrantingTicket>PGTIOU-84678-8a9d2sfa23casd</cas:proxyGrantingTicket>
148          </cas:authenticationSuccess>
149      </cas:serviceResponse>
150
151
152 * Name-Value style (provided in `cas_provider.attribute_formatters.name_value`)::
153
154     <cas:attribute name='attraStyle' value='Name-Value' />
155     <cas:attribute name='surname' value='Smith' />
156     <cas:attribute name='givenName' value='John' />
157     <cas:attribute name='memberOf' value='CN=Staff,OU=Groups,DC=example,DC=edu' />
158     <cas:attribute name='memberOf' value='CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu' />
159
160
161 *  Jasig Style attributes (provided in `cas_provider.attribute_formatters.jasig`)::
162
163     <cas:attributes>
164         <cas:attraStyle>Jasig</cas:attraStyle>
165         <cas:surname>Smith</cas:surname>
166         <cas:givenName>John</cas:givenName>
167         <cas:memberOf>CN=Staff,OU=Groups,DC=example,DC=edu</cas:memberOf>
168         <cas:memberOf>CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu</cas:memberOf>
169     </cas:attributes>
170
171
172 * RubyCAS style (provided in `cas_provider.attribute_formatters.ruby_cas`)::
173
174     <cas:attraStyle>RubyCAS</cas:attraStyle>
175     <cas:surname>Smith</cas:surname>
176     <cas:givenName>John</cas:givenName>
177     <cas:memberOf>CN=Staff,OU=Groups,DC=example,DC=edu</cas:memberOf>
178     <cas:memberOf>CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu</cas:memberOf>
179