Enabling hgLogin: Difference between revisions

From genomewiki
Jump to navigationJump to search
m (→‎Introduction: grammar and clarity corrections)
(→‎Enabling hgLogin: clarified the instruction to leave cookie names the same as they were on genomewiki (RM #9662))
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Introduction==
==Introduction==


To ensure the privacy of saved sessions in the UCSC Genome Browser, a user must log in to the browser before
Prior to version 268, the UCSC Genome Browser was using the UCSC Genome Wiki website
using the session manager. 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 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  
to save sessions locally, the mirror site must have had the sign-in function provided by a simulated or locally-installed  
Line 15: Line 14:
The '''hgLogin''' CGI is designed to maintain complete backward compatibility with the genomewiki login system:
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 user name, password, email address and, most importantly, all the saved sessions are preserved. The user will notice no functional change.   
* 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 with sign-in function (via a simulated- or locally-installed mediawiki server).  When '''hgLogin''' is not enabled, all browser functions will continue to work as before
* 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==
==Enabling hgLogin==
Line 24: Line 23:
* Locate the genome browser configuration file '''hg.conf''' in your '''/cgi-bin/''' directory.  
* 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.
* 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'''
* 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'''
* Since the '''hgLogin''' CGI uses the same cookies as did the genomewiki, please do not modify these two configuration parameters:  
* 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.userNameCookie=wikidb_mw1_UserName       
  wiki.loggedInCookie=wikidb_mw1_UserID
  wiki.loggedInCookie=wikidb_mw1_UserID
* Add the 4 parameters for the UI headings '''(browserName)''' and text string used in emails '''(login.xxxxxx)''' send out to the userYou should set them to appropriate local values.
Otherwise, these parameters can be set to any name:
wiki.userNameCookie=myLabCookieNameForUserName
  wiki.loggedInCookie=myLabCookieNameForUseID


To summarize, You should have the following parameters in '''hg.conf''' to enable the '''hgLogin'''
* 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. 
  login.systemName=hgLogin CGI
 
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
  wiki.host=mylab.university.edu
  wiki.userNameCookie=wikidb_mw1_UserName
  wiki.loggedInCookie=wikidb_mw1_UserID
# 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
  login.browserName=myLab Genome Browser
# base url of browser install
  login.browserAddr=http://mylab.university.edu
  login.browserAddr=http://mylab.university.edu
# signature written at the bottom of hgLogin system emails
  login.mailSignature=My Lab browser administrator
  login.mailSignature=My Lab browser administrator
# from/return email address used for system emails
  login.mailReturnAddr=browserAdministrator@mylab.university.edu
  login.mailReturnAddr=browserAdministrator@mylab.university.edu


==Migration to hgLogin==
==Migration to hgLogin==


Mirror sites currently operating a local sign-in function can replace the local system with the '''hgLogin''' CGI.
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'''.
Migrate the user information to the '''gbMembers''' table in hgcentral, then edit the '''hg.conf''' to enable '''hgLogin'''.


Line 48: Line 66:


* The gbMembers table structure is supplied in the download copy of the '''hgcentral''' database: [http://hgdownload.cse.ucsc.edu/admin/hgcentral.sql hgcentral.sql]
* The gbMembers table structure is supplied in the download copy of the '''hgcentral''' database: [http://hgdownload.cse.ucsc.edu/admin/hgcentral.sql hgcentral.sql]
* Use the '''CREATE TABLE IF NOT EXISTS `gbMembers` (...)''' statement from that '''hgcentral.sql''' file.
* 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  
* Determine the name of the database and table used by mediawiki from the mediaWiki configuration file '''LocalSettings.php'''. Assuming the configuration has:
  $wgDBname          = "wikidb";
  $wgDBname          = "wikidb";
  $wgDBprefix        = "mw1_";
  $wgDBprefix        = "mw1_";
Line 56: Line 74:
  hgsql -e "select user_id,user_name,user_real_name,user_password,user_email,user_touched,user_email_authenticated  
  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
       from mw1_user;"  wikidb > wikidb.user.tab
* Import the '''wikidb.user.tab''' to '''hgcentral.gbMembers''' by
* Import the '''wikidb.user.tab''' to '''hgcentral.gbMembers''':
  hgsql -e "LOAD DATA LOCAL INFILE 'wikidb.user.tab' INTO TABLE gbMembers FIELDS TERMINATED BY '\t'  
  hgsql -e "LOAD DATA LOCAL INFILE 'wikidb.user.tab' INTO TABLE gbMembers FIELDS TERMINATED BY '\t'  
       LINES TERMINATED BY '\n' IGNORE 1 LINES;"  
       LINES TERMINATED BY '\n' IGNORE 1 LINES;"  

Latest revision as of 01:11, 6 April 2013

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.