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