Support other nextstrain.org-like remotes

Adds support for other nextstrain.org-like remotes to the `nextstrain
remote` family of commands, along with support for OIDC/OAuth2
authentication with them to the `nextstrain login` and related commands.
Required IdP and client configuration for OIDC/OAuth2 is
auto-discovered.

One giant pile of changes, because I did not have time to go thru my
typical editing and splitting process before going on leave. :/ Ah well.

Related-to: <nextstrain/private#94>

Author: tsibley

doc/commands/authorization.rst

@@ -12,21 +12,35 @@ nextstrain authorization
 
 .. code-block:: none
 
-    usage: nextstrain authorization [-h]
+    usage: nextstrain authorization [-h] [<remote-url>]
 
 
-Produce an Authorization header appropriate for nextstrain.org's web API.
+Produce an Authorization header appropriate for the web API of nextstrain.org
+(and other remotes).
 
 This is a development tool unnecessary for normal usage.  It's useful for
-directly making API requests to nextstrain.org with `curl` or similar
-commands.  For example::
+directly making API requests to nextstrain.org (and other remotes) with `curl`
+or similar commands.  For example::
 
     curl -si https://nextstrain.org/whoami \
         --header "Accept: application/json" \
         --header @<(nextstrain authorization)
 
 Exits with an error if no one is logged in.
 
+positional arguments
+====================
+
+
+
+.. option:: <remote-url>
+
+    Remote URL for which to produce an Authorization header.  Expects
+    URLs like the remote source/destination URLs used by the
+    `nextstrain remote` family of commands.  Only the domain name
+    (technically, the origin) of the URL is required/used, but a full
+    URL may be specified.
+
 options
 =======
 

doc/commands/index.rst

@@ -74,11 +74,11 @@ commands
 
 .. option:: login
 
-    Log into Nextstrain.org. See :doc:`/commands/login`.
+    Log into Nextstrain.org (and other remotes). See :doc:`/commands/login`.
 
 .. option:: logout
 
-    Log out of Nextstrain.org. See :doc:`/commands/logout`.
+    Log out of Nextstrain.org (and other remotes). See :doc:`/commands/logout`.
 
 .. option:: whoami
 

doc/commands/login.rst

@@ -12,23 +12,37 @@ nextstrain login
 
 .. code-block:: none
 
-    usage: nextstrain login [-h] [--username <name>] [--no-prompt] [--renew]
+    usage: nextstrain login [-h] [--username <name>] [--no-prompt] [--renew] [<remote-url>]
 
 
-Log into Nextstrain.org and save credentials for later use.
+Log into Nextstrain.org (and other remotes) and save credentials for later use.
 
-The first time you log in, you'll be prompted for your Nextstrain.org username
-and password.  After that, locally-saved authentication tokens will be used and
-automatically renewed as needed when you run other `nextstrain` commands
-requiring log in.  You can also re-run this `nextstrain login` command to force
-renewal if you want.  You'll only be prompted for your username and password if
-the locally-saved tokens are unable to be renewed or missing entirely.
+The first time you log in to a remote you'll be prompted to authenticate via
+your web browser or, if you provide a username (e.g. with --username), for your
+Nextstrain.org password.  After that, locally-saved authentication tokens will
+be used and automatically renewed as needed when you run other `nextstrain`
+commands requiring log in.  You can also re-run this `nextstrain login` command
+to force renewal if you want.  You'll only be prompted to reauthenticate (via
+your web browser or username/password) if the locally-saved tokens are unable
+to be renewed or missing entirely.
 
-If you log out of Nextstrain.org on other devices/clients (like your web
-browser), you may be prompted to re-enter your username and password by this
-command sooner than usual.
+If you log out of Nextstrain.org (or other remotes) on other devices/clients
+(like your web browser), you may be prompted to reauthenticate by this command
+sooner than usual.
 
-Your password itself is never saved locally.
+Your username and password themselves are never saved locally.
+
+positional arguments
+====================
+
+
+
+.. option:: <remote-url>
+
+    Remote URL to log in to, like the remote source/destination URLs
+    used by the `nextstrain remote` family of commands.  Only the
+    domain name (technically, the origin) of the URL is required/used,
+    but a full URL may be specified.
 
 options
 =======
