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 USAGE
  31 ======
  32
  33 #. Add ``'cas_provider'`` to your ``INSTALLED_APPS`` tuple in *settings.py*.
  34 #. In *settings.py*, set ``LOGIN_URL`` to ``'/cas/login/'`` and ``LOGOUT_URL`` to ``'/cas/logout/'``
  35 #. In *urls.py*, put the following line: ``(r'^cas/', include('cas_provider.urls')),``
  36 #. Create login/logout templates (or modify the samples)
  37 #. Use 'cleanuptickets' management command to clean up expired tickets
  38
  39 SETTINGS
  40 =========
  41
  42 CAS_TICKET_EXPIRATION - minutes to tickets expiration (default is 5 minutes)
  43 CAS_CHECK_SERVICE - check if ticket service is equal with service GET argument
  44
  45 PROTOCOL DOCUMENTATION
  46 =====================
  47
  48 * `CAS Protocol <http://www.jasig.org/cas/protocol>`
  49 * `CAS 1 Architecture <http://www.jasig.org/cas/cas1-architecture>`
  50 * `CAS 2 Architecture <http://www.jasig.org/cas/cas2-architecture>`
  51 * `Proxy Authentication <http://www.jasig.org/cas/proxy-authentication>`
  52 * `CAS – Central Authentication Service <http://www.jusfortechies.com/cas/overview.html>`
  53 * `Proxy CAS Walkthrough <https://wiki.jasig.org/display/CAS/Proxy+CAS+Walkthrough>`
  54
  55 PROVIDED VIEWS
  56 =============
  57
  58 login
  59 ---------
  60
  61 It has not required arguments.
  62
  63 Optional arguments:
  64
  65 * template_name - login form template name (default is 'cas/login.html')
  66 * success_redirect - redirect after successful login if service GET argument is not provided
  67    (default is settings.LOGIN_REDIRECT_URL)
  68 * warn_template_name - warning page template name to allow login user to service if he
  69   already authenticated in SSO (default is 'cas/warn.html')
  70
  71 If request.GET has 'warn' argument - it shows warning message if user has already
  72 authenticated in SSO instead of generate Service Ticket and redirect.
  73
  74 logout
  75 -----------
  76
  77 This destroys a client's single sign-on CAS session. The ticket-granting cookie is destroyed,
  78 and subsequent requests to login view will not obtain service tickets until the user again
  79 presents primary credentials (and thereby establishes a new single sign-on session).
  80
  81 It has not required arguments.
  82
  83 Optional arguments:
  84
  85 * template_name - template name for page with successful logout message (default is 'cas/logout.html')
  86
  87 validate
  88 -------------
  89
  90 It checks the validity of a service ticket. It is part of the CAS 1.0 protocol and thus does
  91 not handle proxy authentication.
  92
  93 It has not arguments.
  94
  95 service_validate
  96 -------------------------
  97
  98 It checks the validity of a service ticket and returns an XML-fragment response via CAS 2.0 protocol.
  99 Work with proxy is not supported yet.
 100
 101 It has not arguments.
 102
 103