Difference between revisions of "GBrowse Configuration/Authentication"

Revision as of 22:19, 17 January 2011

This article describes HTTP authentication and how to configure it to work with GBrowse.

For the main GBrowse2 configuration article, see: GBrowse 2.0 HOWTO.

Authentication & Authorization, Introduction

You can restrict who has access to gbrowse by IP address, host name, domain, username and password, by OpenID, or, via the authentication plugin mechanism, by site-specific restrictions such as possession of a crypto card. Restriction can apply to the database as a whole, or to particular annotation tracks. You can also make a datasource visible only to authorized users.

Authentication Systems

As of version 2.20, GBrowse has three distinct authentication mechanisms:

1. Authentication via Apache's built-in authentication modules (present in all versions of GBrowse).
2. Authentication via a built-in user accounts database (GBrowse versions 2.16 and higher).
3. Authentication via a plugin architecture (GBrowse 2.20 and higher).

The first mechanism uses Apache's standard authentication and authorization modules. This provides you with a large number of authentication backends, but users will not be able to examine and change their credentials unless you install a third-party application for managing Apache authentication.

The second mechanism provides an "accounts database" that is accessible to the server that is running GBrowse. The database is either a local SQLite database, or a local/remote MySQL database. This mechanism provides a way for users to register themselves (if registration is enabled), and allows users to associate OpenIDs with their accounts for one-click login. Users can change their passwords and other information such as their full name and email address.

The third mechanism uses authentication plugins that are similar in spirit to other GBrowse plugins. Plugins can be written to implement a variety of authentication mechanisms, and are intended to be used by organizations to allow users to use the same authentication mechanism for GBrowse as they use for other organizational assets. This mechanism does not allow users to inspect or change their credentials, but one can easily add a link to the login dialogue that directs them to the organization's web site to help them with this. Authentication plugins do, however, provide the ability to restrict access to role-based groups, something that neither of the other two mechanisms allows. Currently there is a single GBrowse authentication plugin defined, the PamAuthenticate plugin, which authenticates users via the Pluggable Authentication Module (PAM) system, and fetches groups from whatever group database is defined in /etc/nsswitch.conf.

GBrowse Authentication via Apache's Built-in Authentication Modules

To use Apache's standard authentication and authorization system, we take advantage of the fact that GBrowse uses a URL of this form to select which data source is active:

     http://your.host/cgi-bin/gb2/gbrowse/your_datasource

where "your_datasource" is the name of the currently selected datasource. For example, the yeast datasource is http://your.host/cgi-bin/gbrowse/yeast.

Apache's access control mechanism is based on URLs. To control access to an entire datasource, create a <Location> section in httpd.conf. The <Location> section should look like this:

  <Location /cgi-bin/gb2/gbrowse/your_datasource>
       Order deny,allow
       deny from all
       allow from localhost .oicr.on.ca .cshl.edu .ebi.ac.uk
  </Location>

This denies access to everybody except for "localhost" and browsers from the domains .oirc.on.ca, .cshl.edu and .ebi.ac.uk. You can also limit by IP address, by username and password or by combinations of these techniques. See Apache Authentication for the full details. Note that the datasource will still be visible in the pop-up menu of datasources in the GBrowse navigation panel, unless you specify "hide=1" in the GBrowse.conf stanza that defines the datasource.

You can limit individual tracks to certain individuals or organizations. Unless the stated requirements are met, the track will not appear on the main screen or any of the configuration screens. To set this up, add a "restrict" option to the track you wish to make off-limits:

       [PROPRIETARY]
       feature = etc
       glyph   = etc
       restrict = Order deny,allow
                  deny from all
                  allow from localhost .oicr.on.ca .cshl.edu .ebi.ac.uk

The value of the restrict option is identical to the Apache authorization directives and can include any of the directives "Order," "Satisfy," "deny from," "allow from," "require valid-user" or "require user." The only difference is that the "require group" directive is not supported, since the location of Apache's group file is not passed to CGI scripts.

As with other gbrowse options, restrict can be a code subroutine. The subroutine will be called with three arguments consisting of the host, ip address and authenticated user. It should return a true value to allow access to the track, or a false value to forbid it. This can be used to implement group-based authorization or more complex schemes.

Here is an example that uses the Text::GenderFromName to allow access if the user's name sounds female and forbids access if the name sounds male. (It might be useful for an X-chromosome annotation site.)

<perl>restrict = sub {

              my ($host,$ip,$user) = @_;
              return unless defined $user;
              use Text::GenderFromName qw(gender);
              return gender($user) eq 'f';
            }</perl>

You should be aware that the username will only be defined if username authentication is turned on and the user has successfully authenticated himself against Apache's user database using the correct password. In addition, the hostname will only be defined if HostnameLookups have been turned on in httpd.conf. In the latter case, you can convert the IP address into a hostname using this piece of code:

<perl> use Socket;

   $host = gethostbyaddr(inet_aton($addr),AF_INET);</perl>

