Custom Claims and List Users Support (#92)

* Implemented ThreadManager API for configuring the thread pools and thread factories used by the SDK

* Giving all threads unique names; Updated documentation; Using daemons in default thread managers to ensure clean JVM exit

* Updated comments and documentation

* Adding tests for options

* Test cases for basic ThreadManager API

* More test cases

* Made the executor service private in FirebaseApp; Refactored the tests for clarity

* Clean separation of long-lived and short-lived tasks of the SDK

* Updated documentation; More tests; Starting token refresher from database.

* Updated documentation and log statements

* Removing test file

* Initializing executor in FirebaseApp constructor. Minor improvements to documentation and tests.

* Fixed token refresher stop() logic

* Updated documentation; Renamed submit() to submitCallable() and other minor changes

* Implemented custom claims support

* More test cases

* Initial list users implementation

* Changed the setCustomClaims() API on UpdateRequest; Deferring the size check until we have to serialize the update parameters

* Cleaned up the listUser() impl

* Further developed the listUsers() API

* Updated tests and documentation

* Updated documentation

* Implementing batch get operation for users

* Further cleaned up the iterator code

* Further cleaned up the iterator code

* Updated list user API

* Implementing listUsers() using the gax Page interface

* Code clean up and tests

* Updated documentation

* Removed renamed test file

* Adding new line at end of file

* Adding some annotations

* Using empty map in UserRecord when no claims are present; Updated documentation and tests

* minor improvements

* Removing RPC call from constructor

Author: hiranya911

src/main/java/com/google/firebase/auth/ExportedUserRecord.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2017 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.firebase.auth;
+
+import com.google.firebase.auth.internal.DownloadAccountResponse.User;
+import com.google.firebase.internal.Nullable;
+
+/**
+ * Contains metadata associated with a Firebase user account, along with password hash and salt.
+ * Instances of this class are immutable and thread-safe.
+ */
+public class ExportedUserRecord extends UserRecord {
+
+  private final String passwordHash;
+  private final String passwordSalt;
+
+  ExportedUserRecord(User response) {
+    super(response);
+    this.passwordHash = response.getPasswordHash();
+    this.passwordSalt = response.getPasswordSalt();
+  }
+
+  /**
+   * Returns the user's password hash as a base64-encoded string.
+   *
+   * <p>If the Firebase Auth hashing algorithm (SCRYPT) was used to create the user account,
+   * returns the base64-encoded password hash of the user. If a different hashing algorithm was
+   * used to create this user, as is typical when migrating from another Auth system, returns
+   * an empty string. Returns null if no password is set.
+   *
+   * @return A base64-encoded password hash, possibly empty or null.
+   */
+  @Nullable
+  public String getPasswordHash() {
+    return passwordHash;
+  }
+
+  /**
+   * Returns the user's password salt as a base64-encoded string.
+   *
+   * <p>If the Firebase Auth hashing algorithm (SCRYPT) was used to create the user account,
+   * returns the base64-encoded password salt of the user. If a different hashing algorithm was
+   * used to create this user, as is typical when migrating from another Auth system, returns
+   * an empty string. Returns null if no password is set.
+   *
+   * @return A base64-encoded password salt, possibly empty or null.
+   */
+  @Nullable
+  public String getPasswordSalt() {
+    return passwordSalt;
+  }
+}

src/main/java/com/google/firebase/auth/FirebaseAuth.java

@@ -30,11 +30,14 @@
 import com.google.common.base.Strings;
 import com.google.firebase.FirebaseApp;
 import com.google.firebase.ImplFirebaseTrampolines;
+import com.google.firebase.auth.ListUsersPage.DefaultUserSource;
+import com.google.firebase.auth.ListUsersPage.PageFactory;
 import com.google.firebase.auth.UserRecord.CreateRequest;
 import com.google.firebase.auth.UserRecord.UpdateRequest;
 import com.google.firebase.auth.internal.FirebaseTokenFactory;
 import com.google.firebase.auth.internal.FirebaseTokenVerifier;
 import com.google.firebase.internal.FirebaseService;
+import com.google.firebase.internal.Nullable;
 import com.google.firebase.internal.TaskToApiFuture;
 import com.google.firebase.tasks.Task;
 
@@ -346,6 +349,46 @@ public ApiFuture<UserRecord> getUserByPhoneNumberAsync(final String phoneNumber)
     return new TaskToApiFuture<>(getUserByPhoneNumber(phoneNumber));
   }
 
