feat(auth): Add bulk get/delete methods (#151)

This PR allows callers to retrieve a list of users by unique identifier (uid, email, phone, federated provider uid) as well as to delete a list of users.

RELEASE NOTE: Added GetUsersAsync() and DeleteUsersAsync() APIs for retrieving and deleting user accounts in bulk.

Author: rsgowman

FirebaseAdmin/FirebaseAdmin.IntegrationTests/FirebaseAuthTest.cs

@@ -17,6 +17,7 @@
 using System.Linq;
 using System.Net.Http;
 using System.Text;
+using System.Threading;
 using System.Threading.Tasks;
 using System.Web;
 using FirebaseAdmin.Auth;
@@ -37,6 +38,9 @@ public class FirebaseAuthTest
         private const string VerifyCustomTokenUrl =
             "https://www.googleapis.com/identitytoolkit/v3/relyingparty/verifyCustomToken";
 
+        private const string VerifyPasswordUrl =
+            "https://www.googleapis.com/identitytoolkit/v3/relyingparty/verifyPassword";
+
         private const string ContinueUrl = "http://localhost/?a=1&b=2#c=3";
 
         private static readonly ActionCodeSettings EmailLinkSettings = new ActionCodeSettings()
@@ -336,6 +340,37 @@ public async Task GetUserNonExistingEmail()
             Assert.Equal(AuthErrorCode.UserNotFound, exception.AuthErrorCode);
         }
 
+        [Fact]
+        public async Task LastRefreshTime()
+        {
+            var newUserRecord = await NewUserWithParamsAsync();
+            try
+            {
+                // New users should not have a LastRefreshTimestamp set.
+                Assert.Null(newUserRecord.UserMetaData.LastRefreshTimestamp);
+
+                // Login to cause the LastRefreshTimestamp to be set.
+                await SignInWithPasswordAsync(newUserRecord.Email, "password");
+
+                var userRecord = await FirebaseAuth.DefaultInstance.GetUserAsync(newUserRecord.Uid);
+
+                // Ensure the LastRefreshTimstamp is approximately "now" (with a tollerance of 10 minutes).
+                var now = DateTime.UtcNow;
+                int tolleranceMinutes = 10;
+                var minTime = now.AddMinutes(-tolleranceMinutes);
+                var maxTime = now.AddMinutes(tolleranceMinutes);
+                Assert.NotNull(userRecord.UserMetaData.LastRefreshTimestamp);
+                Assert.InRange(
+                        userRecord.UserMetaData.LastRefreshTimestamp.Value,
+                        minTime,
+                        maxTime);
+            }
+            finally
+            {
+                await FirebaseAuth.DefaultInstance.DeleteUserAsync(newUserRecord.Uid);
+            }
+        }
+
         [Fact]
         public async Task UpdateUserNonExistingUid()
         {
@@ -359,6 +394,76 @@ public async Task DeleteUserNonExistingUid()
             Assert.Equal(AuthErrorCode.UserNotFound, exception.AuthErrorCode);
         }
 
+        [Fact]
+        public async Task DeleteUsers()
+        {
+            UserRecord user1 = await NewUserWithParamsAsync();
+            UserRecord user2 = await NewUserWithParamsAsync();
+            UserRecord user3 = await NewUserWithParamsAsync();
+
+            DeleteUsersResult deleteUsersResult = await this.SlowDeleteUsersAsync(
+                new List<string> { user1.Uid, user2.Uid, user3.Uid });
+
+            Assert.Equal(3, deleteUsersResult.SuccessCount);
+            Assert.Equal(0, deleteUsersResult.FailureCount);
+            Assert.Empty(deleteUsersResult.Errors);
+
+            GetUsersResult getUsersResult = await FirebaseAuth.DefaultInstance.GetUsersAsync(
+                new List<UserIdentifier>
+                {
+                    new UidIdentifier(user1.Uid),
+                    new UidIdentifier(user2.Uid),
+                    new UidIdentifier(user3.Uid),
+                });
+
+            Assert.Empty(getUsersResult.Users);
+            Assert.Equal(3, getUsersResult.NotFound.Count());
+        }
+
+        [Fact]
+        public async Task DeleteExistingAndNonExistingUsers()
+        {
+            UserRecord user1 = await NewUserWithParamsAsync();
+
+            DeleteUsersResult deleteUsersResult = await this.SlowDeleteUsersAsync(
+                new List<string> { user1.Uid, "uid-that-doesnt-exist" });
+
+            Assert.Equal(2, deleteUsersResult.SuccessCount);
+            Assert.Equal(0, deleteUsersResult.FailureCount);
+            Assert.Empty(deleteUsersResult.Errors);
+
+            GetUsersResult getUsersResult = await FirebaseAuth.DefaultInstance.GetUsersAsync(
+                new List<UserIdentifier>
+                {
+                    new UidIdentifier(user1.Uid),
+                    new UidIdentifier("uid-that-doesnt-exist"),
+                });
+
+            Assert.Empty(getUsersResult.Users);
+            Assert.Equal(2, getUsersResult.NotFound.Count());
+        }
+
+        [Fact]
+        public async Task DeleteUsersIsIdempotent()
+        {
+            UserRecord user1 = await NewUserWithParamsAsync();
+
+            DeleteUsersResult result = await this.SlowDeleteUsersAsync(
+                new List<string> { user1.Uid });
+
+            Assert.Equal(1, result.SuccessCount);
+            Assert.Equal(0, result.FailureCount);
+            Assert.Empty(result.Errors);
+
+            // Delete the user again, ensuring that everything still counts as a success.
+            result = await this.SlowDeleteUsersAsync(
+                new List<string> { user1.Uid });
+
+            Assert.Equal(1, result.SuccessCount);
+            Assert.Equal(0, result.FailureCount);
+            Assert.Empty(result.Errors);
+        }
+
         [Fact]
         public async Task ListUsers()
         {
@@ -520,6 +625,24 @@ public async Task SessionCookie()
             Assert.Equal("testuser", decoded.Uid);
         }
 