Note that this may slow down the response time of gbrowse noticeably if you have a slow DNS name server.

Another thing to be aware of when restricting access to an entire database is that that even though the database itself will not be accessible to unauthorized users, the name of the database will still be available from the popup "Data Source" menu. There are two ways to suppress this display:

1. Place "hide=1" in the GBrowse.conf stanza that defines the datasource. This will hide the source from all users, even those who are allowed to access it.
2. Place a "restrict" option in the GBrowse.conf stanza that defines the datasource. In this way, only users who meet the requirements will be able to see and select the datasource. For example:

[yeast]
description = Yeast Chromosomes 1+2
path        = yeast_simple.conf
restrict    = require valid-user

Finally, you may place a "restrict" option in the [GENERAL] section of an individual datasource conf file, in which case the restrictions are applied on top of those defined by Apache. This might be useful if you prefer to modify the GBrowse conf file rather than Apache's conf file. For example, if Apache's config file contains this section:

   <Location /cgi-bin/gb2/gbrowse/yeast>
       Order deny,allow
       deny from all
       Satisfy all
       allow from .oicr.on.ca
       require valid-user
  </Location>

then any valid user (who can provide a recognized username and password) who accesses the site from a workstation in the .oicr.on.ca domain will be able to get in. You can further restrict access by adding the following to the [GENERAL] section of yeast_simple.conf:

 [GENERAL]
  # .... other stuff ...
  restrict  = require user fred joseph andrew vivian

This will return an unauthorized message for anyone except the four named users.

GBrowse Authentication via its Built-in User Accounts

The GBrowse user account system provides users with a link in the upper right corner of the screen that lets them login, register, and manage their account settings.

Configuration

The GBrowse user account system is activated when the following requirements are met:

1. The Perl DBI module is installed, and one or both of DBD::mysql and DBD::SQLite.
2. The "user accounts" option is set to a "1" (or any other true value) in GBrowse.conf's [GENERAL] section.
3. No "authentication plugin" option is defined in GBrowse.conf's [GENERAL] section.

User accounts can be created and managed with the utilities gbrowse_create_account.pl and gbrowse_change_passwd.pl. Users can register themselves and manage their own account settings if:

1. The Perl Net::SMTP module is installed (required to validate users via email).
2. The "user accounts registration" option is set to a true value in GBrowse.conf.
3. The "user_account_db" option is set to a valid MySQL or SQLite path.
4. The "smtp_gateway" is set to a working mail gateway that can forward mail to end users.

To enable users to log in using OpenIDs, these requirements must be met:

1. The Perl Net::OpenID::Consumer module must be installed.
2. The "user_accounts_openid" option in the [GENERAL] section of GBrowse.conf should be set to a true value.

The following is a GBrowse.conf configuration file with all the bells and whistles turned on:

[GENERAL]
# ...lots of stuff...

# Login Settings
user_accounts               = 1
user_accounts_registration  = 1
user_accounts_openid        = 1
user_account_db             = DBI:SQLite:/var/www/gbrowse2/databases/users.sqlite
smtp_gateway                = localhost
application_name            = GBrowse
application_name_long       = The Generic Genome Browser
email_address               = noreply@gbrowse.com

This configuration should work on most servers provided that there is a properly-configured mail exchanger running on the server itself. You will need to replace this with an appropriate mail exchanger if this is not the case. The format of this option is described in more detail below. In the case of new installations of GBrowse2 (versions 2.20 and higher), the installer will detect if the prerequisites are present, and establish reasonable starting values.

Here is more information on these options:

user_account_db

This is a Perl DBI-style description of the database that will hold user accounts. Only SQLite and MySQL databases are usable at the current time. For MySQL databases, the full form of the option is:

 DBI:mysql:database=gbrowse_login;host=mysql.oicr.on.ca;user=gbrowse;password=gbrowse

This indicates that the account database is running on a MySQL server named "mysql.oicr.on.ca" and that the database is named "gbrowse_login". The GBrowse application will use the username "gbrowse" and the password "gbrowse" to access the database.

For SQLite databases, the format is:

 DBI:SQLite:/var/www/gbrowse2/databases/users.sqlite

The latter part of the description is a path to the database file.

user_accounts, user_accounts_registration, user_accounts_openid

These options turn on and off user accounts, new users' ability to register themselves and OpenID support, respectively. Pass a true value (usually "1" to turn the feature on). Pass a false value ("0" or just comment out the option) to turn the feature off.

User Account Database Care and Maintenance

Permissions: For GBrowse2 to be able to accept new user registrations and to allow users to change their account information, the web user (e.g. "www-data") must have write privileges on the user account database. In the case of a SQLite database, this means that the database file and the directory that contains it must be writable by the web user. For MySQL databases, the MySQL user ("gbrowse" in the example above) must have SELECT, INSERT, DELETE and UPDATE privileges. The gbrowse_metadb_config.pl script will check and fix the permissions for you.

GBrowse Authentication via Authentication Plugins