Enabling hgLogin

Introduction

Prior to version 268, the UCSC Genome Browser was using the UCSC Genome Wiki website to handle the sign up, login, and logout functions for the session manager. In this context, for a mirror site to save sessions locally, the mirror site must have had the sign-in function provided by a simulated or locally-installed mediawiki server.

Starting with v268, the UCSC Genome Browser introduced the hgLogin CGI to replace Genomewiki as the login manager. The user management functions are now handled by the built-in hgLogin CGI together with the gbMembers table in the hgcentral database. Starting from v269, mirror sites can use the hgLogin CGI to handle the user management directly without mediawiki.

Backward compatibility

The hgLogin CGI is designed to maintain complete backward compatibility with the genomewiki login system:

• For current UCSC Genome Browser users, the transition from genomewiki to hgLogin is transparent. The username, password, email address and, most importantly, all the saved sessions are preserved. The user will notice no functional change.
• The hgSession and hgLogin CGIs are designed to use the same cookies that are used by genomewiki. This design provides complete backwards compatibility to current mirror sites using the login function (via a simulated- or locally-installed mediawiki server). When hgLogin is not enabled, all browser functions will continue to work as before.

Enabling hgLogin

Procedure to enable the hgLogin CGI on a Genome Browser mirror:

• Locate the genome browser configuration file hg.conf in your /cgi-bin/ directory.
• Add the statement login.systemName=hgLogin CGI to the hg.conf file.
• Also in the hg.conf file, change the host value in the "wiki.host" entry to point to your mirror browser host running the hgLogin CGI. The host should be in the same domain as value set in "central.domain". For example, if central.doman=.university.edu then set wiki.host=mylab.university.edu
• If you are migrating from the old genomewiki login system and want the hgLogin CGI to use the same cookies as did the genomewiki, do not modify these two configuration parameters:

wiki.userNameCookie=wikidb_mw1_UserName       
wiki.loggedInCookie=wikidb_mw1_UserID

Otherwise, these parameters can be set to any name:

wiki.userNameCookie=myLabCookieNameForUserName
wiki.loggedInCookie=myLabCookieNameForUseID

• Add the 4 login.xxxxxx parameters for the user interface (UI) headings (browserName) and text string used in emails (login.xxxxxx) send out to the user. You should set them to appropriate local values.

To summarize, the following parameters should be in hg.conf to enable hgLogin:

# required to use hgLogin
login.systemName=hgLogin CGI   

# url to server hosting hgLogin
wiki.host=mylab.university.edu

# name of cookie holding username
wiki.userNameCookie=myLabCookieNameForUserName

# name of cookie holding user id
wiki.loggedInCookie=myLabCookieNameForUseID

# title of host of browser, this text will be shown in the user interface of the login/sign up screens
login.browserName=myLab Genome Browser

# base url of browser install 
login.browserAddr=http://mylab.university.edu

# signature written at the bottom of hgLogin system emails
login.mailSignature=My Lab browser administrator

# from/return email address used for system emails
login.mailReturnAddr=browserAdministrator@mylab.university.edu

Migration to hgLogin

Mirror sites currently operating a local login function can replace the local system with the hgLogin CGI. Migrate the user information to the gbMembers table in hgcentral, then edit the hg.conf to enable hgLogin.

Procedure to migrate from mediawiki to hgLogin:

• The gbMembers table structure is supplied in the download copy of the hgcentral database: hgcentral.sql
• Use the CREATE TABLE IF NOT EXISTS 'gbMembers' (...) statement from the hgcentral.sql file.
• Determine the name of the database and table used by mediawiki from the mediaWiki configuration file LocalSettings.php. Assuming the configuration has:

$wgDBname           = "wikidb";
$wgDBprefix         = "mw1_";

Then, the table name mw1_user and database name wikidb are used.

• Export the user table into a file wikidb.user.tab:

hgsql -e "select user_id,user_name,user_real_name,user_password,user_email,user_touched,user_email_authenticated 
     from mw1_user;"  wikidb > wikidb.user.tab

• Import the wikidb.user.tab to hgcentral.gbMembers:

hgsql -e "LOAD DATA LOCAL INFILE 'wikidb.user.tab' INTO TABLE gbMembers FIELDS TERMINATED BY '\t' 
     LINES TERMINATED BY '\n' IGNORE 1 LINES;" 

• Set the two status fields:

hgsql -e "update gbMembers set passwordChangeRequired='N';" hgcentral
hgsql -e "update gbMembers set accountActivated='Y';" hgcentral

• Enable hgLogin with the modifications to hg.conf as described above.