repoze.who.plugins.cas 0.2.2
CAS plugin for repoze.who by Makina Corpus
License: BSD
Keywords: cas authentication server web wsgi repoze repoze.who sponsorised by Makina Corpus

Introduction
============

.. contents::

``repoze.who.plugins.cas`` is a plugin for the `repoze.who framework
<http://docs.repoze.org/who/>`_ that enables Single Sign-On (SSO)
for applications via a Central Authentication Service (CAS) server.

.. image:: https://secure.travis-ci.org/kiorky/repoze.who.plugins.cas.png
    :target: http://travis-ci.org/kiorky/repoze.who.plugins.cas


The plugin follows the protocols described
in the `official documentation <http://www.jasig.org/cas/protocol>`_ for
login, ticket validation, and logout. The plugin has been tested against
instances of CAS 3.0+ servers.

Compatibility Note
------------------

Whilst the plugin supports both CAS 1.0- and CAS 2.0-style service ticket
validation, the plugin has currently only been tested against instances of
CAS 3.0+ servers.  Backwards compatibility is unknown at the point and
assistance testing this plugin is welcomed.

Potential Applications
----------------------

Applications which can be used :

- Apps complying with the `simple_authentication WSGI specification
  <http://wsgi.org/wsgi/Specifications/simple_authentication>`_, which take
  advantage of the REMOTE_USER key in the WSGI environment.
- Custom applications that utilise the ``repoze.who`` environment
  variables present within a WSGI request.
- Apps which can handle themselves the CAS mechanism (for example: phpBB
  with the CAS patch, using ``wphp`` as a Paste filter for integration of
  PHP with Python),

Links
-----

- `Official link for CAS <http://www.jasig.org/cas>`_

Development
-----------

To run the test suite, clone this project from source code hosting and
run the following::

    cd repoze.who.plugins.cas
    python bootstrap.py
    ./bin/buildout
    ./bin/test

Credits
-------

|makinacom|_

* `Planet Makina Corpus <http://www.makina-corpus.org>`_
* `Contact us <mailto:python@makina-corpus.org>`_

.. |makinacom| image:: http://depot.makina-corpus.org/public/logo.gif
.. _makinacom:  http://www.makina-corpus.com


Documentation
=============





Installing
==========

Requirement
------------

You must have a CAS server working and you will need to know the URL to your
CAS server.  Typically, this will be the part of the URL before your
``/login`` or ``/logout`` URLs for CAS.  For example::

    https://example.edu/cas/

All URLs for CAS login, validation, and logout will be built using this
address.

CAS
---

You must ensure that logout is enabled on your CAS server.
Typically, this involves adding::

    <property name="followServiceRedirects" value="true" />

into the ``LogoutController`` bean in your ``cas-servlet.xml`` file.
Ask your system administrator if you're unsure about the above.

Attribute release
-----------------

If your CAS server supports it, this plugin can parse and capture 
user metadata attributes being released during the CAS ticket validation
process. By specifying an identifer for ``attributes_name`` in the plugin
configuration, attributes released from CAS will be stored into the
``repoze.who`` identity within the given environment.  Given the way
CAS works, you will need to cache or store this information within your
application (or use another ``repoze.who`` plugin to do it for you), as 
this data is only associated with a user's initial CAS request.

A suite of plugins exists for precisely this reason and can be found at
https://pypi.python.org/pypi/repoze.who.plugins.metadata_cache

You can always customise your own method of managing this metadata, too.
As mentioned, you can find the retrieved attributes within the ``repoze.who``
identity within the specific request that triggers the CAS authentication.

Your apps
---------

