Changeset 5750

Show
Ignore:
Timestamp:
11/23/08 12:06:15 (2 months ago)
Author:
Gustavo
Message:

Documented repoze.who and how it works in TG

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • docs/2.0/docs/main/Auth/Authentication.rst

    r5573 r5750  
    1 :mod:`repoze.who` -- Authentication for TurboGears 2 applications 
    2 ================================================================= 
     1**************************************************************** 
     2:mod:`repoze.who` -- Authentication in TurboGears 2 applications 
     3**************************************************************** 
     4 
     5:Status: Official 
     6:Website: `<http://static.repoze.org/whodocs/>`_ 
     7 
    38.. module:: repoze.who 
    49    :synopsis: Setup authentication in WSGI applications 
    510 
    6 :Status: Draft 
     11.. topic:: Overview 
     12 
     13    This document describes how :mod:`repoze.who` is integrated into TurboGears 
     14    and how you make get started with it. For more information, you may want 
     15    to check :mod:`repoze.who`'s website. 
     16 
     17:mod:`repoze.who` is a powerful and extensible ``authentication`` package for 
     18arbitrary WSGI applications. Within TurboGears, it's configured through 
     19:mod:`repoze.what`. 
    720 
    821 
    9 Overview 
    10 -------- 
     22How it works 
     23============ 
    1124 
    12 @TODO 
     25It's a WSGI middleware which is able to authenticate the user through the 
     26method you want (e.g., LDAP or HTTP authentication), "remember" the user in 
     27future requests and log the user out. 
     28 
     29You can customize the interaction with the user through four kinds of 
     30`plugins`, sorted by the order in which they are run on each request: 
     31 
     32* An ``identifier plugin``, with no action required on the user's side, is able 
     33  to tell whether it's possible to authenticate the user (e.g., if it finds 
     34  HTTP Authentication headers in the HTTP request). If so, it will extract the 
     35  data required for the authentication (e.g., username and password, or a 
     36  session cookie). There may be many identifiers and :mod:`repoze.who` will run  
     37  each of them until one finds the required data to authenticate the user. 
     38* If at least one of the identifiers could find data necessary to authenticate 
     39  the current user, then an ``authenticator plugin`` will try to use the 
     40  extracted data to authenticate the user. There may be many authenticators 
     41  and :mod:`repoze.who` will run each of them until one authenticates the user. 
     42* When the user tries to access a protected area or the login page, a 
     43  ``challenger plugin`` will come up to request an action from the user (e.g., 
     44  enter a user name and password and then submit the form). The user's response 
     45  will start another request on the application, which should be caught by 
     46  an `identifier` to extract the login data and then such data will be used 
     47  by the `authenticator`. 
     48* For authenticated users, :mod:`repoze.who` provides the ability to load 
     49  related data (e.g., real name, email) in the WSGI environment so that it can 
     50  be easily used in the application. Such a functionality is provided by  
     51  so-called ``metadata provider plugins``. There may be many metadata providers 
     52  and :mod:`repoze.who` will run them all. 
     53 
     54When :mod:`repoze.who` needs to store data about the authenticated user in the  
     55WSGI environment, it uses its ``repoze.who.identity`` key, which can be  
     56accessed using the code below:: 
     57 
     58    from tg import request 
     59     
     60    # The authenticated user's data kept by repoze.who: 
     61    identity = request.environ.get('repoze.who.identity') 
     62 
     63Such a value is a dictionary and is often called "the identity dict". It will  
     64only be defined if the current user has been authenticated. 
     65 
     66The username will be available in ``identity['repoze.who.userid']``. 
    1367 
    1468 
    15 Links 
    16 ----- 
    17 @TODO 
     69How it works in TurboGears applications by default 
     70================================================== 
    1871 
     72TurboGears itself doesn't deal directly with :mod:`repoze.who`. It's configured 
     73through :mod:`repoze.what` because it has to configure :mod:`repoze.who` in a 
     74special way so that authorization can work. 
     75 
     76You don't have to use :mod:`repoze.who` directly, unless you decide not to use 
     77it the way TurboGears configures it, except if you need to access data stored 
     78in the `identity` dict which was explained above. 
     79 
     80 
     81Advanced topics 
     82=============== 
     83 
     84If you're looking for different authentication methods, you may want to visit 
     85`the repoze.who website <http://static.repoze.org/whodocs/>`_ to check if the 
     86plugin you're looking for is already available or how to create your own plugins. 
     87Then you should also check `the repoze.what manual  
     88<http://static.repoze.org/whatdocs/>`_ to learn how to setup the new settings.