Add docs & release notes for anonymous ID changes.

README.md

@@ -18,53 +18,53 @@ testing. In many cases a manual refresh of the page will be required to see
 changes. Further, once a checkbox is manually checked or unchecked that state
 will not change, even with a refresh - to see changes reset the form.
 
-/  
+`/`  
 General server information including git commit, version, and server time.
 
-/admin  
+`/admin`  
 Global admin tasks - force reset all passwords, revoke all tokens, view a token, search for users.
 
-/admin/customroles  
+`/admin/customroles`  
 View, add, and delete custom roles.
 
-/admin/config  
+`/admin/config`  
 View and edit the server configuration.
 
-/admin/localaccount  
+`/admin/localaccount`  
 Create a local account.
 
-/admin/user/<user name>  
+`/admin/user/<user name>`  
 View user, disable user, reset password, force password reset, and modify user roles.
 
-/admin/user/&lt;user name&gt;/tokens  
+`/admin/user/<user name>/tokens`  
 View and revoke tokens for a specific user.
 
-/customroles  
+`/customroles`  
 View custom roles. This page is publicly viewable to any user with a valid token.
 
-/link  
+`/link`  
 Link accounts.
 
-/login  
+`/login`  
 Login to a provider based account. Stores a cookie with a token.
 
-/localaccount/login  
+`/localaccount/login`  
 Login to a local account. Stores a cookie with a token.
 
-/localaccount/reset  
+`/localaccount/reset`  
 Reset the password for a local account.
 
-/logout  
+`/logout`  
 Logs the user out.  
 Removes the user's token from the database as well as any temporary link tokens associated with
 the user. Removes the login, temporary login, and temporary link cookies except if JSON output
 is requested, in which case it is expected that the UI manages the login token
 (but not the temporary tokens).
 
-/me  
+`/me`  
 User page. Update name and email address, remove roles.
 
-/tokens  
+`/tokens`  
 List, create, and revoke tokens.
 
 ### API
@@ -79,41 +79,56 @@ noted.
 Tokens are opaque strings - no particular structure should be assumed, and token string contents
 may change without notice.
 
-GET /api/V2/me  
+`GET /api/V2/me`  
 See the current user's profile.
 
-PUT /api/V2/me  
+`PUT /api/V2/me`  
 Update the current user's email address and display name. Takes JSON encoded data with the
 keys `display` and `email`.
 
-GET /api/V2/users/?list=&lt;comma separated user names&gt;  
+`GET /api/V2/users/?list=<comma separated user names>`  
 Validate a set of user names and get the users' display names. Returns a map of username ->
 display name. Any usernames that do not correspond to accounts will not be included in the map.
 
-GET /api/V2/users/search/&lt;prefix&gt;/?fields=&lt;comma separated fields&gt;  
+`GET /api/V2/users/search/<prefix>/?fields=<comma separated fields>`  
 Find users based on a prefix of the username or any parts of the display name, where parts are
 delimited by whitespace. By default the search occurs on all fields; setting the fields query
 parameter can restrict the search fields and thus possibly speed up the search. Current field names
 are `username` and `displayname`; any other field names are ignored. Returns a map of
 username -> display name. At most 10,000 names are returned.
 
-GET /api/V2/token  
+`GET /api/V2/token`  
 Introspect a token.
 
-POST /api/V2/token  
+`POST /api/V2/token`  
 Create an agent token. Takes JSON encoded data with the keys `name` for a required token name
 string and `customcontext` for an optional map of user-supplied creation context to be saved
 with the token, and returned when the token is queried.
 
+`GET /api/v2/admin/anonids?list=<comma separated anonymous user IDs>`  
+Translate anonymous user IDs to user names. `Admin` (and exactly `Admin`) permission
+is required. At most 10000 IDs are allowed, but the URL size limit effectively limits the count
+to less than that. Disabled users are not returned; IDs not found in the database are omitted from
+the map.
+
+RETURNS:
+```
+{
+  <anonymous ID 1>: <user name 1>,
+  ...
+  <anonymous ID N>: <user name N>
+}
+```
+
 #### Legacy
 
 Endpoints (mostly) identical to the original Globus and KBase auth endpoints are provided for
 backwards compatibility.
 
-POST /api/legacy/KBase/Sessions/Login  
+`POST /api/legacy/KBase/Sessions/Login`  
 The legacy KBase API.
 
-GET /api/legacy/globus  
+`GET /api/legacy/globus`  
 The legacy globus API. Endpoints are /goauth/token and /users.
 
 ### Test Mode