Nothing is required within your apps, just set them up and configure 
``repoze.who`` accordingly.  You may like to follow the example 
configuration file as seen in the ``config_example/`` directory.
This is what the ``who.ini`` configuration file looks like::

    # IDENTIFIER
    # @param :
    # - cas_url : URL to your CAS server. Ensure your URL has a trailing slash.
    # - cas_version : Version of your CAS server. Affects how the CAS protocol
    #                 is followed.
    # - rememberer_name : name of the plugin for remembering (delegate)
    # - attributes_name : identifier for where to place CAS-sources metadata
    #                     inside the ``repoze.who`` identity.
    # - path_toskip : regex for URLs handling authentication to CAS separately
    # - path_logout : regex for URLS that should be trigger a logout
    #                 WARNING: you must include the path of logout even 
    #                 it is present within ``path_toskip``.
    [plugin:casauth]
    use = repoze.who.plugins.cas.main_plugin:make_plugin
    cas_url= https://servcas:8443/cas/
    cas_version = 3.0
    rememberer_name = auth_tkt
    attributes_name = attributes
    path_toskip = .*/phpbb/.*
    path_logout = .*/logout.*
                  .*mode=logout.*

    
    # CHALLENGE DECIDER
    # @param:
    # - path_login : those regexp indicate which url should be redirected for a challenge 
    #                e.g. : for CAS, will be redirected on a "/cas/login" like url
    [plugin:decider]
    use = repoze.who.plugins.cas.challenge_decider:make_plugin
    path_login = 
                .*trac/login.*
                .*/login$ 

    
    [plugin:auth_tkt]
    # identification
    use = repoze.who.plugins.auth_tkt:make_plugin
    secret = secret
    cookie_name = oatmeal
    secure = False
    include_ip = False
    
    [general]
    request_classifier = repoze.who.classifiers:default_request_classifier
    remote_user_key = REMOTE_USER
    # trick : target the plugin whose name is the same
    challenge_decider = decider
    
    
    [identifiers]
    # plugin_name;classifier_name:.. or just plugin_name (good for any)
    plugins =
          casauth
          auth_tkt
    
    [authenticators]
    # plugin_name;classifier_name.. or just plugin_name (good for any)
    plugins =
          casauth
    
    
    [challengers]
    # plugin_name;classifier_name:.. or just plugin_name (good for any)
    plugins =
          casauth
    
Using the above configuration will see the given application receive the
remote user's name as the ``REMOTE_USER`` environment variable


To Do
=====

* *More tests*: Add additional deployment scenarios for applications
* *Handle Single Sign-Out*: 

  At this point, this plugin does not handle Single Sign Out.
  There may be several ways to achieve this:

  - A simple solution may be found by enabling the plugin to execute each
    callable delivered by webapp whose purpose would be to logout the 
    user from it (e.g: by redirecting the browser on the logout url, 
    or deleting some cookies etc.).

  - Currently, CAS 3 and higher handle SSOut by triggering a POST 
    request to all the web application registered. 

* *Genericising the code*:  At the moment, the plugin relies on a CAS 
  server.  However, CAS is simply a specific trusted third party (like
  Kerberos etc.).  So, to avoid redundancy between plugins, abstract away
  "trusted third party" authentication code and refactory.



Known Issues
============

* None at present.



Changes
=======

0.2.2 (2013-04-25)
------------------

- Documentation markup fixes

0.2.0 (2013-04-24)
------------------------------

 - Review davidjb changes, cleanify the buildout infra, travis setup [kiorky]
 - Support obtaining user attributes (metadata) via CAS 2.0 service
   validation (``/serviceValidation``) and parsing the XML response.
   User attributes will be placed into the repoze.who identity
   using the key ``attributes_name`` after the ticket validation
   process.  Due to how CAS works, the data must be either saved or cached
   by another plugin to allow persistance beyond the request
   that triggered the ticket validation.  See documentation for more info.
   [davidjb]
 - Support specifying a CAS version. This will control what version of
   the CAS protocol (http://www.jasig.org/cas/protocol) to use.
   [davidjb]
 - Precompile regex statements from configuration to avoid needing
   to recompile during every request.
   [davidjb]
 - Clean up debug process. Debugging is now possible by configuring the
   ``debug`` plugin keyword.
   [davidjb]
 - Clean up identification process to remove need for ``bhp`` in query
   string.
   [davidjb]
 - Switch use of paste HTTPFound for webob, following repoze.who.
   [davidjb]
 - Add Buildout boostrap and configuration for running tests.
   [davidjb]
 - Documentation clean up for clarity.
   [davidjb]
 - Code spring cleaning and documentation expansion. Code now requires
   Python 2.6 and works towards Python 3 compatibility (not guaranteed
   at present).
   [davidjb]

0.1.2 (2012-01-13)
------------------

 - Minor additions to example configuration about CAS URL and auth_tkt
   plugin.
   [davidjb]

0.1 (2009-07-28)
----------------
Initial release.

 - Provides repoze.who plugins (i.e.: challenge, identifier, chalenge decider and
   auth plugins) for enabling CAS
 - Provides simple unit tests