X-Git-Url: https://git.mdrn.pl/django-cas-provider.git/blobdiff_plain/4d08fe00954d5a4a3a5d963ff04d001be57f9007..38bde55959257eaef6b76dc3f45424c7d0bd64e8:/README.rst diff --git a/README.rst b/README.rst index bc2874d..e8a53f9 100644 --- a/README.rst +++ b/README.rst @@ -2,30 +2,27 @@ django-cas-provider =================== ---------------------------------- -Chris Williams ---------------------------------- - OVERVIEW ========= -django-cas-provider is a provider for the `Central Authentication -Service `_. 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 `_ -and `Single Sign-On on Wikipedia `_. +django-cas-provider is a provider for the `Central Authentication Service `_. 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 `_ and +`Single Sign-On on Wikipedia `_. 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 ====== @@ -39,8 +36,20 @@ USAGE 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 ===================== @@ -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') -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 ----------- @@ -87,7 +96,7 @@ Optional arguments: 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. It has not arguments. @@ -95,9 +104,72 @@ It has not arguments. 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 not arguments. + +proxy_validate +------------------------- + +It checks the validity of a Proxy Ticket and returns an XML-fragment response via CAS 2.0 protocol. + +proxy +------------------------- +Creates a proxy ticket for a given Proxy Granting Ticket. It has not 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:: + + + + jsmith + + + + PGTIOU-84678-8a9d2sfa23casd + + + + +* Name-Value style (provided in `cas_provider.attribute_formatters.name_value`):: + + + + + + + + +* Jasig Style attributes (provided in `cas_provider.attribute_formatters.jasig`):: + + + Jasig + Smith + John + CN=Staff,OU=Groups,DC=example,DC=edu + CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu + + + +* RubyCAS style (provided in `cas_provider.attribute_formatters.ruby_cas`):: + + RubyCAS + Smith + John + CN=Staff,OU=Groups,DC=example,DC=edu + CN=Spanish Department,OU=Departments,OU=Groups,DC=example,DC=edu +