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