Metadata-Version: 1.0
Name: plone.session
Version: 3.0
Summary: Session based authentication for Zope
Home-page: http://pypi.python.org/pypi/plone.session
Author: Plone Foundation
Author-email: plone-developers@lists.sourceforge.net
License: BSD
Description: Overview
        ========
        
        plone.session implements secure session management for Zope sites.
        
        In its default configuration plone.session uses an HMAC_ SHA-256_ secure
        cryptographic hash to authenticate sessions. The hash is generated using the
        userid and a secret stored in the PAS plugin. Otherwise, the cookie
        format is identical to that of Apache's mod_auth_tkt_. For single sign on with
        the original mod_auth_tkt or another compatible implementation, set the
        ``mod_auth_tkt`` property to true. This invokes an MD5_ based double hashing
        scheme. You will need to use the same secret across all servers.
        
        This has several advantages over other session management systems:
        
        * passwords are not sent to the server in a cookie on every request, as
          is done by the *Cookie Auth Helper* 
        * it does not require any ZODB write for sessions, as is needed by the
          *Session Crumbler*. This allows it to scale very well.
        * it allows you to invalidate all existing authentication cookies for
          users by updating the secret.
        * The cookie is only valid for the period specified by the `timeout` property.
        
        There are some downsides to this approach:
        
        * if a user's password is changed or disabled session identifiers will
          continue to work, making it hard to lock out individual users.
        * a user must have cookies enabled.
        
        A session cookie is used to track sessions; that means that as long as
        a user keeps his browser open (and does not explicitly log out) the session
        remains open until the timout limit is reached. This can be changed by setting
        the ``timeout`` property of the plugin to the number of seconds the cookie
        should remain valid *after the moment of login*. 
        
        `tktauth.py` implements the core mod_auth_tkt functionality. It is
        self-contained and may be of useful to other frameworks.
        
        .. _mod_auth_tkt: http://www.openfusion.com.au/labs/mod_auth_tkt/
        .. _MD5: http://en.wikipedia.org/wiki/MD5
        .. _HMAC: http://en.wikipedia.org/wiki/HMAC
        .. _SHA-256: http://en.wikipedia.org/wiki/SHA-256
        
        
        Using plone.session
        ===================
        
        plone.session only takes care of handling sessions for already authenticated
        users. This means it can not be used stand-alone: you need to have another
        PAS plugin, such as the standard *Cookie Auth Helper* to take care of
        authentication.
        
        After a user has been authenticated plone.session can take over via the
        PAS *credentials update* mechanism. 
        
        
        Configuration options
        =====================
        
        To enable logins between sites or other mod_auth_tkt systems, set the shared
        secret through the Zope Management Interface. You can manage the plone.keyring
        secrets through the same page.
        
        The following properties may be set through the Properties tab:
        
          Cookie validity timeout (in seconds)
            After this, the session is invalid and the user must login again. Set to 0
            for the cookie to remain valid indefinitely. Note that when the user
            folder has caching enabled, cookie validity may not be checked on every
            request.
        
          Use mod_auth_tkt compatabile hashing algorithm
            Compatibility with other implemenations, but at the cost of using a weaker
            hashing algorithm.
        
          Cookie name
            Which cookie to use. This must also be set on the
            ``credentials_cookie_auth`` plugin.
        
          Cookie lifetime (in days)
            This makes the cookie persistent across opening and closing the browser.
        
          Cookie domain (blank for default)
            A cookie may be shared across www1.example.com and www2.example.com by
            setting the cookie domain to ``.example.com``.
        
          Cookie path
            What path the cookie is set valid (defaults to ``/``.)
        
        
        Single Sign On with IIS
        =======================
        
        For intranet setups with users on a Windows domain, it's possible to configure IIS with `Integrated Windows Authentication` to act as an external login provider, even for sites running on Linux/Unix servers.
        
        
        Requirements
        ------------
        
        - You need a Microsoft Windows Server running IIS. Preferably Windows Server
          2003 or a later version.
        
        - The server must be a member of the Windows domain you want to authenticate
          users for. It does not need to be an Active Directory server itself.
        
        - You site should use LDAPMultiPlugins_ to use the same Active Directory as a
          user source. (Use plone.app.ldap_ to set this up with Plone.)
        
        .. _LDAPMultiPlugins: http://pypi.python.org/pypi/Products.LDAPMultiPlugins
        .. _plone.app.ldap: http://pypi.python.org/pypi/plone.app.ldap
        
        
        Python
        ------
        
        - The Windows server needs to have `Python 2.6
          <http://www.python.org/download/>` and the `Python Win 32 extensions
          <http://sourceforge.net/projects/pywin32/files/>`_ installed. (Currently
          Python 2.6.5 and pywin32-214.)
        
        - Until pywin32-215 is released, apply this `fix
          <http://mail.python.org/pipermail/python-win32/2009-October/009639.html>`_
          to the file::
        
            C:\Python26\Lib\site-packages\win32comext\axscript\client\framework.py
        
          and remove the framework.pyc and framework.pyo files.
        
        - Place a copy of ``tktauth.py`` (from plone/session of this package) into::
        
            C:\Python26\Lib\site-packages\
        
        - Follow these `instructions on how to configure Python for IIS
          <http://support.microsoft.com/kb/276494>`_. In bullet point 2.d. use::
        
            Executable: "C:\Python26\python.exe -u %s %s"
        
          instead. This will ensure files are opened in universal newline mode. You
          can choose to only configure these settings for the specific web site and
          not the entire IIS. Adjust settings accordingly and create the web site
          first as detailed in the next chapter.
        
        
        IIS
        ---
        
        - Find and open the IIS management console.
        
        - Create a new `Web Site`, by going into the `Web Sites` folder and using the
          right-click menu. You should get a wizard asking you for various questions::
        
            Description: SSO login service
        
            TCP port: 80
        
            Path: c:\Inetpub\sso
        
            Allow anonymous access to this Web site: <not checked>
        
            Permissions: Read, Run scripts, Execute
        
        - If you are running IIS 6, you need to go to the `Web Service Extensions`
          folder and change `Active Server Pages` to be `Allowed`. Otherwise you
          will get rather unhelpful `404 Not Found` errors for the asp scripts.
        
        
        IIS script
        ----------
        
        - Copy the `login.asp` and `test.asp` scripts (from the iis-login folder of
          this package) into root path of the web site (for example C:\Inetpub\sso).
        
        - You need to modify the `SECRET` constant found in the `login.asp` to the
          same shared secret set on plone.session's `Manage secrets` tab.
        
        - Modify the `SITE_URL` constant in `login.asp` ot the address our your Plone
          site.
        
        - Access http://LOGONSERVER/test.asp to confirm access permissions are
          correctly configured.
        
        
        Configuring browsers to allow automatic logon
        ---------------------------------------------
        
        Browsers must be configured to "trust" the logon server for user
        authentication data to be sent automatically.
        
        By default, Internet Explorer sends logon information to servers within the
        "Intranet Zone", so long as the site is accessed using it's intranet name
        (http://LOGONSERVER/login.asp). If the site is accessed using a fully
        qualified domain name or IP address, it must be explicitly added to the list
        of `trusted sites <http://support.microsoft.com/kb/174360>`_.
        
        Firefox configuration information may be found in this `article
        <http://support.mozilla.com/en-US/kb/Firefox+asks+for+user+name+and+password+on+internal+sites>`_.
        
        
        Configuring your Plone site
        ---------------------------
        
        Ensure that you have setup authentication to Active Directory and that you can
        login with the your current Windows user name.
        
        Set the following configuration options through the Zope interface:
        
        - In `/Plone/acl_users/session`. On the `Manage secrets`
        
        - In `/Plone/acl_users/credentials_cookie_auth`. On the `Properties` tab set
          `Login Form` to `http://LOGONSERVER/login.asp`
        
        - In `/Plone/portal_actions/user/login`. On the `Properties` tab set `URL
          (Expression)` to
          `python:portal.acl_users.credentials_cookie_auth.getProperty('login_path')`.
        
        
        Note for developers testing this under Windows XP
        -------------------------------------------------
        
        - IIS may be installed as an additional component using the Windows XP
          installation CD.
        
        - The IIS management console can be located at::
        
            Start -> Control Panel -> Adminstrative Tools -> Internet Information Services
        
        - The pywin32 installer setup IIS sufficiently for me not to need to follow
          the `instructions on how to configure Python for IIS`.
        
        - I could not find how to setup a separate site, so placed the asp scripts
          directly in C:\Inetpub\wwwroot - the "Default Web Site"
        
        - From the IIS management console, select "Default Web Site". You should see
          `login.asp` and `test.asp` in the right hand pane. With each file,
          right-click Properties. On the `File Security` tab click Edit... on
          `Anonymous access and authentication control`. Uncheck `Anonymous access`
          and check `Basic authentication` (to be used as a fallback) and `Integrated
          Windows authentication`.
        
        - Access http://localhost/test.asp to confirm IIS authentication works as
          expected.
        
        - Set the secret in `login.asp` and `Manage secrets` of plone.session.
        
        - Set SITE_URL in `login.asp` to `http://localhost:8080/Plone` (or whatever
          the address of your site is.)
        
        - Add a Plone user with the same name as your Windows login name (e.g.
          Administrator), this avoids setting up Active Directory.
        
        - Follow the section above to configure your Plone site, but set `Login Form`
          to `http://localhost/login.asp`.
        
        Changelog
        =========
        
        3.0 - 2010-07-18
        ----------------
        
        - Update package metadata.
          [hannosch]
        
        3.0b5 - 2010-06-13
        ------------------
        
        - Make sure to load the right meta ZCML.
          [hannosch]
        
        - Avoid deprecation warnings under Zope 2.13.
          [hannosch]
        
        - Removed dependency on GPL licensed Products.PloneTestCase.
          [hannosch]
        
        3.0b4 - 2010-05-23
        ------------------
        
        - Make the ``secure`` option of cookies configurable. This allows to restrict
          cookies to HTTPS connections alone. This closes
          http://dev.plone.org/plone/ticket/7897.
          [pfurman, hannosch]
        
        - Use the standard libraries doctest module, instead of the deprecated one
          from zope.testing.
          [hannosch]
        
        - Marked the session cookie as ``HTTPOnly``.
          [hannosch]
        
        - PEP8 cleanup.
          [hannosch]
        
        - Relicense as BSD following PF Board decision.
          http://lists.plone.org/pipermail/membership/2010-April/001123.html
          [elro]
        
        3.0b3 - 2010-04-09
        ------------------
        
        - Example IIS login form and documentation. This builds on work by Hanno and I
          at Jarn for Centrepoint.
          [elro]
        
        - Support authentication by an external form, perhaps one running on an IIS
          server with Integrated Windows Authentication.
          [elro]
        
        3.0b2 - 2010-03-09
        ------------------
        
        - Prefix setupSession with underscore, the method should be unavailable TTW.
          [elro]
        
        - Catch a ComponentLookupError in authenticateCredentials.
          [elro]
        
        3.0b1 - 2010-03-05
        ------------------
        
        - Add back the hash management UI with added functionality to set shared
          secret.
          [elro]
        
        - Add properties for cookie domain and ticket validity timeout.
          [elro]
        
        - Use mod_auth_tkt format cookies to give us a session validity timeout.
          By default we use a more secure HMAC SHA-256 hashing scheme. An MD5 based
          scheme compatible with other mod_auth_tkt implementations is optional.
          [elro]
        
        - Remove the source component indirection.
          [elro]
        
        3.0a2 - 2009-11-13
        ------------------
        
        - Remove hash management UI which had been accidentally re-merged.
          [davisagli]
        
        3.0a1 - 2009-04-04
        ------------------
        
        - Avoid deprecation warning for the sha module in Python 2.6.
          [hannosch]
        
        - Declare test dependencies in an extra.
          [hannosch]
        
        - Specify package dependencies.
          [hannosch]
        
        - Fixed the remaining tests to work with the new keyring backend.
          [hannosch]
        
        - Fixed a component lookup call in the HashSession source.
          [davisagli, hannosch]
        
        - Update default (hash) session source to use plone.keyring to manage
          the secrets.
          [wichert]
        
        2.1 - 2009-02-04
        ----------------
        
        - Protect the setupSession call with the ManageUsers permission.
          Fixes possible privilege escalation.
          [maurits]
        
        - Make the cookie lifetime configurable. Patch by Rok Garbas. Fixes
          http://dev.plone.org/plone/ticket/7248
          [wichert, garbas]
        
        2.0 - 2008-07-08
        ----------------
        
        - Fix CSRF protection for managing server secrets via the Plone session
          plugin for PAS. Fixes http://dev.plone.org/plone/ticket/8176
          [witsch]
        
        1.2 - 2007-02-15
        ----------------
        
        - Use the binascii base64 methods to encode/decode the session cookie. This
          prevents newlines being inserted in long cookies.
          [wichert]
        
        1.1 - 2007-09-11
        ----------------
        
        - Use the userid instead of the login name in session identifiers. This
          has the side-effect of working around a bug in PAS which caused us to
          mix up users when the login name used was an inexact match for another
          login name.
          [wichert]
        
        1.0 - 2007-08-15
        ----------------
        
        - First stable release
          [wichert]
        
Keywords: PAS session authentication Zope
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Zope2
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
