FASWho Plugin

Authors:Luke Macken Toshio Kuratomi Date:3 September 2011

This plugin provides authentication to the Fedora Account System using the repoze.who WSGI middleware. It is designed for use with TurboGears2 but it may be used with any repoze.who using application. Like TurboGears Identity Provider 2, faswho has builtin CSRF protection. This protection is implemented as a second piece of middleware and may be used with other repoze.who authentication schemes.

Authenticating against FAS with TurboGears2

Setting up authentication against FAS in TurboGears2 is very easy. It requires one change to be made to app/config/app_cfg.py. This change will take care of registering faswho as the authentication provider, enabling CSRF protection, switching tg.url() to use fedora.ta2g.utils.url() instead, and allowing the _csrf_token parameter to be given to any URL.

Using CSRF middleware with other Auth Methods

This section needs to be made clearer so that apps like mirrormanager can be ported to use this.

Templates

The fedora.tg2.utils module contains some templates to help you write CSRF aware login forms and buttons. You can use the fedora_template() function to integrate them into your templates:

The templates themselves come in two flavors. One set for use with mako and one set for use with genshi.

Mako

Mako version of templates to make adding certain Fedora widgets easier.

fedora.tg2.templates.mako.login.mak

Module author: Toshio Kuratomi <tkuratom@redhat.com>

New in version 0.3.25.

Include this using:

<%namespace name="fedora" file="${context['fedora_template']('login.mak')}" />

fedora.tg2.templates.mako.login.mak.loginform(message='')

kwarg message:Any text or elements contained by the <loginform> tag will be shown as a message to the user. This is generally used to show status of the last login attempt (“Please provide your credentials”, “Supplied credentials were not correct”, etc)

A function for generating the main login form. This is a CSRF token-aware login form that will prompt for username and password when no session identity is present and ask the user to click a link if they merely lack a token.

Typical usage, given the above import of the login.mak template would be:

${fedora.loginform()}

fedora.tg2.templates.mako.login.mak.logintoolitem(href=None)

kwarg href:If an href is given, when a user is logged in, their username or display_name will be a link to the URL.

This function creates an entry into a toolbar for logging into a web app. The entry will contain the user’s username and a logout button if the user is logged in, a verify login button if the user has a session cookie but not a CSRF token, or a login button if the user doesn’t have a session cookie.

Typical usage looks like this:

<ul class="toolbar" id="#main-toolbar">
  ${fedora.logintoolitem(href=tg.url('/users/info'))}
</ul>

fedora.tg2.templates.mako.jsglobals.mak

Module author: Toshio Kuratomi <tkuratom@redhat.com>

New in version 0.3.25.

Include this using:

<%namespace name="jsglobals" file="${context['fedora_template']('jsglobals.mak')}" />

fedora.tg2.templates.mako.jsglobals.mak.jsglobals()

A function to add global variables to a page. Typically, you’d include this in your master.mak template and let the javascript variables defined there propogate to every page on your site (since they all should inherit from master.mak). This adds the following variables in the fedora namespace for other scripts to access:

fedora.baseurl:URL fragment to prepend to any calls to the application. In a TurboGears application, this is the scheme, host, and server.webpath. Example: https://admin.fedoraproject.org/pkgdb/. This may be a relative link. fedora.identity.anonymous:  If true, there will be no other variables in the fedora.identity namespace. If false, these variables are defined: fedora.identity.userid:  Numeric, unique identifier for the user fedora.identity.username:  Publically visible unique identifier for the user fedora.identity.display_name:  Common human name for the user fedora.identity.token:  csrf token for this user’s session to be added to urls that query the server.

Typical usage would be:

${jsglobals.jsglobals()}

Genshi

Genshi version of templates to make adding certain Fedora widgets easier.

fedora.tg2.templates.genshi.login.html

Module author: Toshio Kuratomi <tkuratom@redhat.com>

New in version 0.3.26.

Include this using::

<xi:include href=”${fedora_template(‘login.html’, template_type=’genshi’)}” />

fedora.tg2.templates.genshi.login.html.loginform([message])

message:Any text or elements contained by the <loginform> tag will be shown as a message to the user. This is generally used to show status of the last login attempt (“Please provide your credentials”, “Supplied credentials were not correct”, etc)

A match template for the main login form. This is a CSRF token-aware login form that will prompt for username and password when no session identity is present and ask the user to click a link if they merely lack a token.

Typical usage would be:

<loginform>${message}</loginform>

fedora.tg2.templates.genshi.login.html.logintoolitem(@href=URL)

@href:If an href attribute is present for this tag, when a user is logged in, their username or display_name will be a link to the URL.

A match template to add an entry to a toolbar. The entry will contain the user’s username and a logout button if the user is logged in, a verify login button if the user has a session cookie but not a CSRF token, or a login button if the user doesn’t have a session cookie.

Typical usage looks like this:

<ul class="toolbar" id="#main-toolbar">
  <logintoolitem href="${tg.url('/users/info')}" />
</ul>

fedora.tg2.templates.genshi.jsglobals.html

Module author: Toshio Kuratomi <tkuratom@redhat.com>

New in version 0.3.26.

Include this using::

<xi:include href=”${fedora_template(‘jsglobals.html’, template_type=’genshi’)}” />

fedora.tg2.templates.genshi.jsglobals.html.jsglobals()

A match template to add global variables to a page. Typically, you’d include this in your master.html template and let it be added to every other page from there. This adds the following variables in the fedora namespace for other scripts to access:

fedora.baseurl:URL fragment to prepend to any calls to the application. In a TurboGears application, this is the scheme, host, and server.webpath. Example: https://admin.fedoraproject.org/pkgdb/. This may be a relative link. fedora.identity.anonymous:  If true, there will be no other variables in the fedora.identity namespace. If false, these variables are defined: fedora.identity.userid:  Numeric, unique identifier for the user fedora.identity.username:  Publically visible unique identifier for the user fedora.identity.display_name:  Common human name for the user fedora.identity.token:  csrf token for this user’s session to be added to urls that query the server.

Typical usage would be:

<jsglobals />