Table Of Contents

Previous topic

Identity Management

Next topic

Using Identity

Getting Started With Identity

This tutorial shows you how to enable and use identity support in a new quickstart project. Please note that there is additional Identity functionality beyond what is covered in this tutorial. See the list at the end of this page for links to more information.

Create an Identity-enabled Project

First, let’s create a new project called identity_tutorial, requesting that identity management features be included:

$ tg-admin quickstart --identity --package idtut IdentityTutorial

Or, more briefly:

$ tg-admin quickstart -i -p idtut IdentityTutorial

TurboGears will generate the project skeleton for you, including identity-specific data objects in and controllers to handle form-based logging in and out in

You might customize the model generated in IdentityTurtorial/idtut/ as you can do with the other parts of the model, but be aware that the identity framework expects your user, group and permission objects to have certain properties. See the advanced identity documentation linked below for more information.

Make your newly created project directory the current directory and initialize the database to store the identity information:

$ cd IdentityTutorial
$ tg-admin sql create

This creates a database called “devdata.sqlite”, that contains the empty tables needed for identity management.

Create an SQLObject Project

By default, TurboGears 1.1 will generate the identity data model based on SQLAlchemy. To generate an SQLObject-based identity and data model instead, you can use the following command:

$ tg-admin quickstart --identity --sqlobject --package idtut IdentityTutorial

Or more briefly:

$ tg-admin quickstart -i -o -p idtut IdentityTutorial

Test the Login Page

To check that everything is set up correctly so far, start the project as usual:

$ python

In your browser, visit http://localhost:8080/login. You should see a login page with username and password fields – login and logout methods are added to your project’s and appropriate templates are created because you requested that your project include identity management.

All login attempts will fail at this stage because you haven’t yet added any users or groups.

Adding a User and Group

TurboGears currently provides two ways to set up users, groups and permissions in your database:

  1. A basic database bootstrap function in, which creates all database tables and optionally adds a default user.
  2. Manually manipulating data model objects using the interactive shell.


When SQLObject database support is used you can also use CatWalk to maintain user and group data. Please refer to the TurboGears 1.0 identity documentation for datailed instructions on this.

1. Simple Bootstrap

Start the TurboGears shell from the top-level directory of your project:

$ tg-admin shell

Remember that all your model objects and other module globals are already imported into the shell environment as if you had typed from model import *. This means we can directly run the bootstrap function:

>>> bootstrap_model(user=u'jdoe')
Enter password for user 'jdoe':
Confirm password:
User 'jdoe' created.

Enter the password twice and you now have a user with user name "jdoe" in your database. If you like, you can check the user object with:

>>> User.by_user_name(u'jdoe')
<User 1 user_name=u'jdoe' email_address=u''
display_name=u'Default User' password=u'xxx' created='datetime.datetime...)'>

You can try to log into your application with the password you have chosen.


By default the users’ passwords are saved as plaintext in the database. That’s fine for now, but in a production environment, you’ll want to specify a password encryption scheme. See the configuration reference section on Visit and Identity Configuration for the encryption_algorithm setting, that enables on-the-fly password encryption with different algorithms.

2. Using the Shell

If you would rather manipulate your data model objects directly for maximum flexibility, or you need more user and groups, you also use the shell. Again you would start the shell from the top-level project directory:

$ tg-admin shell

Let’s create the initial user:

>>> user = User(user_name=u'jdoe', email_address=u'',
                display_name=u'Jane Doe', password=u'xxx')

Add this if you use SQLAlchemy:

>>> session.add(user)

You will see messages indicating that the shell has loaded identity models and the user object will be created.

Similarly, create the group:

>>> group = Group(group_name=u'admin', display_name=u'Administrators')

Only if you use SQLAlchemy:

>>> session.add(group)

Now add the user to the group. If you are using SQLAlchemy:

>>> group.users.append(u)

Or, if you have a SQLObject model, use this:

>>> group.addUser(u)

And finallly, if you are using SQLAlchemy:

>>> session.flush()

You can now see that the user is indeed part of the group:

>>> group.users
[<User 1 user_name=u'jdoe' email_address=u''
display_name=u'Jane Doe' password=u'xxx' created='datetime.datetime...)'>]

>>> user.groups
[<Group 1 group_name=u'admin' display_name=u'Administrators'

Create a permission:

>>> p = Permission(permission_name='admin',
        description=u"Administer the application")

Now, add the permission to the group. If you have a SQLAlchemy model:

>>> g.permissions.append(p)

Or, if you are using SQLObject:

>>> g.addPermission(p)

Now exit the shell (using Ctrl-Z on Windows, or Ctrl-D on other systems). Your user and group objects should be already saved in the database, but for safety, choose “yes” when you are asked whether you want to commit you database changes. Now try to log into your application with the user name and password you have chosen.

Further Reading

Now that you have identity up and running, you probably want to know how to use it. Be sure to check out the following pages