Add documentation re setting up environments

Also delete the extremely crufty jetty-config.md and some build.gradle
cruft

README.md

@@ -203,7 +203,9 @@ the user.
 `DELETE /testmode/api/V2/testmodeonly/clear`  
 Removes all test mode data from the system.
 
-## Admin notes
+## Administration
+
+### Notes
 
 * It is expected that this server always runs behind a reverse proxy (such as
   nginx) that enforces https / TLS and as such the auth server is configured to
@@ -224,6 +226,11 @@ Removes all test mode data from the system.
 * Get Google OAuth2 creds [here](https://console.developers.google.com/apis)
 * Get OrcID creds [here](https://orcid.org/content/register-client-application-0)
   * Note that only the public API has been tested with the auth server.
+
+#### Migration notes
+
+##### 0.6.0
+
 * In version 0.6.0, the canonicalization algorithm for user display names changed and the
   database needs to be updated.
   * See the `--recanonicalize-display-names` option for the `manage_auth` script
@@ -233,39 +240,46 @@ Removes all test mode data from the system.
     used to remove flags set on database objects to avoid reprocessing if the recanonicalize
     process does not complete.
 
-## Requirements
+### Requirements
 
-Java 8 (OpenJDK OK)  
-MongoDB 2.6+ (https://www.mongodb.com/)  
-Jetty 9.3+ (http://www.eclipse.org/jetty/download.html)
-    (see jetty-config.md for version used for testing)  
-This repo (git clone https://github.com/kbase/auth2)  
+* Java 8 (OpenJDK OK)
+* MongoDB 2.6+ (https://www.mongodb.com/)
+* Jetty 9.3+ (http://www.eclipse.org/jetty/download.html)
+* This repo (git clone https://github.com/kbase/auth2)  
 
-## To start server
+### Starting the server
 
-Either use `docker-compose --build -d`, which is easier and starts the server in test mode
-(which can be configured in the docker-compose file), or:
+#### Docker
 
-start mongodb  
-if using mongo auth, create a mongo user  
-cd into the auth2 repo
+The provided `Dockerfile` can be used to build and run an image. See the deployment template
+in `deployment/conf/.templates` for the environment variables available to configure the
+service - the `deploy.cfg.example` file provides documentation for these variables.
 
-```
+`docker-compose --build -d` can be used to start a MongoDB instance and the auth server in
+test mode (which can be configured via environment variables in the compose file).
+
+#### Manually
+
+* Start mongodb
+* If using mongo auth, create a mongo user
+* `cd` into the auth2 repo
+
+```shell
 ./gradlew war
 mkdir -p jettybase/webapps
 cp build/libs/auth2.war jettybase/webapps/ROOT.war
 cp templates jettybase/templates
 ```
 
-copy `deploy.cfg.example` to `deploy.cfg` and fill in appropriately
+* copy `deploy.cfg.example` to `deploy.cfg` and fill in appropriately
 
-```
+```shell
 export KB_DEPLOYMENT_CONFIG=<path to deploy.cfg>
 cd jettybase
 ./jettybase$ java -jar -Djetty.port=<port> <path to jetty install>/start.jar
 ```
 
-## Administer the server
+### Perform initial setup
 
 Create the administration script:
 
@@ -274,11 +288,16 @@ Create the administration script:
 Set a root password:  
 `build/manage_auth -d <path to deploy.cfg> -r`  
 
+* Note that the `deploy.cfg` file only needs accurate MongoDB connection information for use
+  with the auth CLI.
+
 Login to a local account as `***ROOT***` with the password you set. Create a
 local account and assign it the create administrator role. That account can
 then be used to create further administrators (including itself) without
 needing to login as root. The root account can then be disabled.
 
+To set up alternate login / link environments, see [Environments](documentation/Environments.md).
+
 ### Revoking tokens in an emergency
 
 The simple HTML only test UI included with the server supports most administration functions,
@@ -300,7 +319,7 @@ curl -X POST --cookie "kbase_session=<admin token>" http://<host>/admin/revokeal
 If the `token-cookie-name` deployment configuration value is not `kbase_session` change
 the request to match.
 
-## Start & stop server w/o a pid
+### Start & stop server w/o a pid
 
 `./jettybase$ java -DSTOP.PORT=8079 -DSTOP.KEY=foo -jar ~/jetty/jetty-distribution-9.3.11.v20160721/start.jar`  
 `./jettybase$ java -DSTOP.PORT=8079 -DSTOP.KEY=foo -jar ~/jetty/jetty-distribution-9.3.11.v20160721/start.jar --stop`  

build.gradle

@@ -1,9 +1,5 @@
 /*
  * This file was generated by the Gradle 'init' task.
- *
- * This generated file contains a sample Java application project to get you started.
- * For more details take a look at the 'Building Java & JVM projects' chapter in the Gradle
- * User Manual available at https://docs.gradle.org/7.4.2/userguide/building_java_projects.html
  */
 
 plugins {

documentation/Environments.md

@@ -0,0 +1,63 @@
+# Authentication service environments
+
+The auth service can support multiple environments, allowing it to service multiple hosts.
+Alternate environments only affect account login and linking - all the environments share
+tokens and are invisible from the perspective of a service contacting the auth server to look up
+users or validate tokens.
+
+## Setup
+
+There are several steps to setting up an environment. The following steps assume the the default
+or standard environment is `host1.org` and is properly configured in the auth service and
+3rd party identity providers (IDPs). The new environment is assumed to be served at `host2.org`.
+The environment names, respectively, will be `host1` and `host2`.
+
+* The login and link redirect URLs for `host2` must be registered with each IDP.
+  * They are usually going to be the same as the redirect URLs for `host1` with the replacement
+    of `host1.org` with `host2.org`. However, if URLs are rewritten by the remote proxy in
+    a different manner between `host1` and `host2` that must be taken into account.
+* The login and link redirect URLs must be added to the `deploy.cfg` file as described in
+  `deploy.cfg.example`. If using the Docker image, they need to be added to the environment
+  in the `env1` and `auth_base_url_env1` keys or the `additional_config` key.
+  * For example:
+
+```
+identity-provider-Google-env-host2-login-redirect-url=https://host2.org/auth/login/complete/google
+identity-provider-Google-env-host2-link-redirect-url=https://host2.org/auth/link/complete/google
+```
+
+* The new environment must be activated in the `deploy.cfg` file, either directly or via
+  environment variable if using Docker:
+
+```
+identity-provider-envs=<existing environments>, host2
+```
+
+* On login or linking requests, the auth server must know which environment to use. There are two
+  options for providing this information:
+  * Send a header to the auth server defining the environment. The name of the header is
+    defined in the `deploy.cfg` `environment-header` key. For example, if the environment
+    header was set to `X-AUTH-ENV` the auth service would receive requests with the header
+    `X-AUTH-ENV: host2` in order to set the environment to `host2`. This is the simplest
+    and preferred approach, as it generally only needs a one line addition to the reverse
+    proxy configuration for the host, at which point all requests to the auth service get the
+    environment header.
+  * The UI code can specify the environment when contacting the auth2 service to start a login or
+    link flow via the `environment` form parameter. This requires the UI code to be
+    environment aware which is generally held to be undesired.
+* Once the previous steps have been completed the service can be restarted with the updated
+  configuration.
+* The final step requires an admin to go to the `/admin/config` endpoint of the auth server.
+  The new environment should now be visible in the configuration. While the IDP relevant
+  configuration is all specified in the `deploy.cfg` file to avoid passing secrets over the API
+  and to locate cohesive configuration elements together, the host side configuration is
+  updateable on the fly via the API. The redirect URLs for login and linking must be updated
+  appropriately for the host. In many cases, this will be simply replacing `host1.org` with
+  `host2.org` but see the previously mentioned caveats regarding updating the URLs.
+
+## Notes
+
+* When using multiple environments, it may be wise to clear the default environment and use
+  alternate environments for all the environments. This makes it less likely that a
+  misconfiguration could cause an alternate environment to use settings from the default
+  environment mistakenly.

documentation/recovering_lost_account_due_to_email_provider_change.md

@@ -101,7 +101,7 @@ should be impossible.
 
 1. Add an option to the Auth command line tool to add identities to users to avoid incorrect DB
    updates. The CLI could, when possible, query the identity provider to ensure the information
-   provided command line is correct or pull additional information from the provider.
+   provided on the command line is correct or pull additional information from the provider.
 2. Develop procedures for verifying a user's possession of an account and transferring
    trusted information needed to restore access to an account.
 3. Develop and deploy user documentation recommending that users always have at least one