9e922c6ce892e1bf489c4c3e39d6eefa466813d5
[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         
23 USAGE
24 ======
25
26 #. Add ``'cas_provider'`` to your ``INSTALLED_APPS`` tuple in *settings.py*.
27 #. In *settings.py*, set ``LOGIN_URL`` to ``'/cas/login/'`` and ``LOGOUT_URL`` to ``'/cas/logout/'``
28 #. In *urls.py*, put the following line: ``(r'^cas/', include('cas_provider.urls')),``
29 #. Create login/logout templates (or modify the samples)
30 #. Use 'cleanuptickets' management command to clean up expired tickets
31
32 SETTINGS
33 =========
34
35 CAS_TICKET_EXPIRATION - minutes to tickets expiration. Default is 5 minutes.
36
37 CAS_CUSTOM_ATTRIBUTES_CALLBACK - name of callback to provide dictionary with 
38 extended user attributes (may be used in CAS v.2 or above). Default is None.
39
40 CAS_CUSTOM_ATTRIBUTES_FORMAT - name of custom attribute formatter callback will be
41 used to format custom user attributes. This package provide module `attribute_formatters`
42 with formatters for common used formats. Available formats styles are `RubyCAS`, `Jasig`
43 and `Name-Value. Default is Jasig style. See module source code for more details.
44
45
46 PROTOCOL DOCUMENTATION
47 =====================
48
49 * `CAS Protocol <http://www.jasig.org/cas/protocol>`
50 * `CAS 1 Architecture <http://www.jasig.org/cas/cas1-architecture>`
51 * `CAS 2 Architecture <http://www.jasig.org/cas/cas2-architecture>`
52 * `Proxy Authentication <http://www.jasig.org/cas/proxy-authentication>`
53 * `CAS – Central Authentication Service <http://www.jusfortechies.com/cas/overview.html>`
54 * `Proxy CAS Walkthrough <https://wiki.jasig.org/display/CAS/Proxy+CAS+Walkthrough>`
55
56 PROVIDED VIEWS
57 =============
58
59 login
60 ---------
61
62 It has not required arguments.
63
64 Optional arguments:
65
66 * template_name - login form template name (default is 'cas/login.html')
67 * success_redirect - redirect after successful login if service GET argument is not provided 
68    (default is settings.LOGIN_REDIRECT_URL)
69 * warn_template_name - warning page template name to allow login user to service if he
70   already authenticated in SSO (default is 'cas/warn.html')
71
72 If request.GET has 'warn' argument and user has already authenticated in SSO it shows 
73 warning message instead of generate Service Ticket and redirect.
74
75 logout
76 -----------
77
78 This destroys a client's single sign-on CAS session. The ticket-granting cookie is destroyed, 
79 and subsequent requests to login view will not obtain service tickets until the user again
80 presents primary credentials (and thereby establishes a new single sign-on session).
81
82 It has not required arguments.
83
84 Optional arguments:
85
86 * template_name - template name for page with successful logout message (default is 'cas/logout.html')
87
88 validate
89 -------------
90
91 It checks the validity of a service ticket. It is part of the CAS 1.0 protocol and thus does
92 not handle proxy authentication.
93
94 It has not arguments. 
95
96 service_validate
97 -------------------------
98
99 It checks the validity of a service ticket and returns an XML-fragment response via CAS 2.0 protocol.
100 Work with proxy is not supported yet.
101
102 It has not arguments.
103
104
105 CUSTOM USER ATTRIBUTES FORMAT
106 ===========================
107
108 Custom attribute format style may be changed in project settings with 
109 CAS_CUSTOM_ATTRIBUTES_FORMAT constant. You can provide your own formatter callback
110 or specify existing in this package in `attribute_formatters` module.
111
112 Attribute formatter callback takes two arguments:
113
114 *  `auth_success` - `cas:authenticationSuccess` node. It is `lxml.etree.SubElement`instance;
115 *  `attrs` - dictionary with user attributes received from callback specified in 
116     CAS_CUSTOM_ATTRIBUTES_CALLBACK in project settings. 
117
118 Example of generated XML below::
119  
120      <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
121          <cas:authenticationSuccess>
122              <cas:user>jsmith</cas:user>
123
124              <!-- extended user attributes wiil be here -->
125
126              <cas:proxyGrantingTicket>PGTIOU-84678-8a9d2sfa23casd</cas:proxyGrantingTicket>
127          </cas:authenticationSuccess>
128      </cas:serviceResponse>
129
130
131 * Name-Value style (provided in `cas_provider.attribute_formatters.name_value`)::
132
133     <cas:attribute name='attraStyle' value='Name-Value' />
134     <cas:attribute name='surname' value='Smith' />
135     <cas:attribute name='givenName' value='John' />
136     <cas:attribute name='memberOf' value='CN=Staff,OU=Groups,DC=example,DC=edu' />
137     <cas:attribute name='memberOf' value='CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu' />
138
139
140 *  Jasig Style attributes (provided in `cas_provider.attribute_formatters.jasig`)::
141
142     <cas:attributes>
143         <cas:attraStyle>Jasig</cas:attraStyle>
144         <cas:surname>Smith</cas:surname>
145         <cas:givenName>John</cas:givenName>
146         <cas:memberOf>CN=Staff,OU=Groups,DC=example,DC=edu</cas:memberOf>
147         <cas:memberOf>CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu</cas:memberOf>
148     </cas:attributes>
149
150
151 * RubyCAS style (provided in `cas_provider.attribute_formatters.ruby_cas`)::
152
153     <cas:attraStyle>RubyCAS</cas:attraStyle>
154     <cas:surname>Smith</cas:surname>
155     <cas:givenName>John</cas:givenName>
156     <cas:memberOf>CN=Staff,OU=Groups,DC=example,DC=edu</cas:memberOf>
157     <cas:memberOf>CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu</cas:memberOf>
158