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