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