+  private Task<ListUsersPage> listUsers(@Nullable String pageToken, int maxResults) {
+    checkNotDestroyed();
+    final PageFactory factory = new PageFactory(
+        new DefaultUserSource(userManager), maxResults, pageToken);
+    return call(new Callable<ListUsersPage>() {
+      @Override
+      public ListUsersPage call() throws Exception {
+        return factory.create();
+      }
+    });
+  }
+
+  /**
+   * Gets a page of users starting from the specified {@code pageToken}. Page size will be
+   * limited to 1000 users.
+   *
+   * @param pageToken A non-empty page token string, or null to retrieve the first page of users.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link ListUsersPage}
+   *     instance. If an error occurs while retrieving user data, the future throws an exception.
+   * @throws IllegalArgumentException If the specified page token is empty.
+   */
+  public ApiFuture<ListUsersPage> listUsersAsync(@Nullable String pageToken) {
+    return listUsersAsync(pageToken, FirebaseUserManager.MAX_LIST_USERS_RESULTS);
+  }
+
+  /**
+   * Gets a page of users starting from the specified {@code pageToken}.
+   *
+   * @param pageToken A non-empty page token string, or null to retrieve the first page of users.
+   * @param maxResults Maximum number of users to include in the returned page. This may not
+   *     exceed 1000.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link ListUsersPage}
+   *     instance. If an error occurs while retrieving user data, the future throws an exception.
+   * @throws IllegalArgumentException If the specified page token is empty, or max results value
+   *     is invalid.
+   */
+  public ApiFuture<ListUsersPage> listUsersAsync(@Nullable String pageToken, int maxResults) {
+    return new TaskToApiFuture<>(listUsers(pageToken, maxResults));
+  }
+
   /**
    * Similar to {@link #createUserAsync(CreateRequest)}, but returns a {@link Task}.
    *
@@ -398,7 +441,7 @@ public Task<UserRecord> updateUser(final UpdateRequest request) {
     return call(new Callable<UserRecord>() {
       @Override
       public UserRecord call() throws Exception {
-        userManager.updateUser(request);
+        userManager.updateUser(request, jsonFactory);
         return userManager.getUserById(request.getUid());
       }
     });
@@ -418,6 +461,35 @@ public ApiFuture<UserRecord> updateUserAsync(final UpdateRequest request) {
     return new TaskToApiFuture<>(updateUser(request));
   }
 
+  private Task<Void> setCustomClaims(String uid, Map<String, Object> claims) {
+    checkNotDestroyed();
+    final UpdateRequest request = new UpdateRequest(uid).setCustomClaims(claims);
+    return call(new Callable<Void>() {
+      @Override
+      public Void call() throws Exception {
+        userManager.updateUser(request, jsonFactory);
+        return null;
+      }
+    });
+  }
+
+  /**
+   * Sets the specified custom claims on an existing user account. A null claims value removes
+   * any claims currently set on the user account. The claims should serialize into a valid JSON
+   * string. The serialized claims must not be larger than 1000 characters.
+   *
+   * @param uid A user ID string.
+   * @param claims A map of custom claims or null.
+   * @return An {@code ApiFuture} which will complete successfully when the user account has been
+   *     updated. If an error occurs while deleting the user account, the future throws a
+   *     {@link FirebaseAuthException}.
+   * @throws IllegalArgumentException If the user ID string is null or empty, or the claims
+   *     payload is invalid or too large.
+   */
+  public ApiFuture<Void> setCustomClaimsAsync(String uid, Map<String, Object> claims) {
+    return new TaskToApiFuture<>(setCustomClaims(uid, claims));
+  }
+
   /**
    * Similar to {@link #deleteUserAsync(String)}, but returns a {@link Task}.
    *
@@ -440,19 +512,6 @@ public Void call() throws Exception {
     });
   }
 
-  private void checkNotDestroyed() {
-    synchronized (lock) {
-      checkState(!destroyed.get(), "FirebaseAuth instance is no longer alive. This happens when "
-          + "the parent FirebaseApp instance has been deleted.");
-    }
-  }
-
-  private void destroy() {
-    synchronized (lock) {
-      destroyed.set(true);
-    }
-  }
-
   /**
    * Deletes the user identified by the specified user ID.
    *
@@ -470,6 +529,19 @@ private <T> Task<T> call(Callable<T> command) {
     return ImplFirebaseTrampolines.submitCallable(firebaseApp, command);
   }
 
+  private void checkNotDestroyed() {
+    synchronized (lock) {
+      checkState(!destroyed.get(), "FirebaseAuth instance is no longer alive. This happens when "
+          + "the parent FirebaseApp instance has been deleted.");
+    }
+  }
+
+  private void destroy() {
+    synchronized (lock) {
+      destroyed.set(true);
+    }
+  }
+
   private static final String SERVICE_ID = FirebaseAuth.class.getName();
 
   private static class FirebaseAuthService extends FirebaseService<FirebaseAuth> {

src/main/java/com/google/firebase/auth/FirebaseUserManager.java

@@ -37,10 +37,12 @@
 import com.google.common.collect.ImmutableMap;
 import com.google.firebase.auth.UserRecord.CreateRequest;
 import com.google.firebase.auth.UserRecord.UpdateRequest;
+import com.google.firebase.auth.internal.DownloadAccountResponse;
 import com.google.firebase.auth.internal.GetAccountInfoResponse;
 
 import com.google.firebase.internal.SdkUtils;
 import java.io.IOException;
+import java.util.List;
 import java.util.Map;
 
 /**
@@ -56,8 +58,15 @@ class FirebaseUserManager {
   static final String USER_CREATE_ERROR = "USER_CREATE_ERROR";
   static final String USER_UPDATE_ERROR = "USER_UPDATE_ERROR";
   static final String USER_DELETE_ERROR = "USER_DELETE_ERROR";
+  static final String LIST_USERS_ERROR = "LIST_USERS_ERROR";
   static final String INTERNAL_ERROR = "INTERNAL_ERROR";
 
+  static final int MAX_LIST_USERS_RESULTS = 1000;
+
+  static final List<String> RESERVED_CLAIMS = ImmutableList.of(
+      "amr", "at_hash", "aud", "auth_time", "azp", "cnf", "c_hash", "exp", "iat",
+      "iss", "jti", "nbf", "nonce", "sub", "firebase");
+
   private static final String ID_TOOLKIT_URL =
       "https://www.googleapis.com/identitytoolkit/v3/relyingparty/";
   private static final String CLIENT_VERSION_HEADER = "X-Client-Version";
@@ -157,10 +166,10 @@ String createUser(CreateRequest request) throws FirebaseAuthException {
     throw new FirebaseAuthException(USER_CREATE_ERROR, "Failed to create new user");
   }
 
-  void updateUser(UpdateRequest request) throws FirebaseAuthException {
+  void updateUser(UpdateRequest request, JsonFactory jsonFactory) throws FirebaseAuthException {
     GenericJson response;
     try {
-      response = post("setAccountInfo", request.getProperties(), GenericJson.class);
+      response = post("setAccountInfo", request.getProperties(jsonFactory), GenericJson.class);
     } catch (IOException e) {
       throw new FirebaseAuthException(USER_UPDATE_ERROR,
           "IO error while updating user: " + request.getUid(), e);
@@ -187,6 +196,28 @@ void deleteUser(String uid) throws FirebaseAuthException {
     }
   }
 
+  DownloadAccountResponse listUsers(int maxResults, String pageToken) throws FirebaseAuthException {
+    ImmutableMap.Builder<String, Object> builder = ImmutableMap.<String, Object>builder()
+        .put("maxResults", maxResults);
+    if (pageToken != null) {
+      checkArgument(!pageToken.equals(ListUsersPage.END_OF_LIST), "invalid end of list page token");
+      builder.put("nextPageToken", pageToken);
+    }
+
+    DownloadAccountResponse response;
+    try {
+      response = post("downloadAccount", builder.build(), DownloadAccountResponse.class);
+      if (response == null) {
+        throw new FirebaseAuthException(LIST_USERS_ERROR,
+            "Unexpected response from download user account API.");
+      }
+      return response;
+    } catch (IOException e) {
+      throw new FirebaseAuthException(LIST_USERS_ERROR,
+          "IO error while downloading user accounts.", e);
+    }
+  }
+
   private <T> T post(String path, Object content, Class<T> clazz) throws IOException {
     checkArgument(!Strings.isNullOrEmpty(path), "path must not be null or empty");
     checkNotNull(content, "content must not be null");