| Status: | Official |
|---|
This documents describes how to implement authentication and authorization in TG 2 applications. Although there are other ways to implement it (e.g., using the AuthKit package or a project-specific solution), this document only describes the officially supported and recommended way.
Table of Contents
Authentication is the act verifying that somebody is really who she claims
to be, which is normally done using credentials (e.g., when you need to access
your email, you provide the email address and your password, or if you want
to check your bank account, you’ll probably have to provide you Id number and
your card’s PIN). In other words, finding who you are.
Authorization, on the other hand, is the act of granting access to given
resources depending on whether you have permission to use them. For example,
allowing registered members to leave comments on a blog, or allowing your
friends to see your pictures while others cannot.
In other words, finding what you may do.
TurboGears 2 applications may take advantage of a robust, extendable, pluggable and easy-to-use system for authentication and authorization suitable for nearly all situations in fact, you may extend it to suit your needs if it doesn’t, which should be really simple in most situations. Such a system is made up of two independent components, well integrated into TurboGears:
repoze.who, a framework forauthenticationin WSGI applications. You normally don’t have to care about it because by default TurboGears 2.1.5 applications ship all the code to set it up (as long as you had selected such an option when you created the project), but if you need something more advanced you are at the right place.repoze.what, the successor oftg.ext.repoze.whoandtgext.authorization(used in unstable TurboGears 2.1.5 releases), is a framework forauthorizationthat is mostly compatible with the TurboGears 1.x Identity authentication, identification and authorization system.
You may store your users’ credentials where you want (e.g., in a database, an LDAP server, an .htaccess file) and also store your authorization settings in any type of source (e.g., in a database, Ini file) – if the back-end you need is not available, you may create it yourself (which is usually very easy). And don’t worry if you need to change the back-end afterwards: You would not need to touch your code! Except, of course, the snippet that tells where the data may be found.
repoze.what uses a common pattern based on the users (authenticated
or anonymous) of your web application, the groups they belong to and the
permissions granted to such groups. But you can extend it to check for many
other conditions (such as checking that the user comes from a given country,
based on her IP address, for example).
The authentication framework (repoze.who) only deals with the
source(s) that handle your users’ credentials, while the
authorization framework (repoze.what) deals with both the
source(s) that handle your groups and those that handle your permissions.
While repoze.what only deals with authorization, its SQL plugin
provides a module to setup authentication via repoze.who so that you can
get started with authentication and authorization very quickly. It may be
enabled while creating the TurboGears 2.1.5 project or afterwards, and it
may be easily replaced by a custom solution.
To use it on a new project, just answer “yes” during the paster quickstart process when it asks you if you want authorization:
Do you need authentication and authorization in this project? [yes]
You’ll then get authentication and authorization code added for you, including
the SQLAlchemy-powered model definitions in {yourpackage}.model.auth
and the relevant settings in {yourpackage}.config.app_cfg. It also defines
the default users, groups and permissions in {yourpackage}.websetup, which
you may want to customize.
Before trying to login and try authorization with the rows defined in
{yourpackage}.websetup, you have to create the database; run the following
command from your project’s root directory:
paster setup-app development.ini
Note
This module is repoze.what.plugins.quickstart and only works if your
users’ credentials, groups and permissions are stored in a SQLAlchemy -managed
database. To implement it on an existing project, or customize the model
structure assumed by it, you have to read the documentation for
repoze.what.plugins.quickstart.
If you need more power than that provided by the quickstart, or if you just want to customize some things, you may want to read the following pages: