X-Git-Url: https://git.mdrn.pl/django-cas-provider.git/blobdiff_plain/f8a6477e0cf670ed665c862f5d63490280f7df66..4a479a2031c6d6f96c876e09f6792f96a36da134:/README.rst diff --git a/README.rst b/README.rst index 0ef1742..258d685 100644 --- a/README.rst +++ b/README.rst @@ -5,26 +5,43 @@ django-cas-provider 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 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 +(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. +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. +UPDATING FROM PREVIOUS VERSION +=============================== + +I introduced south for DB schema migration. The schema from any previous version without south is 0001_initial. +You will get an error: + + ``Running migrations for cas_provider:`` + + ``- Migrating forwards to 0001_initial.`` + + ``> cas_provider:0001_initial`` + + ``Traceback (most recent call last):`` + + ``...`` + + ``django.db.utils.DatabaseError: relation "cas_provider_serviceticket" already exists`` + +to circumvent that problem you will need to fake the initial migration: + + python manage.py migrate cas_provider 0001_initial --fake + + USAGE ====== @@ -39,7 +56,7 @@ SETTINGS CAS_TICKET_EXPIRATION - minutes to tickets expiration. Default is 5 minutes. -CAS_CUSTOM_ATTRIBUTES_CALLBACK - name of callback to provide dictionary with +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 @@ -47,6 +64,10 @@ used to format custom user attributes. This package provide module `attribute_fo 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 ===================== @@ -69,18 +90,18 @@ It has not required arguments. Optional arguments: * template_name - login form template name (default is 'cas/login.html') -* success_redirect - redirect after successful login if service GET argument is not provided +* success_redirect - redirect after successful login if service GET argument is not provided (default is settings.LOGIN_REDIRECT_URL) * 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 and user has already authenticated in SSO it shows +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 ----------- -This destroys a client's single sign-on CAS session. The ticket-granting cookie is destroyed, +This destroys a client's single sign-on CAS session. The ticket-granting cookie is destroyed, and subsequent requests to login view will not obtain service tickets until the user again presents primary credentials (and thereby establishes a new single sign-on session). @@ -96,7 +117,7 @@ validate 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. +It has not arguments. service_validate ------------------------- @@ -120,7 +141,7 @@ Attribute formatter callback takes two arguments: * `attrs` - dictionary with user attributes received from callback specified in CAS_CUSTOM_ATTRIBUTES_CALLBACK in project settings. -Example of generated XML below: +Example of generated XML below:: @@ -133,7 +154,7 @@ Example of generated XML below: -* Name-Value style (provided in `cas_provider.attribute_formatters.name_value`): +* Name-Value style (provided in `cas_provider.attribute_formatters.name_value`):: @@ -142,7 +163,7 @@ Example of generated XML below: -* Jasig Style attributes (provided in `cas_provider.attribute_formatters.jasig`): +* Jasig Style attributes (provided in `cas_provider.attribute_formatters.jasig`):: Jasig @@ -153,7 +174,7 @@ Example of generated XML below: -* RubyCAS style (provided in `cas_provider.attribute_formatters.ruby_cas`): +* RubyCAS style (provided in `cas_provider.attribute_formatters.ruby_cas`):: RubyCAS Smith