Changeset 128

Show
Ignore:
Timestamp:
09/30/07 18:11:20
Author:
thejimmyg
Message:

Documentation fixes

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • AuthKit/trunk/AuthKit.egg-info/PKG-INFO

    r125 r128  
    11Metadata-Version: 1.0 
    22Name: AuthKit 
    3 Version: 0.4.0dev-r124 
     3Version: 0.4.0-r127 
    44Summary: An authentication and authorization toolkit for WSGI applications and frameworks 
    55Home-page: http://authkit.org/ 
    …… 
    88License: MIT 
    99Description:  
     10        AuthKit 
     11        +++++++ 
     12         
     13        .. contents :: 
     14         
     15        Summary 
     16        ======= 
     17         
    1018        *   Built for WSGI applications and middleware 
    1119        *   Sophisticated and extensible permissions system 
    12         *   Built in support for HTTP basic, HTTP digest, form, cookie and OpenID authentication 
    13         mehtods plus others. 
     20        *   Built in support for HTTP basic, HTTP digest, form, cookie and OpenID 
     21        authentication methods plus others 
    1422        *   Easily define users, passwords and roles 
    1523        *   Designed to be totally extensible so you can use the components to integrate 
    16         with a database, LDAP connection or your own custom system. 
    17         *   Plays nicely with the `Pylons <http://pylonshq.com>`_ web framework. 
     24        with a database, LDAP connection or your own custom system 
     25        *   Plays nicely with the `Pylons <http://pylonshq.com>`_ web framework 
    1826         
    19         There is also a `development version <http://authkit.org/svn/AuthKit/trunk#egg=AuthKit-dev>`_. 
    20          
    21         Installation 
    22         ============ 
    23          
    24         Source distribution:: 
    25          
    26         unzip zxfv AuthKit-0.4.0.zip 
    27         cd AuthKit-0.4.0 
    28         python setup.py install 
    29          
    30         or using `easy_install <http://peak.telecommunity.com/DevCenter/EasyInstall>`_:: 
    31          
    32         easy_install -U "AuthKit==0.4.0" 
    33          
    34         or if you don't have easy_install installed yet:: 
    35          
    36         wget http://peak.telecommunity.com/dist/ez_setup.py 
    37         python ez_setup.py "AuthKit==0.4.0" 
    38          
    39         Development version:: 
    40          
    41         svn co http://authkit.org/svn/AuthKit/trunk AuthKit 
    42         cd AuthKit 
    43         python setup.py develop 
     27        There is also a `development version 
     28        <http://authkit.org/svn/AuthKit/trunk#egg=AuthKit-dev>`_. 
    4429         
    4530        Get Started 
    …… 
    4732         
    4833        * `Download and Installation <http://python.org/pypi/AuthKit/0.4.0>`_ 
    49         * `AuthKit Manual <http://authkit.org/docs/manual.html>`_ 
    50         * `Module Reference <http://authkit.org/docs/module-index.html>`_ 
    51         * `Pylons Integration Manual <http://authkit.org/docs/pylons.html>`_ 
     34        * `Pylons Book <http://pylonsbook.com>`_ (the two chapters on Authentication and 
     35        Authorization and Advanced AuthKit form the AuthKit 0.4 documentation) 
     36        * `Module Reference <http://authkit.org/docs/0.4/module-index.html>`_ 
    5237        * `Trac <http://authkit.org/trac>`_ - Tickets, Wiki, Subversion 
    5338        * `Examples <http://authkit.org/trac/browser/AuthKit/trunk/examples>`_ 
    5439         
     40        Author 
     41        ====== 
     42         
     43        `James Gardner <http://jimmyg.org/>`_ james at pythonweb dot org 
     44         
     45        Development sponsored by `3aims <http://3aims.com/>`_ and 
     46        `Prometheus Research <http://www.prometheusresearch.com/>`_. 
     47         
     48         
     49        Changes 
     50        ======= 
     51         
     52        0.4 (**svn**) 
     53         
     54        *** AS A RESULT OF THESE CHANGES THE DOCS ARE CURRENTLY OUT OF DATE *** 
     55         
     56        * Added support for encrypted passwords 
     57        * Fixed the IE7 bug in digest middleware 
     58        * Adding SSO sub-directory, redirecting API, and CAS auth handler. 
     59        * Fixed binding check to return none, instead of throwing an Exception (for 
     60        performance reasons). 
     61        * Moved start_response check outside of app_iter consumption since it must be 
     62        called by this point to comply with WSGI. 
     63        * Fixed consumption app iter in multi, loading entire response into ram. 
     64        * Adding changelog 
     65        * Added IP and Time based permission objects 
     66        * Started unit tests 
     67        * Extended the user management API and added SQLAlchemy driver and example 
     68        * Restructured the authenticate middleware into induvidual pluggable components 
     69        * Simplified the configuration file system 
     70        * Added OpenID dependencies 
     71        * Removed the larger SQLAlchemy based demos 
     72        * The cookie module uses ``authkit`` as a default cookie name, not ``auth_tkt``. 
     73        Any code which does anything manually with this cookie needs the name changing 
     74        if it wasn't explicitly set to ``auth_tkt`` in the config file. 
     75         
     76        0.3.0pre5 
     77         
     78        * Changed the arguments to the authkit.authenticate.middleware() factory. You 
     79        will need to update your middleware setup to use app_conf instead of 
     80        config_paste for the app_conf dictionary. 
     81         
     82        0.3 
     83         
     84        * Re-written from scratch to be a modular toolkit for building your own auth 
     85        framework rather than an all-in-one solution. 
     86         
     87        0.2 
     88         
     89        * Re-written from scratch so to use SQLAlchemy only, old driver system considered 
     90        unnecessary and limiting. Also doesn't fit in with current Pylons 
     91        best-practice. 
     92         
     93        0.1 
     94         
     95        * Based on the web.auth 0.6 module from www.pythonweb.org, support for SQLObject 
     96        driver included 
     97         
     98         
     99        License 
     100        ======= 
     101         
     102        Copyright (c) Copyright 2005-2007 James Gardner <james at pythonweb dot org> 
     103         
     104        Permission is hereby granted, free of charge, to any person obtaining a copy 
     105        of this software and associated documentation files (the "Software"), to deal 
     106        in the Software without restriction, including without limitation the rights 
     107        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
     108        copies of the Software, and to permit persons to whom the Software is 
     109        furnished to do so, subject to the following conditions: 
     110         
     111        The above copyright notice and this permission notice shall be included in 
     112        all copies or substantial portions of the Software. 
     113         
     114        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
     115        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
     116        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
     117        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
     118        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
     119        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 
     120        THE SOFTWARE. 
     121         
     122         
     123        Download 
     124        ======== 
     125         
    55126Platform: UNKNOWN 

  • AuthKit/trunk/AuthKit.egg-info/SOURCES.txt

    r125 r128  
    1 CHANGELOG 
     1CHANGELOG.txt 
    22LICENSE.txt 
    33README.txt 

  • AuthKit/trunk/CHANGELOG.txt

    r127 r128  
    11Changes 
    2 +++++++ 
     2======= 
    33 
    440.4 (**svn**) 

  • AuthKit/trunk/LICENSE.txt

    r73 r128  
     1License 
     2======= 
     3 
    14Copyright (c) Copyright 2005-2007 James Gardner <james at pythonweb dot org> 
    25 

  • AuthKit/trunk/README.txt

    r125 r128  
    1 See the setup.py file for documentation links. 
     1See the docs/index.txt file for documentation links. 
    22 

  • AuthKit/trunk/authkit/authenticate/sso/__init__.py

    r88 r128  
    1515 
    1616.. admonition :: sources 
     17 
    1718    # http://searchsecurity.techtarget.com/sDefinition/0,,sid14_gci340859,00.html 
    1819    # http://en.wikipedia.org/wiki/Single_sign-on 

  • AuthKit/trunk/authkit/authenticate/sso/api.py

    r94 r128  
    5151        like so: 
    5252         
    53         .. code :: Python 
     53        .. code-block :: Python 
    5454             
    5555            class MyRedirectMiddleware(RedirectingAuthMiddleware): 

  • AuthKit/trunk/authkit/template/__init__.py

    r64 r128  
     1"""\ 
     2Paster create template for creating your own authentication methods. 
     3""" 
    14from paste.script.templates import BasicPackage 
    25 

  • AuthKit/trunk/authkit/users/__init__.py

    r123 r128  
    1414The implementation consists of the following: 
    1515 
    16     ``authkit.authenticate.valid_password()`` 
    17         A ``valid_password()`` implementation used by default with the 
    18         ``basic`` or ``form`` authentication methods that checks usernames and 
    19         passwords against those defined in the user management API object. 
    20       
    21     ``authkit.authenticate.digest_password()`` 
    22         A ``digest_password()`` implementation used by default with the 
    23         ``digest`` authentication which produces a digest from the users set up 
    24         in the user management API object. 
    25  
    26     ``authkit.permissions.HasAuthKitRole`` 
    27         A permission object which checks the signed in user's role from the  
    28         user management API object. 
    29  
    30     ``authkit.permissions.HasAuthKitGroup`` 
    31         A permission object which checks the signed in user's group from the  
    32         user management API object. 
    33  
    34     ``authkit.permissions.ValidAuthKitUser`` 
    35         A permission object which checks the signed in user is defined in the  
    36         user management API object. 
     16``authkit.authenticate.valid_password()`` 
     17    A ``valid_password()`` implementation used by default with the 
     18    ``basic`` or ``form`` authentication methods that checks usernames and 
     19    passwords against those defined in the user management API object. 
     20  
     21``authkit.authenticate.digest_password()`` 
     22    A ``digest_password()`` implementation used by default with the 
     23    ``digest`` authentication which produces a digest from the users set up 
     24    in the user management API object. 
     25 
     26``authkit.permissions.HasAuthKitRole`` 
     27    A permission object which checks the signed in user's role from the  
     28    user management API object. 
     29 
     30``authkit.permissions.HasAuthKitGroup`` 
     31    A permission object which checks the signed in user's group from the  
     32    user management API object. 
     33 
     34``authkit.permissions.ValidAuthKitUser`` 
     35    A permission object which checks the signed in user is defined in the  
     36    user management API object. 
    3737 
    3838Of course since the user management API is fairly generic, it is possible to 
    …… 
    6161import md5 as _md5 
    6262from authkit.authenticate import AuthKitConfigError 
    63 from authkit.authenticate import AuthKitConfigError 
    6463 
    6564# 
    …… 
    256255    def user(self, username): 
    257256        """ 
    258         Returns a dictionary in the following foramt:: 
     257        Returns a dictionary in the following format: 
     258 
     259        .. code-block :: Python 
    259260         
    260261            { 
    …… 
    264265                'roles':    [role1,role2,role3... etc] 
    265266            } 
     267 
    266268        The role names are ordered alphabetically 
    267269        Raises an exception if the user doesn't exist. 
    …… 
    456458    def user(self, username): 
    457459        """ 
    458         Returns a dictionary in the following foramt:: 
     460        Returns a dictionary in the following format: 
     461 
     462        .. code-block :: Python 
    459463         
    460464            { 
    …… 
    464468                'roles':    [role1,role2,role3... etc] 
    465469            } 
    466         Role names are ordered alphabetically 
     470 
     471        The role names are ordered alphabetically 
    467472        Raises an exception if the user doesn't exist. 
    468         """ 
     473        """     
    469474        username = username.lower() 
    470475        if not username in self.usernames: 

  • AuthKit/trunk/authkit/users/postgresql_driver.py

    r120 r128  
    336336    def user(self, username): 
    337337        """ 
    338         Returns a dictionary in the following foramt:: 
     338        Returns a dictionary in the following format: 
     339 
     340        .. code-block :: Python 
    339341         
    340342            { 
    …… 
    344346                'roles':    [role1,role2,role3... etc] 
    345347            } 
    346         The role names are ordered alphabetically 
     348 
     349        Role names are ordered alphabetically 
    347350        Raises an exception if the user doesn't exist. 
    348351        """ 

  • AuthKit/trunk/authkit/users/sqlalchemy_driver.py

    r120 r128  
    291291    def user(self, username): 
    292292        """ 
    293         Returns a dictionary in the following foramt:: 
     293        Returns a dictionary in the following format: 
     294 
     295        .. code-block :: Python 
    294296         
    295297            { 
    …… 
    299301                'roles':    [role1,role2,role3... etc] 
    300302            } 
     303 
    301304        The role names are ordered alphabetically 
    302305        Raises an exception if the user doesn't exist. 

  • AuthKit/trunk/docs/index.txt

    r59 r128  
    22+++++++ 
    33 
     4.. contents :: 
     5 
     6Summary 
     7======= 
     8 
    49*   Built for WSGI applications and middleware 
    510*   Sophisticated and extensible permissions system 
    6 *   Built in support for HTTP basic, HTTP digest, form, cookie and OpenID authentication  
    7     mehtods plus others. 
     11*   Built in support for HTTP basic, HTTP digest, form, cookie and OpenID 
     12    authentication methods plus others 
    813*   Easily define users, passwords and roles 
    914*   Designed to be totally extensible so you can use the components to integrate 
    10     with a database, LDAP connection or your own custom system. 
    11 *   Plays nicely with the `Pylons <http://pylonshq.com>`_ web framework. 
     15    with a database, LDAP connection or your own custom system 
     16*   Plays nicely with the `Pylons <http://pylonshq.com>`_ web framework 
    1217     
    13 There is also a `development version <http://authkit.org/svn/AuthKit/trunk#egg=AuthKit-dev>`_. 
     18There is also a `development version 
     19<http://authkit.org/svn/AuthKit/trunk#egg=AuthKit-dev>`_. 
    1420 
    1521Get Started 
    1622=========== 
    1723 
    18 * `Download and Installation <http://python.org/pypi/AuthKit/>`_ (choose the latest version) 
    19 * `AuthKit Manual <http://authkit.org/docs/manual.html>`_ 
    20 * `Module Reference <http://authkit.org/docs/module-index.html>`_ 
    21 * `Pylons Integration Manual <http://authkit.org/docs/pylons.html>`_ 
     24* `Download and Installation <http://python.org/pypi/AuthKit/0.4.0>`_ 
     25* `Pylons Book <http://pylonsbook.com>`_ (the two chapters on Authentication and 
     26  Authorization and Advanced AuthKit form the AuthKit 0.4 documentation) 
     27* `Module Reference <http://authkit.org/docs/0.4/module-index.html>`_ 
    2228* `Trac <http://authkit.org/trac>`_ - Tickets, Wiki, Subversion 
    2329* `Examples <http://authkit.org/trac/browser/AuthKit/trunk/examples>`_ 
    24  
    25 Status 
    26 ====== 
    27  
    28 AuthKit is not quite finished. It hasn't been used in production yet and will almost certainly have some bugs. 
    2930 
    3031Author 
    3132====== 
    3233 
    33 `James Gardner <http://www.3aims.com/>`_ james at pythonweb dot org  
     34`James Gardner <http://jimmyg.org/>`_ james at pythonweb dot org  
    3435 
    35 Development sponsored by `3aims Web Development. <http://www.3aims.com/>`_ 
     36Development sponsored by `3aims <http://3aims.com/>`_ and 
     37`Prometheus Research <http://www.prometheusresearch.com/>`_. 
     38 

  • AuthKit/trunk/docs/manual.txt

    r95 r128  
    22++++++++++++++ 
    33 
    4 AuthKit is a complete authentication and authorisation framework for WSGI applications. 
     4The AuthKit Manual has been replaced by two chapters of the `Pylons Book <http://pylonsbook.com>`_: 
    55 
    6 :author: James Gardner 
    7 :date: 2007-07-12 
     6* Authentication and Authorization 
     7* Advanced AuthKit 
    88 
    9 .. note:: 
    10  
    11     This version of AuthKit (0.4) is nothing like the old AuthKit 0.2 
    12     which used to be hosted in the Pylons SVN. This version is a 
    13     generic framework, the old version was a specific implementation. 
    14  
    15 .. contents:: Table of Contents 
    16 .. sectnum:: 
    17  
    18 .. warning::   
    19      
    20     AuthKit has not been audited by a security expert, please use with 
    21     caution at your own risk (or better yet, report security holes).  
    22  
    23 Any comments, suggestions or improvements would be gratefully received on the 
    24 `Pylons mailing list <http://groups.google.com/group/pylons-discuss>`_. 
    25  
    26 Credits 
    27 ======= 
    28  
    29 The middleware components of AuthKit make heavy use of `Paste 
    30 <http://pythonpaste.org>`_. 
    31  
    32 The Basics 
    33 ========== 
    34  
    35 When writing a web application you frequently come across the problem of 
    36 needing to restrict which visitors can see which pages. This problem can be 
    37 split into two parts. 
    38  
    39 Authentication 
    40  
    41     The process of proving who the visitor is. Usually they will 
    42     enter a username and password to prove their identity and the web application 
    43     will set a cookie so that when they visit other pages on the site the 
    44     application will be able to remember who the visitor is without needing to ask 
    45     for their username and password again. 
    46  
    47 Authorization 
    48  
    49     The process of checking that an authenticated vistor has 
    50     permission to see a particular page they are requesting. 
    51  
    52 These two parts are quite separate but often become confused becuase 
    53 information about who can be authenticated and what authorization permissions 
    54 each user has is often stored in the same place, for example a database or LDAP 
    55 repository. 
    56  
    57 Because authorisation and authentication information typically comes from a  
    58 variety of different sources any one solution (eg an SQL database) is not  
    59 necessarily going to fit your requirements AuthKit provides a framework you 
    60 can tweak to fit your requirements. 
    61  
    62 AuthKit is therefore a WSGI framework that provides a sensible structure for implementing 
    63 your own auth system. It also provides some sample implementations of the  
    64 framework so that you can add full authentication and authorisation to your  
    65 Web Server Gateway Interface project with just a few lines of code if you  
    66 prefer not to imlement your own system. 
    67  
    68 This document will take you through some different ways of restricting access 
    69 to your site with AuthKit starting simply and getting more sophisticated. 
    70  
    71 The AuthKit Architecture 
    72 ======================== 
    73  
    74 The AuthKit functionality is separated into the following classes of components: 
    75  
    76 Authentication Middleware 
    77  
    78     All authentication can be handled transparently by a middleware component so 
    79     that your application doesn't need to worry about how to sign users in. This 
    80     means you can change how your users are authenticated without changing any 
    81     of your application code. 
    82  
    83     The authentication middleware can intercept 401 and 403 responses so that 
    84     the rest of you application doesn't even need to use AuthKit in order for 
    85     the authenticate part to work. 
    86      
    87     In a WSGI application it is as simple as: 
    88      
    89     .. code-block:: Python 
    90      
    91         start_response('403 Access denied', []) 
    92  
    93     In Pylons this is as simple as writing: 
    94  
    95     .. code-block:: Python 
    96      
    97         abort(401) 
    98  
    99     The authenticate middleware supports the methods HTTP basic, HTTP digest, 
    100     form and cookie (with sign out), OpenID passurl or internal forward to 
    101     application. The middleware is either configured directly, from a generic 
    102     config file or a paste deploy setup.  
    103  
    104     If you are using paste deploy you can add the middleware and set:: 
    105  
    106         authkit.enable = false 
    107  
    108     in your config to disable it. One way of enabling it is to do something 
    109     like this:: 
    110  
    111         authkit.enable = true 
    112         authkit.setup.method = basic 
    113         authkit.users = james:bananas       
    114                         ben:apples 
    115  
    116     Any 401 status will now be handled and james can sign in with password 
    117     bananas and ben with apples. Nice and easy eh? 
    118  
    119     Of course there is a lot more to AuthKit. All the options are described  
    120     in this manual. 
    121  
    122 Permission Objects 
    123  
    124     An auth system should provide a way to check user permissions and has to 
    125     facilitate the developer in authorising a user at any point in the application 
    126     stack that the developer feels is appropriate. 
    127  
    128     AuthKit solves this requirement with permission objects used like this:: 
    129  
    130         from authkit.permissions import * 
    131         permission1 = UserIn(users=['ben','james']) 
    132         permission2 = And(RemoteUser(), Not(UserIn(['james']))) 
    133  
    134     You can use existing permissions or define them yourself. 
    135  
    136     Permissions have access to the WSGI ``environ`` dictionary and 
    137     ``start_response`` callable so as well as being based on information from a 
    138     database or LDAP repository they could be based on information from the request 
    139     or even the resposne and have all the flexibility and power of WSGI middleware. 
    140  
    141 Authorization Objects 
    142  
    143     Permission objects need to be checked in different ways depending on where  
    144     in the applicaiton stack the check occurs. There are different authorization 
    145     objects for use in different parts of a WSGI application but they all have 
    146     the same effect of requiring the user to be authorized based on the  
    147     permission object 
    148  
    149     If a permission check fails a NotAuthorizedError or NotAuthenticatedError 
    150     is raised by the authorisation object. This stops the request and is eventually 
    151     handled by the ``httpexceptions`` middleware which turns it into a response 
    152     with a 401 or 403 status code to be handled by the authentication middleware. 
    153  
    154 Using the above features it is possible to build a sophisticated auth system.  
    155 AuthKit goes further though and also defines other objects which you can use 
    156 as they stand, ignore completely or modify for your use: 
    157  
    158 User Management API 
    159  
    160     AuthKit provides a simple read-only, extensible user management API and  
    161     permissions objects to use it. It allows you to get started straight away.  
    162     
    163     If you want to be able to use the exisitng permissions you can implement  
    164     a user management API compatible with the AuthKit one and the existing  
    165     funcationality will work. 
    166  
    167     If you want to start from scratch, all the authentication methods provide  
    168     a means of handling user management yourself. 
    169  
    170 Framework Adaptors 
    171  
    172     Although AuthKit provides a totally generic API it also has built in  
    173     support for configuration via Paste Deploy config files and comes with 
    174     the authkit.pylons_adaptors module which provides tools for integrating 
    175     AuthKit into Pylons quickly and easily.  
    176  
    177     It is hoped other framework developers will also implement version of  
    178     AuthKit and the developers would be keen to assist with any such efforts. 
    179  
    180 The best way to expalin the various components and how they all fit together is 
    181 with some examples so lets get started. 
    182  
    183 Authentication Middleware 
    184 ========================= 
    185  
    186 Configuration 
    187 ------------- 
    188  
    189 First of all we need a middleware component to intercept responses with 401 
    190 status codes so that the user can be prompted to sign in. This is done using 
    191 ``authkit.authenticate`` middleware: 
    192  
    193 .. code-block:: Python 
    194  
    195     from authkit import authenticate 
    196     app = authenticate.middleware( 
    197         app, 
    198         config_paste=None, 
    199         config_file=None, 
    200         prefix='authkit.', 
    201         **options 
    202     ) 
    203  
    204 The authenticate middleware takes the WSGI application as the first parameter. 
    205 You can then choose to specify all the configuration options directly as 
    206 keyword arguments in the Python code that sets up the middleware or to use a 
    207 `Paste deploy config file <http://pythonpaste.org/deploy>`_. If you choose to 
    208 use a config file you can either specify the filename with ``config_file`` or 
    209 if you have already parsed the config file you can specify ``config_paste`` 
    210 which should be the ``paste.deploy.CONFIG['app_conf']`` dictionary. 
    211  
    212 AuthKit automatically converts any ``.`` characters in the config file keys to 
    213 ``_`` characters and it also strips off the ``prefix`` defined when inilialising 
    214 the middleware. If you don't set ``prefix`` it defaults to ``authkit.``. This  
    215 means that options such as ``cookie_signoutpath`` used by AuthKit can be written in  
    216 the slightly more descriptive and clean form ``authkit.cookie.signoutpath`` in the 
    217 config file. 
    218  
    219 .. note :: 
    220  
    221     Throughout the documentation we will describe configuration options in terms 
    222     of the configuration file keys because this is likely to be how you configure 
    223     AuthKit but in examples we will use the direct AuthKit options because we  
    224     don't want to clutter the examples with config parsing code. Please be aware 
    225     that the two ways of specifying AuthKit options have the same effect. 
    226  
    227 If you are using Paste Deploy or Pylons you can put these options in the 
    228 ``[app:main]`` section and setup your middleware stack as follows: 
    229  
    230 .. code-block:: Python  
    231  
    232     from authkit.authenticate import middleware 
    233     from paste.deploy import CONFIG 
    234     app = middleware(app, config_paste=CONFIG['app_conf')) 
    235  
    236 If you want to load the configuration from a plain file you can do so as follows: 
    237  
    238 .. code-block:: Python  
    239  
    240     from authkit.authenticate import middleware 
    241     app = middleware(app, config_file='/path/to/authkit.conf') 
    242  
    243 You can still specify parameters in conjunction with using a config file. Any 
    244 parameters specified in code will replace those specified in the config file 
    245 and a warning will be issued. 
    246  
    247 There are some options such as ``authkit.users.valid`` and 
    248 ``authkit.users.digest`` which take functions when used as parameters 
    249 from within code. In a config file these varibles should specify the module 
    250 path of the function to use in the format ``module_path:function``. For 
    251 example::  
    252  
    253     authkit.users.valid = authkit.authenticate:valid_password 
    254  
    255 Advanced Configuration Options 
    256 ------------------------------ 
    257  
    258 You can also specify some other configuration variables: 
    259  
    260 authkit.enable 
    261     If no options have been supplied in code when configuring the AuthKit 
    262     middleware it is assumed that authkit has been deployed as part of a framework 
    263     and will therefore not be enabled unless ``authkit.enable`` is set to ``true``. 
    264     Setting ``authkit.enable`` to ``false`` in the config file will always disable 
    265     the authkit middleware. If no value is set the authkit middleware is disables 
    266     and a warning logged. 
    267  
    268 authkit.catch 
    269     If specified should be a comma separated list of status codes you would 
    270     like the authkit middleware to respond to. For example if you want 403 
    271     Unauthorized pages to also prompt the visitor to sign in you could do this:: 
    272  
    273         authkit.catch = 401, 403 
    274  
    275     If you wanted only authenticated users to see error reports you could use:: 
    276          
    277         authkit.catch = 500 
    278  
    279     If you wanted all pages to require an authenticated user you could use:: 
    280      
    281         authkit.catch = *  
    282      
    283     If not specified authkit responds only to 401 status codes. 
    284  
    285 authkit.exclude 
    286     If ``authkit.catch`` is set to ``*`` you can specifically set codes not to 
    287     catch using ``authkit.exclude``. For example to require authentication for all 
    288     status codes except 500 and 404 you could do this:: 
    289  
    290         authkit.catch = * 
    291         authkit.exclude = 500, 404 
    292  
    293 Authentication Methods 
    294 ---------------------- 
    295  
    296 Once the basic configuration is set up the first thing to decide is how you 
    297 want to authenticate users. The options for the ``method`` parameter are: 
    298  
    299 ``basic``  
    300  
    301     Use HTTP basic authorisation 
    302  
    303 ``digest`` 
    304  
    305     Use HTTP digest authentication  
    306  
    307 ``form`` 
    308  
    309     Use a cookie and simple HTML form generated by the middleware 
    310  
    311 ``forward``  
    312  
    313     Internally forward the request to a specified URL so the 
    314     application can present a form to the user and handle sign in itself 
    315      
    316 ``passurl`` 
    317  
    318     Use an OpenID passurl for authentication 
    319  
    320 As mentioned before you can specify this in your code as 
    321 ``method="basic"`` or in your config file as ``authkit.setup.method = 
    322 basic``. If you try to specify the same option using both methods an 
    323 error is raised, otherwise AuthKit tries to use all the options from 
    324 both sources. 
    325  
    326 Each of these options is described in detail in the following sections. 
    327  
    328 Basic HTTP/1.0 Authentication 
    329 ----------------------------- 
    330  
    331 The ``basic`` method is an implementation of basic authentication as described in 
    332 HTTP/1.0 specification [1]_ .   
    333  
    334 .. warning:: Do not use this example in production sites unless you are using 
    335     SSL or need to work with very out-dated clients because the password entered is 
    336     transmitted in plain text, instead use `Digest HTTP/1.1 Authentication`_  
    337     described below. 
    338  
    339 HTTP Basic Authentication is perhaps the easiest way to add authentication to 
    340 your website. When your application returns a 401 status code the visitor's 
    341 browser will promot them for a username and password if they haven't already 
    342 signed in.  
    343  
    344 The AuthKit middleware will check the username and password and sign in the 
    345 visitor only if password was correct. 
    346  
    347 The code looks like this: 
    348  
    349     .. include:: ../examples/docs/basic.py 
    350         :literal: 
    351     
    352 The ``realm`` parameter is an identifier for the authority that is 
    353 requesting authorization. It is shown to the user and should be unique within 
    354 the domain it is being used. If it isn't specified, a default of ``AuthKit`` is 
    355 used. 
    356  
    357 The parameter ``users_valid`` should be a function that returns ``True`` 
    358 if the username and password are correct and ``False`` otherwise. The example 
    359 above will allow anyone with a password that is the same as their username to 
    360 sign in. In this case not entering a username or password is therefore allowed. 
    361 This isn't very secure so you should customise the function to suit 
    362 your setup. 
    363  
    364 .. note:: 
    365  
    366     Bear in mind that in authentication systems usernames are usually 
    367     case *insensitive* and passwords are case *sensitive*. Your users will 
    368     probably expect your system to follow this general rule. 
    369  
    370 If the visitor presses Cancel they will be shown the 403 Unauthorized response. 
    371  
    372 If a user has been signed in the ``REMOTE_USER`` environment variable will be 
    373 set with their username so you can access it in your application code as 
    374 ``environ['REMOTE_USER']``. 
    375  
    376 The example above is available in the ``examples/docs`` directory and can be  
    377 run with:: 
    378  
    379     python basic.py 
    380  
    381 If you run the program you will be able to visit http://localhost:8080 but will 
    382 be prompted to sign in if you visit http://localhost:8080/private and any 
    383 username password combination where the username is the same as the password 
    384 will sign you in any you will notice the ``REMOTE_USER`` variable will be set.  
    385  
    386 .. note:: 
    387  
    388     HTTP authentication does not easily support signing out so you will 
    389     need to close the browser to test the example again. 
    390  
    391 Digest HTTP/1.1 Authentication 
    392 ------------------------------ 
    393  
    394 This module implements ``Digest`` authentication as described by RFC 2617 [2]_ 
    395 . At this time, this implementation does not provide for further challenges, 
    396 nor does it support Authentication-Info header. It also uses md5, and an 
    397 option to use sha would be a good thing. 
    398  
    399 Digest authentication is similar to basic authentication but rather than 
    400 sending the password unencrypted you send an encrypted digest so the security 
    401 is slightly better. 
    402  
    403 The code looks like this: 
    404  
    405     .. include:: ../examples/docs/digest.py 
    406         :literal: 
    407  
    408 Note that the ``digest()`` function takes different parameters from the 
    409 ``valid()`` function we used in the HTTP basic authentication. Also rather than 
    410 returing ``True`` or ``False`` the function should use the 
    411 ``digest_password()`` function from ``authkit.middleware.digest`` to return a 
    412 digest. 
    413  
    414 Form-Based Authentication 
    415 ------------------------- 
    416  
    417 One of the drawbacks of HTTP authentication is that the user can't easily sign 
    418 out without closing the browser window. A form and cookie based solution is 
    419 therefore preferable for most web applications. 
    420  
    421 With this method if the user accesses a page that returns a 401 status code, the 
    422 AuthKit middleware intercepts it and displays a form for the user to sign in. 
    423 The template to use is supplied when configuring the middleware or a default is 
    424 used if none is specified. If the user's sign in is incorrect they are shown 
    425 the form again. 
    426  
    427 Since the authentication form is submitted (via POST) neither the PATH_INFO nor 
    428 the QUERY_STRING are accessed, and hence the current path remains _unaltered_ 
    429 through the entire authentication process. If authentication succeeds, the 
    430 REQUEST_METHOD is converted from a POST to a GET and the page the user was 
    431 trying to view is displayed, so that a redirect is unnecessary (unlike most 
    432 form auth implementations). 
    433  
    434 Here is a working example: 
    435  
    436     .. include:: ../examples/docs/form.py 
    437         :literal: 
    438  
    439 The ``form`` method can use the same ``valid()`` authenticate function as that 
    440 used by the HTTP basic method but this example uses an alternative method 
    441 making use of the AuthKit user management API. This is described in detail 
    442 later but provides a very quick and easy way of specifying users, passwords, 
    443 groups and roles. 
    444  
    445 The example also specifies a ``cookie_secret`` which is a string used to help 
    446 make the encryption on the cookie more random and a ``cookie_signoutpath`` 
    447 parameter which is a special path which should automatically sign the user out 
    448 when visited but will still display the resulting page so that your application 
    449 can display a signed out message. There are lots of cookie options you can 
    450 specify including the name, and expire time and more. These are all described 
    451 in the cookie options section later. 
    452  
    453 If you run the example and visiting http://localhost:8080/private the sign in 
    454 form will be displayed. If you sign in with a username that is the same as the 
    455 password you will be signed in. If you visit http://localhost:8080/signout you 
    456 will see the data as usual but if you press refresh you will notice that you 
    457 have also been signed out. 
    458  
    459 .. note::  
    460  
    461     If you would like your application to handle the creation of the form, the 
    462     sign in process and sign out manually so that you have complete control over 
    463     the authentication process you should use the ``forward`` method. 
    464  
    465 You can also configure the template used in the form. There are three ways to  
    466 do this. The first is to specify the ``form_template`` option with the new 
    467 template.  
    468  
    469 The template should contain the characters ``%s`` which will be replaced with 
    470 the correct action URL. Any other ``%`` characters should be escaped by  
    471 writing them as ``%%``. The form should also contain fields named ``username`` 
    472 and ``password`` and should use the ``POST`` method. Here is an example:: 
    473  
    474     form_template = """\ 
    475     <html> 
    476       <head><title>Please Login!</title></head> 
    477       <body> 
    478         <h1>Please Login</h1> 
    479         <form action="%s" method="post"> 
    480           <dl> 
    481             <dt>Username:</dt> 
    482             <dd><input type="text" name="username"></dd> 
    483             <dt>Password:</dt> 
    484             <dd><input type="password" name="password"></dd> 
    485           </dl> 
    486           <input type="submit" name="authform" /> 
    487           <hr /> 
    488         </form> 
    489       </body> 
    490     </html> 
    491     """ 
    492  
    493 You can also specify ``form_template_file`` which should be a file containing 
    494 the template with the same escaping as described above or ``form_template_obj`` 
    495 which should be the Paste eval_import style path to a string object in an 
    496 existing module containing the template or a callable that returns a string. 
    497 For example:: 
    498  
    499     form_template_obj = authkit.authenticate.form:template 
    500  
    501 Forwarding 
    502 ---------- 
    503  
    504 Arguably the most flexible and powerful system for authentication is for the 
    505 middleware to internally forward the request to a different part of the 
    506 application if a 401 status is intercepted. The application itself is then 
    507 responsible for displaying that page to take care of displaying a sign in form, 
    508 authenticate a user, set a cookie and sign the user out in whichever 
    509 way the application author thinks is best. 
    510  
    511 The foward middleware sets up the cookie middleware used by the ``form`` method 
    512 but you still need to manually set the cookie after the user has signed in 
    513 using your own custom sign in form which you would have implemented yourself. 
    514  
    515 The cookie can be set like this: 
    516  
    517 .. code-block:: Python 
    518  
    519     environ['paste.auth_tkt.set_user'](username) 
    520  
    521 If you specify a ``cookie_signoutpath`` path when you set up the authentication 
    522 middleware the user will be signed out automatically when visiting that path 
    523 but you will still need to display a "signed out" path at that URL or the user 
    524 will see a 404 page and think they haven't been signed out. 
    525  
    526 Alternatively you can sign out the user manually by setting a cookie with the 
    527 same name but no value or using the ``environ['paste.auth_tkt.logout_user']()`` 
    528 method documented here: http://pythonpaste.org/module-paste.auth.auth_tkt.html  
    529  
    530 Here is a simple complete example: 
    531  
    532     .. include:: ../examples/docs/forward.py 
    533         :literal: 
    534  
    535 .. note::  
    536  
    537     If you are using any of the examples shown so far with permissions objects (described later)  
    538     you will also need to include the paste httpexceptions middleware otherwise 
    539     the ``NotAuthorizedError`` and ``NotAuthenticatedError`` errors will not be 
    540     converted to status codes which the authenticate middleware use. 
    541  
    542     You can set this up by adding the following lines before you add the  
    543     authenticate middleware: 
    544  
    545     .. code-block:: Python 
    546  
    547         from paste import httpexceptions 
    548         test_app = httpexceptions.middleware(test_app) 
    549          
    550 A full description of the cookie options you can use is described in the cookie options 
    551 section. 
    552  
    553 OpenID Passurl 
    554 -------------- 
    555  
    556 Perhaps the simplest way of handling authentication in your application is to 
    557 use OpenID. With OpenID the user enters their identity URL and the middleware 
    558 contacts the identity provider associated with the URL. The identity provider  
    559 then handles the authentication and replies to tell the middleware if the user