@@ -45,7 +59,7 @@ options
 
 .. option:: --no-prompt
 
-    Never prompt for a username/password; succeed only if there are login credentials in the environment or existing valid/renewable tokens saved locally, otherwise error.  Useful for scripting.
+    Never prompt for authentication (via web browser or username/password); succeed only if there are login credentials in the environment or existing valid/renewable tokens saved locally, otherwise error.  Useful for scripting.
 
 .. option:: --renew
 
@@ -62,4 +76,7 @@ of interactive input and/or command-line options:
 .. envvar:: NEXTSTRAIN_PASSWORD
 
     Password for nextstrain.org user.  Required if :option:`--no-prompt` is
-    used without existing valid/renewable tokens.
+    used without existing valid/renewable tokens.
+
+If you want to suppress ever opening a web browser automatically, you
+may set the environment variable ``NOBROWSER=1``.

doc/commands/logout.rst

@@ -12,16 +12,29 @@ nextstrain logout
 
 .. code-block:: none
 
-    usage: nextstrain logout [-h]
+    usage: nextstrain logout [-h] [<remote-url>]
 
 
-Log out of Nextstrain.org by deleting locally-saved credentials.
+Log out of Nextstrain.org (and other remotes) by deleting locally-saved
+credentials.
 
 The authentication tokens are removed but not invalidated, so if you used them
 outside of the `nextstrain` command, they will remain valid until they expire.
 
 Other devices/clients (like your web browser) are not logged out of
-Nextstrain.org.
+Nextstrain.org (or other remotes).
+
+positional arguments
+====================
+
+
+
+.. option:: <remote-url>
+
+    Remote URL to log out of, like the remote source/destination URLs
+    used by the `nextstrain remote` family of commands.  Only the
+    domain name (technically, the origin) of the URL is required/used,
+    but a full URL may be specified.
 
 options
 =======

doc/commands/whoami.rst

@@ -12,16 +12,29 @@ nextstrain whoami
 
 .. code-block:: none
 
-    usage: nextstrain whoami [-h]
+    usage: nextstrain whoami [-h] [<remote-url>]
 
 
-Show information about the logged-in user.
+Show information about the logged-in user for Nextstrain.org (and other
+remotes).
 
-The username, email address, and Nextstrain Groups memberships of the currently
-logged-in user are shown.
+The username, email address (if available), and Nextstrain Groups memberships
+of the currently logged-in user are shown.
 
 Exits with an error if no one is logged in.
 
+positional arguments
+====================
+
+
+
+.. option:: <remote-url>
+
+    Remote URL for which to show the logged-in user.  Expects URLs like
+    the remote source/destination URLs used by the `nextstrain remote`
+    family of commands.  Only the domain name (technically, the origin)
+    of the URL is required/used, but a full URL may be specified.
+
 options
 =======
 

doc/development.md

@@ -59,13 +59,23 @@ resources from our ["testing" configuration][], you can configure `nextstrain`
 with the same, e.g.:
 
     export NEXTSTRAIN_DOT_ORG=http://localhost:5000
-    export NEXTSTRAIN_COGNITO_USER_POOL_ID="$(jq -r .COGNITO_USER_POOL_ID ../nextstrain.org/env/testing/config.json)"
-    export NEXTSTRAIN_COGNITO_CLI_CLIENT_ID="$(jq -r .OAUTH2_CLI_CLIENT_ID ../nextstrain.org/env/testing/config.json)"
 
     nextstrain login
     nextstrain whoami
     nextstrain remote ls groups/test-private
 
+Most of the times the above is not necessary, however, as you can specify the
+local remote explicitly instead of pretending it's nextstrain.org, e.g.:
+
+    nextstrain remote ls http://localhost:5000/groups/test
+
+    nextstrain login http://localhost:5000
+    nextstrain whoami http://localhost:5000
+    nextstrain remote ls http://localhost:5000/groups/test-private
+
+Setting `NEXTSTRAIN_DOT_ORG` is mostly useful when testing the default-remote
+code paths themselves.
+
 ## Releasing
 
 New releases are made frequently and tagged in git using a [_signed_ tag][].