Permalink
Browse files

Update Authentication documentation

  • Loading branch information...
amol- committed May 4, 2012
1 parent 1c84f92 commit a92357800e540a4248d2c77a6b5b5a683f4af886
Showing with 123 additions and 479 deletions.
  1. +16 −14 docs/main/Auth/Authentication.rst
  2. +28 −70 docs/main/Auth/Authorization.rst
  3. +68 −364 docs/main/Auth/Customization.rst
  4. +11 −31 docs/main/Auth/index.rst
@@ -15,8 +15,10 @@
to check :mod:`repoze.who`'s website.
:mod:`repoze.who` is a powerful and extensible ``authentication`` package for
-arbitrary WSGI applications. Within TurboGears, it's configured through
-:mod:`repoze.what`.
+arbitrary WSGI applications. By default TurboGears2 configures it to log using
+a form and retrieving the user informations through the user_name field of the
+User class. This is made possible by the ``authenticator plugin`` that TurboGears2
+uses by default which is ``repoze.who.plugins.sa.SQLAlchemyAuthenticatorPlugin``.
How it works
@@ -92,29 +94,29 @@ select).
How it works in TurboGears applications
=======================================
-TurboGears itself doesn't deal directly with :mod:`repoze.who`. It's configured
-through :mod:`repoze.what` because it has to configure :mod:`repoze.who` in a
-special way so that authorization can work.
-
-By default, :mod:`repoze.what` in TurboGears |version| configures :mod:`repoze.who`
-to use its :class:`repoze.who.plugins.form.RedirectingFormPlugin` as the first
+By default, TurboGears |version| configures :mod:`repoze.who` to use
+:class:`repoze.who.plugins.friendlyform.FriendlyFormPlugin` as the first
identifier and challenger -- using ``/login`` as the relative URL that will
display the login form, ``/login_handler`` as the relative URL where the
form will be sent and ``/logout_handler`` as the relative URL where the
user will be logged out. The so-called rememberer of such identifier will
be an instance of :class:`repoze.who.plugins.cookie.AuthTktCookiePlugin`.
-All these settings can be customized through
-:mod:`repoze.what.plugins.quickstart`.
-You don't have to use :mod:`repoze.who` directly either, unless you decide not
-to use it the way TurboGears configures it through :mod:`repoze.what`.
+All these settings can be customized through the ``config.app_cfg.base_config.sa_auth``
+options in your project. Identifiers, Authenticators and Challengers can be overridden
+providing a different list for each of them as::
+ base_config.sa_auth['identifiers'] = [('myidentifier', myidentifier)]
+
+You don't have to use :mod:`repoze.who` directly either, unless you decide not
+to use it the way TurboGears configures it.
Advanced topics
===============
If you're looking for different authentication methods, you may want to visit
`the repoze.who website <http://static.repoze.org/whodocs/>`_ to check if the
plugin you're looking for is already available or how to create your own plugins.
-Then you should also check the :mod:`repoze.what` documentation to learn how to
-setup the new settings.
+
+To learn how to customize Authentication and Authorization in TurboGears you
+can give a look at `Customizing Authentication <Customization.html>`_.
@@ -1,62 +1,44 @@
****************************************************************
-:mod:`repoze.what` -- Authorization in TurboGears 2 applications
+Authorization in TurboGears 2 applications
****************************************************************
:Status: Official
-:Website: `<http://static.repoze.org/whatdocs/>`_
-
-.. module:: repoze.what
- :synopsis: Setup authorization in WSGI applications
.. topic:: Overview
- This document describes how :mod:`repoze.what` is integrated into TurboGears
- and how you may get started with it. For more information, you may want
- to check :mod:`repoze.what`'s website.
-
-
-:mod:`repoze.what` is a highly extensible and fully documented ``authorization``
-framework which is well integrated into TurboGears (in fact, it started as a TG
-subproject).
-
+ This document describes how authentication is integrated into TurboGears
+ and how you may get started with it.
How authentication and authorization is set up by default
=========================================================
If you enabled authentication and authorization in your project when it was
generated by TurboGears, then it's been set up to store your users, groups and
-permissions in SQLAlchemy-managed tables.
-
-Your users' table is used by :mod:`repoze.who` to authenticate them and also
-by :mod:`repoze.what` (along with the groups table) to find the groups to which
-the user belongs. Then your permissions table is only used by
-:mod:`repoze.what` to find the permissions granted to the groups to which the
-current user belongs.
-
-This is all configured through :mod:`repoze.what` and you are free to replace
-these settings whenever you want. If you want to keep the three tables above
-but you need more flexibility, you will get it by adjusting your
-``{yourproject}.config.app_cfg`` module accordingly. If you don't want to keep
-the three tables above for authentication or authorization (e.g., you want to
-use `OpenID` authentication and store your groups and permissions in XML
-files), then you should check the :mod:`repoze.what` manual to learn how
-to configure your TG application. (See also :ref:`openid` which describes
-the process of setting up `OpenID` authentication in detail).
+permissions in SQLAlchemy-managed tables or Ming collections.
+
+Your users' table is used by :mod:`repoze.who` to authenticate them.
+When the authentication has success TurboGears uses the ``TGAuthMetadata``
+instance declared in ``config.base_config.sa_auth.authmetadata`` to
+retrieve the informations about your user which are required for authorization.
+
+You are free to change the authmetadata object as you wish, usually if your
+authentication model changes, your authmetadata object will change accordingly.
You can even get rid of authorization based on groups and permissions and use
other authorization patterns (e.g., roles, based on network components) or
-simply use a mix of patterns -- if so, check the :mod:`repoze.what`
-manual to learn more.
-
+simply use a mix of patterns. To do this you can set ``authmetadata`` to ``None``
+and register your own metadata providers for :mod:`repoze.who`.
-Restricting access with :mod:`repoze.what.predicates`
+Restricting access with :mod:`tg.predicates`
=====================================================
-.. module:: repoze.what.predicates
- :synopsis: repoze.what built-in predicate checkers.
+.. module:: tg.predicates
+ :synopsis: built-in predicate checkers.
-:mod:`repoze.what` allows you to define access rules based on so-called
-"predicate checkers".
+tg.predicates allows you to define access rules based on so-called
+"predicate checkers". It is a customized version of the :mod:`repoze.what`
+module which has been merged into TurboGears itself to make easier
+to support different authentication backends.
A ``predicate`` is the condition that must be met for the user to be able to
access the requested source. Such a predicate, or condition, may be made
@@ -76,15 +58,15 @@ are done.
For example, if you have a predicate which is "grant access to any authenticated
user", then you can use the following built-in predicate checker::
- from repoze.what.predicates import not_anonymous
+ from tg.predicates import not_anonymous
p = not_anonymous(msg='Only logged in users can read this post')
Or if you have a predicate which is "allow access to root or anyone with the
'manage' permission", then you may use the following built-in predicate
checker::
- from repoze.what.predicates import Any, is_user, has_permission
+ from tg.predicates import Any, is_user, has_permission
p = Any(is_user('root'), has_permission('manage'),
msg='Only administrators can remove blog posts')
@@ -143,7 +125,7 @@ your controller class::
from yourproject.lib.base import BaseController
class Admin(BaseController):
- allow_only = authorize.has_permission('manage')
+ allow_only = predicates.has_permission('manage')
@expose('yourproject.templates.index')
def index(self):
@@ -169,7 +151,7 @@ your controller class::
Built-in predicate checkers
---------------------------
-These are the predicate checkers that are included with :mod:`repoze.what`,
+These are the predicate checkers that are included with :mod:`tg.predicates`,
although the list below may not always be up-to-date:
@@ -250,7 +232,7 @@ Custom single predicate checkers
You may create your own predicate checkers if the built-in ones are not enough
to achieve a given task.
-To do so, you should extend the :class:`repoze.what.predicate.Predicate`
+To do so, you should extend the :class:`tg.predicates.Predicate`
class. For example, if your predicate is "Check that the current month is the
specified one", your predicate checker may look like this::
@@ -286,7 +268,7 @@ as in this example::
class SummerVacations(BaseController):
# ...
@expose('spain_travels.templates.start_vacations')
- @authorize.require(is_month(7))
+ @require(is_month(7))
def start_vacations():
flash('Have fun!')
dict()
@@ -322,35 +304,11 @@ But you can also nest compound predicates::
# ...
@authorize.require(authorize.All(
Any(is_month(4), is_month(10)),
- authorize.has_permission('release')
+ predicates.has_permission('release')
))
def release_ubuntu(self, **kwargs):
return dict()
# ...
Which translates as "Anyone granted the 'release' permission may release a
version of Ubuntu, if and only if it's April or October".
-
-
-How TurboGears deals with :mod:`repoze.what` internally
-=======================================================
-
-.. note::
-
- TurboGears will configure :mod:`repoze.what` for you, if and only if you
- have enabled authentication and authorization in
- ``{yourproject}.config.app_cfg``.
-
-TurboGears will take your auth settings defined in
-``{yourproject}.config.app_cfg`` and then it will configure :mod:`repoze.what`
-with such settings using its SQL plugin.
-
-Also, it provides you will the functionality described above:
-The ``@require`` decorator and the ability to define controller-wide predicates.
-
-That's it -- TurboGears doesn't deal with :mod:`repoze.what` in any other way,
-so it's absolutely safe for you to stop TurboGears from configuring
-:mod:`repoze.what` with its SQL plugin so that you can set it up on your own,
-while still using the @require decorator and the ability to control access
-at the controller level.
-
Oops, something went wrong.

0 comments on commit a923578

Please sign in to comment.