1e1b78acdbd86ed07b3301aaf3061a3a57f95264 max Tue Aug 4 03:16:26 2026 -0700 mirrorManual: document hgLogin social sign-in (Google/ORCID/GitHub/OIDC) and email sign-in link config. refs #37984 diff --git src/hg/htdocs/goldenPath/help/mirrorManual.html src/hg/htdocs/goldenPath/help/mirrorManual.html index 808905ad986..1d5e61e608a 100755 --- src/hg/htdocs/goldenPath/help/mirrorManual.html +++ src/hg/htdocs/goldenPath/help/mirrorManual.html @@ -15,30 +15,31 @@ <h1>Manual installation of the UCSC Genome Browser on a Unix server</h1> <h2>Contents</h2> <h6><a href='#overview-of-the-genome-browser-directories-and-databases'>Overview of the Genome Browser directories and databases</a></h6> <h6><a href='#software-requirements'>Software Requirements</a></h6> <h6><a href='#hardware-and-disk-space-requirements'>Hardware and disk space requirements</a></h6> <h6><a href='#installing-the-ucsc-genome-browser'>Installing the UCSC Genome browser</a></h6> <h6><a href='#mariadb-setup'>MariaDB Setup</a></h6> <h6><a href='#local-git-repository-aka-quotthe-source-treequot'>Local Git repository (aka: "the source tree")</a></h6> <h6><a href='#adding-your-own-track-groups-to-the-browser'>Adding your own track groups to the browser</a></h6> <h6><a href='#adding-your-own-tracks-to-the-browser'>Adding your own tracks to the browser</a></h6> <h6><a href='#adding-a-new-custom-non-ucsc-genome-to-the-browser'>Adding a new, custom (non-UCSC) genome to the browser</a></h6> <h6><a href='#modifying-the-source-code'>Modifying the source code</a></h6> <h6><a href='#custom-track-database'>Custom Track Database</a></h6> <h6><a href='#debugging-the-cgi-binaries'>Debugging the CGI binaries</a></h6> <h6><a href='#notes-on-security'>Notes on security</a></h6> +<h6><a href='#user-login-social-sign-in-and-email-sign-in-links'>User login: social sign-in and email sign-in links</a></h6> <h6><a href='#proxy-support'>Proxy support</a></h6> <h6><a href='#support-for-cloud-urls'>Support for cloud URLs</a></h6> <h6><a href='#the-udc-local-cache-directory'>The UDC local cache directory</a></h6> <h6><a href='#activating-cram-support-for-the-genome-browser'>Activating CRAM support for the Genome Browser.</a></h6> <h6><a href='#using-freetype-font-support-for-anti-aliased-text'>Using FreeType font support for anti-aliased text</a></h6> <h6><a href='#adding-a-new-font-to-the-genome-browser-display'>Adding a new font to the Genome Browser display</a></h6> <h6><a href='#building-the-kent-source-tree'>Building the kent source tree.</a></h6> <h6><a href='#adding-a-track-hub-to-your-hubpublic-table-so-it-appears-under-my-data-gt-track-hubs'>Adding a track hub to your hubPublic table so it appears under My Data > Track Hubs</a></h6> <h6><a href='#make-the-api-work-in-the-same-way-as-on-the-public-website'>Make the API work in the same way as on the public website</a></h6> <h6><a href='#set-up-the-cloudflare-captcha'>Set up the Cloudflare captcha</a></h6> <p> We do not recommend following the procedure below anymore, as we provide a docker image and the "GBIC" installation bash script. They can setup a genome browser with a single linux command line and within a few minutes. This page exists as a reference, explains how the installer is structured and helps changing the @@ -1916,30 +1917,113 @@ data from external URLs is shown, and even though the HTML tags are interpreted, Javascript in these pages is not executed, so an XSS exploit is not possible through these. We use CSP and a nonce to block Javascript injection in these pages. CSP/nonce is a system that many security scanners do not recognize. You can disregard XSS warnings from the security scanners and refer your IT department to our CSP declarations in the HTML headers unless you think that you found a case where it is possible to get through the CSP/nonce system. Feel free to send us the security report from your scanner when in doubt.</li> <li>Our CSP/nonce system also secures the Javascript libraries. We use customized jquery libraries from the mid-2000s. Some of these are outdated, so some security scanners deem them unsafe, but our use of CSP and a nonce means that possible XSS problems cannot be exploited. The security scanners also cannot detect that. To reduce these warnings, we are in the process of upgrading our Javascript dependencies where possible.</li> </ul> +<a name='user-login-social-sign-in-and-email-sign-in-links'></a> +<h2>User login: social sign-in and email sign-in links</h2> + +<p> +User accounts on the Genome Browser are handled by the hgLogin CGI, with the accounts stored +in the gbMembers table of the hgcentral database. An account lets a user save and share named +sessions. Enabling the login system itself (the login.systemName, wiki.host and cookie +settings) is described at http://genomewiki.ucsc.edu/index.php/Enabling_hgLogin and in the +comments of the example hg.conf. Once login is enabled, users can register with a username +and password. The settings below add three optional, and by default disabled, extra ways to +sign in. +</p> + +<p> +A note on secrets first: the file cgi-bin/hg.conf is part of the source tree and is not +private, so it must never contain passwords or OAuth client secrets. Put all secrets in +cgi-bin/hg.conf.private, a file that hg.conf includes and that is not shared. Non-secret +settings such as the provider list, labels and endpoint URLs can live in either file. +</p> + +<h2 id="social-sign-in-google-orcid-github-or-any-openid-connect-provider">Social sign-in (Google, ORCID, GitHub, or any OpenID Connect provider)</h2> + +<p> +You can let users sign in with an external identity provider using OAuth 2.0 / OpenID +Connect. First register an OAuth client with each provider and set its "redirect" or +"callback" URL to your hgLogin URL exactly, for example +https://yourbrowser.university.edu/cgi-bin/hgLogin . Then list the providers to offer and +give each one a block of settings: +</p> + +<pre><code>login.oauth.providers=google,orcid,github,myuni</code></pre> + +<p> +The names google, orcid and github are recognized and come with built-in endpoints, so they +only need a client id and secret (put the secrets in hg.conf.private): +</p> + +<pre><code>login.oauth.google.clientId=xxxxxxxx.apps.googleusercontent.com +login.oauth.google.clientSecret=xxxxxxxx +login.oauth.orcid.clientId=APP-XXXXXXXXXXXXXXXX +login.oauth.orcid.clientSecret=xxxxxxxx +login.oauth.github.clientId=Iv1.xxxxxxxx +login.oauth.github.clientSecret=xxxxxxxx</code></pre> + +<p> +Any other OpenID Connect server works too. Give it a label (used on the button), credentials, +and either an issuer, from which the endpoints are discovered automatically, or the three +endpoint URLs written out explicitly: +</p> + +<pre><code>login.oauth.myuni.label=My University +login.oauth.myuni.clientId=xxxx +login.oauth.myuni.clientSecret=xxxx +login.oauth.myuni.issuer=https://idp.myuni.edu +# ... or, instead of the issuer line, spell out the endpoints: +login.oauth.myuni.authUrl=https://idp.myuni.edu/authorize +login.oauth.myuni.tokenUrl=https://idp.myuni.edu/token +login.oauth.myuni.userinfoUrl=https://idp.myuni.edu/userinfo +login.oauth.myuni.scopes=openid email profile</code></pre> + +<p> +A provider's button appears on the login and sign-up pages only when both its client id and +secret are set, so unconfigured mirrors are unaffected. When a provider reports an email +address that it has verified, and that address matches an existing account, that account is +automatically linked to the new identity and the user is signed in; if the address matches +several accounts, the user is asked which one to use. GitHub is a plain OAuth 2.0 provider +rather than OpenID Connect and is handled as a special case; it is the only non-OIDC provider +supported without extra code. (The older, un-prefixed keys login.google.clientId and +login.orcid.clientId are still recognized for backward compatibility.) +</p> + +<h2 id="passwordless-email-sign-in-link-and-changing-the-account-email">Passwordless email sign-in link, and changing the account email</h2> + +<pre><code>login.emailLink=on</code></pre> + +<p> +When this is on, the login page offers an "Email me a sign-in link" option: the user types +their email address and receives a one-time link that signs them in without a password, which +is convenient on a computer where the password is not saved. The same switch also enables the +"Change email" option in the account menu. It is off by default and needs working outbound +email (see login.mailReturnAddr), so turn it on only where email delivery is configured. +</p> + <a name='proxy-support'></a> <h2>Proxy support</h2> <p> net.c now has support for http(s) proxy servers which may be required by some installations to get through the firewall to external resources such as (but not limited to) for example bigWig or bigBed data via custom track bigDataUrl. </p> <p> One must add the setting "httpProxy", "httpsProxy", "ftpProxy" to hg.conf </p>