Update release notes and readme re user search updates

README.md

@@ -1,14 +1,12 @@
-KBase authentication server
-===========================
+# KBase authentication server
 
 This repo contains the second iteration of the KBase authentication server.
 
 Build status (master):
 [![Build Status](https://travis-ci.org/kbase/auth2.svg?branch=master)](https://travis-ci.org/kbase/auth2) [![codecov](https://codecov.io/gh/kbase/auth2/branch/master/graph/badge.svg)](https://codecov.io/gh/kbase/auth2)
 
 
-Current endpoints
------------------
+## Current endpoints
 
 ### UI
 
@@ -190,8 +188,8 @@ the user.
 DELETE /testmode/api/V2/testmodeonly/clear  
 Removes all test mode data from the system.
 
-Admin notes
------------
+## Admin 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
   allow cookies to be set over insecure connections.
@@ -211,9 +209,16 @@ Admin notes
 * 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.
+* 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. This can
+    be run while the server is live **after** updating to version 0.6.0.
+  * Once the names have been recanonicalized, the `--remove-recanonicalization-flag` can be
+    used to remove flags set on database objects to avoid reprocessing if the recanonicalize
+    process does not complete.
+
+## Requirements
 
-Requirements
-------------
 Java 8 (OpenJDK OK)  
 Apache Ant (http://ant.apache.org/)  
 MongoDB 2.6+ (https://www.mongodb.com/)  
@@ -223,8 +228,8 @@ This repo (git clone https://github.com/kbase/auth2)
 The jars repo (git clone https://github.com/kbase/jars)  
 The two repos above need to be in the same parent folder.
 
-To start server
----------------
+## To start server
+
 start mongodb  
 if using mongo auth, create a mongo user  
 cd into the auth2 repo  
@@ -234,8 +239,8 @@ copy `deploy.cfg.example` to `deploy.cfg` and fill in appropriately
 `cd jettybase`  
 `./jettybase$ java -jar -Djetty.port=<port> <path to jetty install>/start.jar`  
 
-Administer the server
----------------------
+## Administer the server
+
 Set a root password:  
 `./manage_auth -d <path to deploy.cfg> -r`  
 
@@ -244,15 +249,14 @@ 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.
 
-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`  
 
 Omit the stop key to have jetty generate one for you.
 
-Developer notes
----------------
+## Developer notes
 
 ### Adding and releasing code
 
@@ -306,7 +310,6 @@ In `us.kbase.auth2.lib.exceptions`:
 
 Anything else is mapped to 500.
 
-Ancient history
----------------
+## Ancient history
 
 https://github.com/kbaseIncubator/auth2proto

RELEASE_NOTES.md

@@ -1,8 +1,13 @@
-Authentication Service MKII release notes
-=========================================
+# Authentication Service MKII release notes
 
-0.5.0
------
+## 0.6.0
+
+* ADMIN ACTION REQUIRED - after the server is upgraded, use the `manage_auth` script to
+  recanonicalize the user display names. See the [README.md](./README.md#admin-notes) file.
+* The user search API endpoint has been improved to allow for multiple tokens (e.g. "Dave Smith")
+  in the search prefix. The prefix will be tokenized prior to search.
+
+## 0.5.0
 
 * BACKWARDS INCOMPATIBILITY - any in flight login or link flows will fail after the server is
   upgraded to 0.5.0.
@@ -13,28 +18,25 @@ Authentication Service MKII release notes
   * OrcID currently does not support PKCE, see https://github.com/ORCID/ORCID-Source/issues/5977
 * The OAuth2 state value is now stored in the database rather than in a cookie.
 
-0.4.3
------
+## 0.4.3
 
 * Added the ability for the test auth controller to authenticate to MongoDB.
 
-0.4.2
------
+## 0.4.2
 
 * Fixed a bug decoding Google JWT tokens, which could very rarely prevent users from
   logging in.
 
-0.4.1
------
+## 0.4.1
 
 * Added a `/testmode` endpoint that mimics the standard root endpoint.
 * The service is now tested against OpenJDK 8 and 11.
   * Note that the compiler compliance level must still be set at 1.8. The server fails to
     start if the compliance level is 11, likely due to out of date jars, including, possibly,
     jersey repackaged asm jars.
 
-0.4.0
------
+## 0.4.0
+
 * CONFIGURATION CHANGE - the `identity-provider-Google-custom-people-api-host`
   configuration key has been removed. (see below).
 * The Google People API does not return the email address for a small subset of users for,
@@ -43,8 +45,8 @@ Authentication Service MKII release notes
   user name) from the JWT provided at the end of the OAuth2 login flow rather than using the
   People API.
 
-0.3.0
------
+## 0.3.0
+
 * CONFIGURATION CHANGE - the `identity-provider-Google-custom-people-api-host`
   configuration key is now required for the Google identity provider (see below).
 * The Google identity provider has been updated to no longer use the soon to be removed
@@ -53,16 +55,16 @@ Authentication Service MKII release notes
   `deploy.cfg.example` file has an example setting. 2) The People API must be enabled
   for the project corresponding to the Google client ID and client secret.
 
-0.2.8
------
+## 0.2.8
+
 * Added a customizable config block to the deployment template.
 
-0.2.7
------
+## 0.2.7
+
 * Update the MongoDB client to 3.8.2 to fix https://jira.mongodb.org/browse/JAVA-2383.
 
-0.2.6
------
+## 0.2.6
+
 * CONFIGURATION CHANGE - there is a new required `deploy.cfg` parameter, `environment-header`
   (see below).
 * The service can now support multiple alternate environments with different redirect urls
@@ -75,37 +77,35 @@ Authentication Service MKII release notes
   environment. Additionally, in the `/admin/config/` configuration endpoint, optional redirect
   URLs equivalent to the default environment redirect urls can be configured.
 
-0.2.5
------
+## 0.2.5
+
 * OrcID is now supported as an identity provider. See `deploy.cfg.example` for a
   configuration example.
 
-0.2.4
------
+## 0.2.4
+
 * CONFIGURATION CHANGE - the templates directory is now configurable. Add
   `template-dir = templates` to any existing configuration files to preserve current
   behavior. The purpose of this change is primarily to allow other applications to
   test the server with the templates in a non-standard location.
 
-0.2.3
------
+## 0.2.3
+
 * Add an endpoint for getting user display names in test mode.
 
-0.2.2
------
+## 0.2.2
+
 * Add helpers for running the auth service in a separate java process during tests.
 
-0.2.1
------
+## 0.2.1
 
 * As the Globus Nexus endpoint has been retired, the Globus user import functionality no longer
   works and has been removed.
 * Added dockerfile that is compatible with automated docker build practices. A successful
   TravisCI build pushes the docker image to dockerhub.
 * Added test mode (see documentation).
 
-0.2.0
------
+## 0.2.0
 
 * BACKWARDS INCOMPATIBILITY: after upgrading to 0.2.0, all login and link in process tokens will
   be invalid. Users will need to restart the login or linking processes.
@@ -122,13 +122,11 @@ Authentication Service MKII release notes
   cookies are removed. If JSON is requested, the login cookie is not removed, unlike with an
   HTML response.
 
-0.1.1
------
+## 0.1.1
 
 * the `/link/choice` endpoint now returns the linked identities and the account to which they are
   linked. If all identities are linked an error is not thrown.
 
-0.1.0
------
+## 0.1.0
 
 * Initial release