+        private static async Task<UserRecord> NewUserWithParamsAsync()
+        {
+            // TODO(rsgowman): This function could be used throughout this file
+            // (similar to the other ports).
+            RandomUser randomUser = RandomUser.Create();
+            var args = new UserRecordArgs()
+            {
+                Uid = randomUser.Uid,
+                Email = randomUser.Email,
+                PhoneNumber = randomUser.PhoneNumber,
+                DisplayName = "Random User",
+                PhotoUrl = "https://example.com/photo.png",
+                Password = "password",
+            };
+
+            return await FirebaseAuth.DefaultInstance.CreateUserAsync(args);
+        }
+
         private static async Task<UserRecord> CreateUserForActionLinksAsync()
         {
             var randomUser = RandomUser.Create();
@@ -558,6 +681,33 @@ private static async Task<string> SignInWithCustomTokenAsync(string customToken)
             }
         }
 
+        private static async Task<string> SignInWithPasswordAsync(string email, string password)
+        {
+            var rb = new Google.Apis.Requests.RequestBuilder()
+            {
+                Method = Google.Apis.Http.HttpConsts.Post,
+                BaseUri = new Uri(VerifyPasswordUrl),
+            };
+            rb.AddParameter(RequestParameterType.Query, "key", IntegrationTestUtils.GetApiKey());
+            var request = rb.CreateRequest();
+            var jsonSerializer = Google.Apis.Json.NewtonsoftJsonSerializer.Instance;
+            var payload = jsonSerializer.Serialize(new VerifyPasswordRequest
+            {
+                Email = email,
+                Password = password,
+                ReturnSecureToken = true,
+            });
+            request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
+            using (var client = new HttpClient())
+            {
+                var response = await client.SendAsync(request);
+                response.EnsureSuccessStatusCode();
+                var json = await response.Content.ReadAsStringAsync();
+                var parsed = jsonSerializer.Deserialize<VerifyPasswordResponse>(json);
+                return parsed.IdToken;
+            }
+        }
+
         private static async Task<string> SignInWithEmailLinkAsync(string email, string oobCode)
         {
             var rb = new Google.Apis.Requests.RequestBuilder()
@@ -610,6 +760,132 @@ private static async Task<string> ResetPasswordAsync(ResetPasswordRequest data)
                 return (string)parsed["email"];
             }
         }
+
+        /**
+         * The {@code batchDelete} endpoint is currently rate limited to 1qps. Use this test helper
+         * to ensure you don't run into quota exceeded errors.
+         */
+        // TODO(rsgowman): When/if the rate limit is relaxed, eliminate this helper.
+        private async Task<DeleteUsersResult> SlowDeleteUsersAsync(IReadOnlyList<string> uids)
+        {
+            await Task.Delay(millisecondsDelay: 1000);
+            return await FirebaseAuth.DefaultInstance.DeleteUsersAsync(uids);
+        }
+
+        public class GetUsersFixture : IDisposable
+        {
+            public GetUsersFixture()
+            {
+                IntegrationTestUtils.EnsureDefaultApp();
+
+                this.TestUser1 = NewUserWithParamsAsync().Result;
+                this.TestUser2 = NewUserWithParamsAsync().Result;
+                this.TestUser3 = NewUserWithParamsAsync().Result;
+
+                // The C# port doesn't support importing users, so unlike the other ports, there's
+                // no way to create a user with a linked federated provider.
+                // TODO(rsgowman): Once either FirebaseAuth.ImportUser() exists (or the UpdateUser()
+                // method supports ProviderToLink (#143)), then use it here and
+                // adjust the VariousIdentifiers() test below.
+            }
+
+            public UserRecord TestUser1 { get; }
+
+            public UserRecord TestUser2 { get; }
+
+            public UserRecord TestUser3 { get; }
+
+            public void Dispose()
+            {
+                // TODO(rsgowman): deleteUsers (plural) would make more sense here, but it's
+                // currently rate limited to 1qps. When/if that's relaxed, change this to just
+                // delete them all at once.
+                var auth = FirebaseAuth.DefaultInstance;
+                auth.DeleteUserAsync(this.TestUser1.Uid).Wait();
+                auth.DeleteUserAsync(this.TestUser2.Uid).Wait();
+                auth.DeleteUserAsync(this.TestUser3.Uid).Wait();
+            }
+        }
+
+        public class GetUsers : IClassFixture<GetUsersFixture>
+        {
+            private FirebaseAuth auth;
+            private UserRecord testUser1;
+            private UserRecord testUser2;
+            private UserRecord testUser3;
+
+            public GetUsers(GetUsersFixture fixture)
+            {
+                this.auth = FirebaseAuth.DefaultInstance;
+                this.testUser1 = fixture.TestUser1;
+                this.testUser2 = fixture.TestUser2;
+                this.testUser3 = fixture.TestUser3;
+            }
+
+            [Fact]
+            public async void VariousIdentifiers()
+            {
+                var getUsersResult = await this.auth.GetUsersAsync(new List<UserIdentifier>()
+                {
+                    new UidIdentifier(this.testUser1.Uid),
+                    new EmailIdentifier(this.testUser2.Email),
+                    new PhoneIdentifier(this.testUser3.PhoneNumber),
+                    // TODO(rsgowman): Once we're able to create a user with a
+                    // provider, do so above and fetch the user like this:
+                    // new ProviderIdentifier("google.com", "google_" + importUserUid),
+                });
+
+                var uids = getUsersResult.Users.Select(userRecord => userRecord.Uid);
+                var expectedUids = new List<string>() { this.testUser1.Uid, this.testUser2.Uid, this.testUser3.Uid };
+                Assert.True(expectedUids.All(expectedUid => uids.Contains(expectedUid)));
+                Assert.Empty(getUsersResult.NotFound);
+            }
+
+            [Fact]
+            public async void IgnoresNonExistingUsers()
+            {
+                var doesntExistId = new UidIdentifier("uid_that_doesnt_exist");
+                var getUsersResult = await this.auth.GetUsersAsync(new List<UserIdentifier>()
+                {
+                    new UidIdentifier(this.testUser1.Uid),
+                    doesntExistId,
+                    new UidIdentifier(this.testUser3.Uid),
+                });
+
+                var uids = getUsersResult.Users.Select(userRecord => userRecord.Uid);
+                var expectedUids = new List<string>() { this.testUser1.Uid, this.testUser3.Uid };
+                Assert.True(expectedUids.All(expectedUid => uids.Contains(expectedUid)));
+                Assert.Equal(doesntExistId, getUsersResult.NotFound.Single());
+            }
+
+            [Fact]
+            public async void OnlyNonExistingUsers()
+            {
+                var doesntExistId = new UidIdentifier("uid_that_doesnt_exist");
+                var getUsersResult = await this.auth.GetUsersAsync(new List<UserIdentifier>()
+                {
+                    doesntExistId,
+                });
+
+                Assert.Empty(getUsersResult.Users);
+                Assert.Equal(doesntExistId, getUsersResult.NotFound.Single());
+            }
+
+            [Fact]
+            public async void DedupsDuplicateUsers()
+            {
+                var getUsersResult = await this.auth.GetUsersAsync(new List<UserIdentifier>()
+                {
+                    new UidIdentifier(this.testUser1.Uid),
+                    new UidIdentifier(this.testUser1.Uid),
+                });
+
+                var uids = getUsersResult.Users.Select(userRecord => userRecord.Uid);
+                var expectedUids = new List<string>() { this.testUser3.Uid };
+                Assert.Equal(this.testUser1.Uid, getUsersResult.Users.Single().Uid);
+                Assert.Empty(getUsersResult.NotFound);
+            }
+        }
     }
 
     /**
@@ -656,6 +932,24 @@ internal class SignInResponse
         public string IdToken { get; set; }
     }
 
+    internal class VerifyPasswordRequest
+    {
+        [Newtonsoft.Json.JsonProperty("email")]
+        public string Email { get; set; }
+
+        [Newtonsoft.Json.JsonProperty("password")]
+        public string Password { get; set; }
+
+        [Newtonsoft.Json.JsonProperty("returnSecureToken")]
+        public bool ReturnSecureToken { get; set; }
+    }
+
+    internal class VerifyPasswordResponse
+    {
+        [Newtonsoft.Json.JsonProperty("idToken")]
+        public string IdToken { get; set; }
+    }
+
     internal class RandomUser
     {
         internal string Uid { get; private set; }