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/product/mirrorManual.txt src/product/mirrorManual.txt
index 636548beb08..38d50177ff0 100644
--- src/product/mirrorManual.txt
+++ src/product/mirrorManual.txt
@@ -1421,59 +1421,75 @@
 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.
 
 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.
 
 ## Social sign-in (Google, ORCID, GitHub, or any OpenID Connect provider)
 
 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:
+
+    Google:  https://console.cloud.google.com/auth/clients
+    ORCID:   https://orcid.org/developer-tools
+    GitHub:  https://github.com/settings/applications/
+
+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:
 
     login.oauth.providers=google,orcid,github,myuni
 
 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):
 
     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
 
 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:
 
     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
 
+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):
+
+    CILogon, for US universities:        https://cilogon.org/oauth2/register
+    LifeScience RI, for EU universities: https://services.aai.lifescience-ri.eu/spreg/auth
+
 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.)
 
 ## Passwordless email sign-in link, and changing the account email
 
     login.emailLink=on
 
 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