30bd9b2986b3dfd6ce6023fb6302423efc68e04b max Tue Aug 4 04:14:29 2026 -0700 mirrorManual: add OAuth provider registration URLs (Google/ORCID/GitHub, and CILogon/LifeScienceRI for universities). refs #37984 diff --git src/hg/htdocs/goldenPath/help/mirrorManual.html src/hg/htdocs/goldenPath/help/mirrorManual.html index 1d5e61e608a..99b5fb7e024 100755 --- src/hg/htdocs/goldenPath/help/mirrorManual.html +++ src/hg/htdocs/goldenPath/help/mirrorManual.html @@ -1943,32 +1943,43 @@ </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: +https://yourbrowser.university.edu/cgi-bin/hgLogin . You create the client id and secret at +each provider's developer console: +</p> + +<pre><code>Google: https://console.cloud.google.com/auth/clients +ORCID: https://orcid.org/developer-tools +GitHub: https://github.com/settings/applications/</code></pre> + +<p> +For GitHub you can register a whole domain, such as gi.ucsc.edu, which then covers all of its +subdomains (handy if you have several sandboxes); the other providers require each exact +hostname to be listed. 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> @@ -1977,30 +1988,39 @@ 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> +Two OpenID Connect federations are useful for reaching many universities at once, without +registering separately with each institution. Register with them and configure them like any +other OIDC provider above (a label, client id/secret and issuer): +</p> + +<pre><code>CILogon, for US universities: https://cilogon.org/oauth2/register +LifeScience RI, for EU universities: https://services.aai.lifescience-ri.eu/spreg/auth</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>