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