The repoze.what Quickstart plugin

Author:Gustavo Narea.
Latest release:1.0.10

Overview

This plugin allows you to take advantage of a rather simple, and usual, authentication and authorization setup, in which the users’ data, the groups and the permissions used in the application are all stored in a SQLAlchemy or Elixir-managed database.

Put simply, it configures repoze.who and repoze.what in one go so that you can have an authentication and authorization system working quickly – hence the name.

How to install

The minimum requirements are SQLAlchemy, repoze.who.plugins.sa, repoze.who.plugins.friendlyform, repoze.what and repoze.what.plugins.sql, and you can install it all with easy_install:

easy_install repoze.what-quickstart

Support and development

The prefered place to ask questions is the Repoze mailing list. Some users are on the #repoze IRC channel.

This project is hosted on GitHub.

How to use it

To get started quickly, you may copy the SQLAlchemy-powered model defined in model_sa_example.py (or model_elixir_example.py for Elixir) and then create at least a few rows to try it out:

u = User()
u.user_name = u'manager'
u.password = u'managepass'

DBSession.save(u)

g = Group()
g.group_name = u'managers'

g.users.append(u)

DBSession.save(g)

p = Permission()
p.permission_name = u'manage'
p.groups.append(g)

DBSession.save(p)
DBSession.flush()

Now that you have some rows in your database, you can set up authentication and authorization as explained in the next section.

How to set it up

Although this is a repoze.what plugin and repoze.what is meant to deal with authorization only, this module configures authentication and identification for you through repoze.who as well.

Such a setup is performed by the setup_sql_auth() function:

repoze.what.plugins.quickstart.setup_sql_auth(app, user_class, group_class, permission_class, dbsession, form_plugin=None, form_identifies=True, cookie_secret='secret', cookie_name='authtkt', login_url='/login', login_handler='/login_handler', post_login_url=None, logout_handler='/logout_handler', post_logout_url=None, login_counter_name=None, translations={}, cookie_timeout=None, cookie_reissue_time=None, charset='iso-8859-1', use_default_authenticator=True, **who_args)

Configure repoze.who and repoze.what with SQL-only authentication and authorization, respectively.

Parameters:
  • app – Your WSGI application.
  • user_class – The SQLAlchemy/Elixir class for the users.
  • group_class – The SQLAlchemy/Elixir class for the groups.
  • permission_class – The SQLAlchemy/Elixir class for the permissions.
  • dbsession – The SQLAlchemy/Elixir session.
  • form_plugin – The main repoze.who challenger plugin; this is usually a login form.
  • form_identifies (bool) – Whether the form_plugin may and should act as an repoze.who identifier.
  • cookie_secret (str) – The “secret” for the AuthTktCookiePlugin (set a custom one!).
  • cookie_name (str) – The name for the AuthTktCookiePlugin.
  • login_url (str) – The URL where the login form is displayed.
  • login_handler (str) – The URL where the login form is submitted.
  • post_login_url (str) – The URL/path where users should be redirected to after login.
  • logout_handler – The URL where the logout is handled.
  • post_logout_url (str) – The URL/path where users should be redirected to after logout.
  • login_counter_name (str) – The name of the variable in the query string that represents the login counter; defaults to __logins.
  • translations (dict) – The model translations.
  • cookie_timeout (int) – The time (in seconds) during which the session cookie would be valid.
  • cookie_reissue_time (int) – How often should the session cookie be reissued (in seconds); must be less than timeout.
  • use_default_authenticator (bool) – Whether the default SQL authenticator should be used.
Returns:

The WSGI application with authentication and authorization middleware.

It configures repoze.who with the following plugins:

  • Identifiers:

    • repoze.who.plugins.friendlyform.FriendlyFormPlugin as the first identifier and challenger – using login as the URL/path where the login form will be displayed, login_handler as the URL/path where the form will be sent and logout_handler as the URL/path where the user will be logged out. The so-called rememberer of such an identifier will be the identifier below.

      If post_login_url is defined, the user will be redirected to that page after login. Likewise, if post_logout_url is defined, the user will be redirected to that page after logout.

      You can override the repoze.who.plugins.friendlyform.FriendlyFormPlugin’s login counter variable name (which defaults to __logins) by defining login_counter_name.

      Tip

      This plugin may be overridden with the form_plugin argument. See also the form_identifies argument.

    • repoze.who.plugins.auth_tkt.AuthTktCookiePlugin. You can customize the cookie name and secret using the cookie_name and cookie_secret arguments, respectively.

    Then it will append the identifiers you pass through the identifiers keyword argument, if any.

  • Authenticators:

    • repoze.who.plugins.sa.SQLAlchemyAuthenticatorPlugin (unless use_default_authenticator is False), using the user_class and dbsession arguments as its user class and DB session, respectively.

    Then it will be appended to the authenticators you pass through the authenticators keyword argument, if any. The default authenticator would have the lowest precedence.

  • Challengers:

    • The same Form-based plugin used in the identifiers.

    Then it will append the challengers you pass through the challengers keyword argument, if any.

  • Metadata providers:

    • repoze.who.plugins.sa.SQLAlchemyUserMDPlugin, using the user_class and dbsession arguments as its user class and DB session, respectively.

    Then it will append the metadata providers you pass through the mdproviders keyword argument, if any.

The charset is passed to any component which needs to decode/encode data to/from the user. At present, only FriendlyFormPlugin does.

Additional keyword arguments will be passed to repoze.who.middleware.PluggableAuthenticationMiddleware.

Warning

It’s very important to set a custom cookie_secret! It’s the key to encrypt and decrypt the cookies, so you shouldn’t leave the default one.

Note

If you don’t want to use the groups/permissions-based authorization pattern, then set group_class and permission_class to None.

New in version 1.0.5: Introduced the cookie_timeout and cookie_reissue_time arguments.

New in version 1.0.6: Introduced the charset argument.

New in version 1.0.8: Introduced the use_default_authenticator argument.

New in version 1.0.9: Added support for the dummy_validate_password translation in repoze.who.plugins.sa.SQLAlchemyAuthenticatorPlugin v1.0.1.

See “changing attribute names” to learn how to use the translations argument in setup_sql_auth().

Customizing the model definition

Your auth-related model doesn’t have to be like the default one, where the class for your users, groups and permissions are, respectively, User, Group and Permission, and your users’ user name is available in User.user_name. What if you prefer Member and Team instead of User and Group, respectively? Or what if you prefer Group.members instead of Group.users? Read on!

Changing class names

Changing the name of an auth-related class (User, Group or Permission) is a rather simple task. Just rename it in your model, and then make sure to update the parameters you pass to setup_sql_auth() accordingly.

Changing attribute names

You can also change the name of the attributes assumed by repoze.what in your auth-related classes, such as renaming User.groups to User.memberships.

Changing such values is what repoze.what calls “translating”. You may set the translations for the attributes of the models repoze.what deals with in a dictionary passed to setup_sql_auth() as its translations parameters. For example, if you want to replace Group.users with Group.members, you may use the following translation dictionary:

translations['users'] = 'members'

Below are the translations that you would be able to set in the translations dictionary used above:

  • user_name: The translation for the attribute in User.user_name.
  • users: The translation for the attribute in Group.users.
  • group_name: The translation for the attribute in Group.group_name.
  • groups: The translation for the attribute in User.groups and Permission.groups.
  • permission_name: The translation for the attribute in Permission.permission_name.
  • permissions: The translation for the attribute in User.permissions and Group.permissions.
  • validate_password: The translation for the method in User.validate_password.