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.
First, let’s create a new project called
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
model.py and controllers to handle
form-based logging in and out in
You might customize the model generated in
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
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.
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
To check that everything is set up correctly so far, start the project as usual:
$ python start-idtut.py
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
controllers.py 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.
TurboGears currently provides two ways to set up users, groups and permissions in your database:
model.py, which creates all database tables and optionally adds a default user.
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.
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
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@example.com' 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
encryption_algorithm setting, that enables on-the-fly password
encryption with different algorithms.
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', firstname.lastname@example.org', display_name=u'Jane Doe', password=u'xxx')
Add this if you use SQLAlchemy:
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:
Now add the user to the group. If you are using SQLAlchemy:
Or, if you have a SQLObject model, use this:
And finallly, if you are using SQLAlchemy:
You can now see that the user is indeed part of the group:
>>> group.users [<User 1 user_name=u'jdoe' email@example.com' display_name=u'Jane Doe' password=u'xxx' created='datetime.datetime...)'>] >>> user.groups [<Group 1 group_name=u'admin' display_name=u'Administrators' created='datetime.datetime...)'>]
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:
Or, if you are using SQLObject:
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.