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 &quot;redirect&quot; or
 &quot;callback&quot; 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&#39;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&#39;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>