@@ -141,51 +156,51 @@ Test mode data is only accessible via endpoints under the `/testmode` root endpo
 These endpoints mimic the behavior of the standard API endpoints above, but only interact with
 test mode data.
 
-GET /testmode  
+`GET /testmode`  
 
-GET /testmode/api/V2/me  
+`GET /testmode/api/V2/me`  
 
-GET /testmode/api/V2/token  
+`GET /testmode/api/V2/token`  
 
-GET /testmode/api/V2/users  
+`GET /testmode/api/V2/users`  
 
-POST /testmode/api/legacy/KBase/Sessions/Login  
+`POST /testmode/api/legacy/KBase/Sessions/Login`  
 
-GET /testmode/api/legacy/globus  
+`GET /testmode/api/legacy/globus`  
 
 #### Data manipulation endpoints
 
 These endpoints allow a test harness to create and modify test mode users, tokens, and roles.
 No authentication is required.
 
-POST /testmode/api/V2/testmodeonly/user  
+`POST /testmode/api/V2/testmodeonly/user`  
 Create a user. Takes JSON encoded data with the keys `user` for the user name and `display` for
 the user's display name.
 
-GET /testmode/api/V2/testmodeonly/user/&lt;username&gt;  
+`GET /testmode/api/V2/testmodeonly/user/<username>`  
 Get a user's data.
 
-POST /testmode/api/V2/testmodeonly/token  
+`POST /testmode/api/V2/testmodeonly/token`  
 Create a token. The user to which the token is assigned must exist. Takes JSON encoded data with
 the keys `user` for the user name, `name` for an optional token name, and `type` for the token
 type. `type` is one of `Login`, `Agent`, `Dev`, or `Serv`.
 
-POST /testmode/api/V2/testmodeonly/customroles  
+`POST /testmode/api/V2/testmodeonly/customroles`  
 Create a custom role. Takes JSON encoded data with the keys `id` for the role id and `desc` for
 the role description. Posting a role with an existing ID overwrites the description of the role.
 
-GET /testmode/api/V2/testmodeonly/customroles  
+`GET /testmode/api/V2/testmodeonly/customroles`  
 Get the list of extant custom roles.
 
-PUT /testmode/api/V2/testmodeonly/userroles  
+`PUT /testmode/api/V2/testmodeonly/userroles`  
 Set a user's roles, overwriting any current roles. Takes JSON encoded data with the keys `user`
 for the user name of the user to modify, `roles` for a list of built-in roles to grant to the
 user, and `customroles` for a list of custom role ids to grant to the user. Allowed `roles` are
 `DevToken`, `ServToken`, `Admin`, and `CreateAdmin`. Note that these roles don't grant
 any actual privileges in test mode. Omitting `roles` and `customroles` removes all roles from
 the user.
 
-DELETE /testmode/api/V2/testmodeonly/clear  
+`DELETE /testmode/api/V2/testmodeonly/clear`  
 Removes all test mode data from the system.
 
 ## Admin notes

RELEASE_NOTES.md

@@ -4,6 +4,14 @@
 
 * 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.
+* ADMIN OPTIONAL ACTION - on first startup, the service will build a sparse index on the `anonid`
+  field in the `users` collection. If there are many users this could take some time. The
+  index could be built in the background while the server is running to reduce or avoid
+  downtime by starting the new version of the service pointed at the same database or manually
+  creating the index in the MongoDB shell.
+* User anonymous IDs have been added and are visible in the various endpoints that return
+  user information.
+* The `/api/V2/admin/anonids` endpoint has been added to translate anonymous IDs to user names.
 * 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.
 

src/us/kbase/auth2/lib/user/AuthUser.java

@@ -37,7 +37,6 @@ public class AuthUser {
 	private final DisplayName displayName;
 	private final EmailAddress email;
 	private final UserName userName;
-	// TODO ANONID docs and release notes
 	private final UUID anonymousID;
 	private final Set<Role> roles;
 	private final Set<Role> canGrantRoles;

src/us/kbase/test/auth2/lib/AuthenticationAnonymousIDsTest.java

@@ -180,10 +180,10 @@ public void getUserNameFromAnonymousIDsFailTooManyInputs() throws Exception {
 	private void getUserNamesFromAnonymousIDsFail(
 			final Authentication auth,
 			final IncomingToken token,
-			final Set<UUID> anonymoutIDs,
+			final Set<UUID> anonymousIDs,
 			final Exception expected) {
 		try {
-			auth.getUserNamesFromAnonymousIDs(token, anonymoutIDs);
+			auth.getUserNamesFromAnonymousIDs(token, anonymousIDs);
 			fail("expected exception");
 		} catch (Exception got) {
 			TestCommon.assertExceptionCorrect(got, expected);