Enabling hgLogin

Introduction

To ensure privacy of saved sessions in the UCSC Genome Browser, a user must log in to the browser before using the session manager. Prior to version 268, the UCSC Genome Browser was using UCSC Genome Wiki website to handle the sign up, login, and logout functions for the session manager. Previously, for a mirror site to save sessions locally, the mirror site must have sign-in function provided by a simulated or locally-installed mediawiki server.

Starting with V268, the UCSC Genome Browser introduced a hgLogin CGI to replace the genomewiki. The user management functions will be handled by the built-in hgLogin CGI together with the "gbMembers" table in the hgcentral database. Starting from Version V269, mirror site 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:

1. For current UCSC Genome Browser user, the transition from genomewiki to hgLogin is transparent. The user name, password, email address and, most importantly, all the saved sessions are preserved. The user will not notice any function change at all.
2. Since the hgSession and hgLogin CGIs are designed to use the same cookies that used to be used by mediawiki. This design provides complete backwards compatibility to current mirror sites with sign-in function (via a simulated- or locally-installed mediawiki server). As long as hgLogin is not enabled, All browser functions will continue to work as before

Enabling hgLogin

Here are the steps necessary to enable the hgLogin CGI on a Genome Browser mirror:

1. Locate the genome browser configuration file "hg.conf" in your /cgi-bin directory.
2. Add the statement "login.systemName=hgLogin CGI" to the hg.conf file.
3. Also in the hg.conf file, change the host value in the "wiki.host" entry to point to your mirror browser host that 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"
4. Since the hgLogin CGI uses the same cookies as mediawiki used to, please do not modify these two configuration parameters:

    wiki.userNameCookie=wikidb_mw1_UserName       
    wiki.loggedInCookie=wikidb_mw1_UserID
   

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

To summarize, You should have the following parameters in hg.conf to enable the hgLogin"

        login.systemName=hgLogin CGI
        wiki.host=mylab.university.edu
        wiki.userNameCookie=wikidb_mw1_UserName
        wiki.loggedInCookie=wikidb_mw1_UserID

        login.browserName=myLab Genome Browser
        login.browserAddr=http://mylab.university.edu
        login.mailSignature=My Lab browser administrator
        login.mailReturnAddr=browserAdministrator@mylab.university.edu

Migration to hgLogin

For current mirror sites with local sign-in function, you can replace your sign-in system with hgLogin CGI. You need to migrate the user information to gbMembers table in hgcentral first, then edit the hg.conf to enable the hgLogin.

Assuming you are migrating from mediawiki to hgLogin, here are the steps you must take:

1. Understand the structure of the gbMembers table in hgcentral database. Please study the gbMembers table structure in

       
      http://hgdownload.cse.ucsc.edu/admin/hgcentral.sql
   

2. Create the gbMembers table in hgcentral based "REATE TABLE IF NOT EXISTS `gbMembers` (...)" statement in the hgcentral.sql.
3. Find out the names of 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.

4. Export the user table table wikidb.user.tab using:

         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
   

5. Import the wikidb.user.tab to gbMembers by

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

6. Set the two status fields by:

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

7. Enable hgLogin by modifying hg.conf as described above.