fnp / django-cas-provider.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
using south for db migrations
[django-cas-provider.git] / README.rst
diff --git a/README.rst b/README.rst
index bc2874d..a2bd475 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -2,30 +2,27 @@
 django-cas-provider
 ===================
 
 django-cas-provider
 ===================
 
----------------------------------
-Chris Williams <chris@nitron.org>
----------------------------------
-
 OVERVIEW
 =========
 
 OVERVIEW
 =========
 
-django-cas-provider is a provider for the `Central Authentication 
-Service <http://jasig.org/cas>`_. It supports CAS version 1.0. It allows 
-remote services to authenticate users for the purposes of 
-Single Sign-On (SSO). For example, a user logs into a CAS server 
-(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>`_.
+django-cas-provider is a provider for the `Central Authentication Service <http://jasig.org/cas>`_. It supports 
+CAS version 1.0 and 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 (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>`_.
 
 INSTALLATION
 =============
 
 
 INSTALLATION
 =============
 
-To install, run the following command from this directory:
+To install, run the following command from this directory::
+
+    python setup.py install
 
 
-       ``python setup.py install``
+Or, put `cas_provider` somewhere on your Python path.
+
+If you want use CAS v.2 protocol or above, you must install `lxml` package to correct work.
 
 
-Or, put cas_provider somewhere on your Python path.
        
 USAGE
 ======
        
 USAGE
 ======
@@ -39,8 +36,20 @@ USAGE
 SETTINGS
 =========
 
 SETTINGS
 =========
 
-CAS_TICKET_EXPIRATION - minutes to tickets expiration (default is 5 minutes)
-CAS_CHECK_SERVICE - check if ticket service is equal with service GET argument
+CAS_TICKET_EXPIRATION - minutes to tickets expiration. Default is 5 minutes.
+
+CAS_CUSTOM_ATTRIBUTES_CALLBACK - name of callback to provide dictionary with 
+extended user attributes (may be used in CAS v.2 or above). Default is None.
+
+CAS_CUSTOM_ATTRIBUTES_FORMAT - name of custom attribute formatter callback will be
+used to format custom user attributes. This package provide module `attribute_formatters`
+with formatters for common used formats. Available formats styles are `RubyCAS`, `Jasig`
+and `Name-Value. Default is Jasig style. See module source code for more details.
+
+CAS_AUTO_REDIRECT_AFTER_LOGOUT - If False (default behavior, specified in CAS protocol)
+after successful logout notification page will be shown. If it's True, after successful logout will
+be auto redirect back to service without any notification.
+
 
 PROTOCOL DOCUMENTATION
 =====================
 
 PROTOCOL DOCUMENTATION
 =====================
@@ -68,8 +77,8 @@ Optional arguments:
 * warn_template_name - warning page template name to allow login user to service if he
   already authenticated in SSO (default is 'cas/warn.html')
 
 * warn_template_name - warning page template name to allow login user to service if he
   already authenticated in SSO (default is 'cas/warn.html')
 
-If request.GET has 'warn' argument - it shows warning message if user has already
-authenticated in SSO instead of generate Service Ticket and redirect.
+If request.GET has 'warn' argument and user has already authenticated in SSO it shows 
+warning message instead of generate Service Ticket and redirect.
 
 logout
 -----------
 
 logout
 -----------
@@ -87,17 +96,83 @@ Optional arguments:
 validate
 -------------
 
 validate
 -------------
 
-It checks the validity of a service ticket. It is part of the CAS 1.0 protocol and thus does
+It checks the validity of a Service ticket. It is part of the CAS 1.0 protocol and thus does
 not handle proxy authentication.
 
 not handle proxy authentication.
 
-It has not arguments. 
+It has no arguments. 
 
 service_validate
 -------------------------
 
 
 service_validate
 -------------------------
 
-It checks the validity of a service ticket and returns an XML-fragment response via CAS 2.0 protocol.
-Work with proxy is not supported yet.
+It checks the validity of a Service Ticket and returns an XML-fragment response via CAS 2.0 protocol.
+
+It has no arguments.
+
+proxy_validate
+-------------------------
+
+It checks the validity of a Proxy Ticket and returns an XML-fragment response via CAS 2.0 protocol.
+
+It has no arguments.
+
+proxy
+-------------------------
+Creates a proxy ticket for a given Proxy Granting Ticket.
+
+It has no arguments.
+
+
+CUSTOM USER ATTRIBUTES FORMAT
+===========================
+
+Custom attribute format style may be changed in project settings with 
+CAS_CUSTOM_ATTRIBUTES_FORMAT constant. You can provide your own formatter callback
+or specify existing in this package in `attribute_formatters` module.
+
+Attribute formatter callback takes two arguments:
+
+*  `auth_success` - `cas:authenticationSuccess` node. It is `lxml.etree.SubElement`instance;
+*  `attrs` - dictionary with user attributes received from callback specified in 
+    CAS_CUSTOM_ATTRIBUTES_CALLBACK in project settings. 
+
+Example of generated XML below::
+ 
+     <cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
+         <cas:authenticationSuccess>
+             <cas:user>jsmith</cas:user>
+
+             <!-- extended user attributes wiil be here -->
+
+             <cas:proxyGrantingTicket>PGTIOU-84678-8a9d2sfa23casd</cas:proxyGrantingTicket>
+         </cas:authenticationSuccess>
+     </cas:serviceResponse>
+
+
+* Name-Value style (provided in `cas_provider.attribute_formatters.name_value`)::
+
+    <cas:attribute name='attraStyle' value='Name-Value' />
+    <cas:attribute name='surname' value='Smith' />
+    <cas:attribute name='givenName' value='John' />
+    <cas:attribute name='memberOf' value='CN=Staff,OU=Groups,DC=example,DC=edu' />
+    <cas:attribute name='memberOf' value='CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu' />
+
+
+*  Jasig Style attributes (provided in `cas_provider.attribute_formatters.jasig`)::
+
+    <cas:attributes>
+        <cas:attraStyle>Jasig</cas:attraStyle>
+        <cas:surname>Smith</cas:surname>
+        <cas:givenName>John</cas:givenName>
+        <cas:memberOf>CN=Staff,OU=Groups,DC=example,DC=edu</cas:memberOf>
+        <cas:memberOf>CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu</cas:memberOf>
+    </cas:attributes>
+
 
 
-It has not arguments.
+* RubyCAS style (provided in `cas_provider.attribute_formatters.ruby_cas`)::
 
 
+    <cas:attraStyle>RubyCAS</cas:attraStyle>
+    <cas:surname>Smith</cas:surname>
+    <cas:givenName>John</cas:givenName>
+    <cas:memberOf>CN=Staff,OU=Groups,DC=example,DC=edu</cas:memberOf>
+    <cas:memberOf>CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu</cas:memberOf>
 
 
Unnamed repository; edit this file 'description' to name the repository.