feat(auth): Add API to look up users by federated ID.

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

@@ -605,6 +605,56 @@ protected UserRecord execute() throws FirebaseAuthException {
     };
   }
 
+  /**
+   * Gets the user data corresponding to the specified user federated identifier.
+   *
+   * @param providerUid The user identifier with the given provider.
+   * @param providerId Identifier for the given federated provider, for example,
+   *     "google.com" for the Google provider.
+   * @return A {@link UserRecord} instance.
+   * @throws IllegalArgumentException If the providerUid is null or empty, or if
+   *     the providerId is null, empty, or does not belong to a federated provider.
+   * @throws FirebaseAuthException If an error occurs while retrieving user data.
+   */
+  public UserRecord getUserByFederatedId(
+      @NonNull String providerUid, @NonNull String providerId) throws FirebaseAuthException {
+    return getUserByFederatedIdOp(providerUid, providerId).call();
+  }
+
+  /**
+   * Gets the user data corresponding to the specified user federated identifier.
+   *
+   * @param providerUid The user identifier with the given provider.
+   * @param providerId Identifer for the given federated provider, for example,
+   *     "google.com" for the Google provider.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance. If an error occurs while retrieving user data or if the uid and provider ID
+   *     do not correspond to a user, the future throws a {@link FirebaseAuthException}.
+   * @throws IllegalArgumentException If the providerUid is null or empty, or if
+   *     the provider ID is null, empty, or does not belong to a federated provider.
+   */
+  public ApiFuture<UserRecord> getUserByFederatedIdAsync(
+      @NonNull String providerUid, @NonNull String providerId) {
+    return getUserByFederatedIdOp(providerUid, providerId).callAsync(firebaseApp);
+  }
+
+  private CallableOperation<UserRecord, FirebaseAuthException> getUserByFederatedIdOp(
+      final String providerUid, final String providerId) {
+    checkNotDestroyed();
+    checkArgument(!Strings.isNullOrEmpty(providerUid), "providerUid must not be null or empty");
+    checkArgument(!Strings.isNullOrEmpty(providerId), "providerId must not be null or empty");
+    checkArgument(!providerId.equals("phone")
+        && !providerId.equals("password")
+        && !providerId.equals("anonymous"), "providerId must belong to a federated provider");
+    final FirebaseUserManager userManager = getUserManager();
+    return new CallableOperation<UserRecord, FirebaseAuthException>() {
+      @Override
+      protected UserRecord execute() throws FirebaseAuthException {
+        return userManager.getUserByFederatedId(providerUid, providerId);
+      }
+    };
+  }
+
   /**
    * Gets a page of users starting from the specified {@code pageToken}. Page size will be
    * limited to 1000 users.

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

@@ -164,6 +164,23 @@ UserRecord getUserByPhoneNumber(String phoneNumber) throws FirebaseAuthException
     return new UserRecord(response.getUsers().get(0), jsonFactory);
   }
 
+  UserRecord getUserByFederatedId(
+      String providerUid, String providerId) throws FirebaseAuthException {
+    final Map<String, Object> payload = ImmutableMap.<String, Object>of(
+        "federatedUserId", ImmutableList.of(
+            ImmutableMap.<String, Object>builder()
+            .put("rawId", providerUid).put("providerId", providerId).build()));
+
+    GetAccountInfoResponse response = post(
+        "/accounts:lookup", payload, GetAccountInfoResponse.class);
+    if (response == null || response.getUsers() == null || response.getUsers().isEmpty()) {
+      throw new FirebaseAuthException(USER_NOT_FOUND_ERROR,
+          "No user record found for providerUid " + providerUid
+          + " and federated provider ID " + providerId);
+    }
+    return new UserRecord(response.getUsers().get(0), jsonFactory);
+  }
+
   String createUser(CreateRequest request) throws FirebaseAuthException {
     GenericJson response = post(
         "/accounts", request.getProperties(), GenericJson.class);

src/test/java/com/google/firebase/auth/FirebaseAuthIT.java

@@ -49,6 +49,7 @@
 import com.google.firebase.auth.UserRecord.CreateRequest;
 import com.google.firebase.auth.UserRecord.UpdateRequest;
 import com.google.firebase.auth.hash.Scrypt;
+import com.google.firebase.internal.Nullable;
 import com.google.firebase.testing.IntegrationTestUtils;
 import java.io.IOException;
 import java.net.URLDecoder;
@@ -140,37 +141,98 @@ public void testDeleteNonExistingUser() throws Exception {
   @Test
   public void testCreateUserWithParams() throws Exception {
     RandomUser randomUser = RandomUser.create();
-    String phone = randomPhoneNumber();
-    CreateRequest user = new CreateRequest()
-        .setUid(randomUser.uid)
-        .setEmail(randomUser.email)
-        .setPhoneNumber(phone)
-        .setDisplayName("Random User")
-        .setPhotoUrl("https://example.com/photo.png")
-        .setEmailVerified(true)
-        .setPassword("password");
-
-    UserRecord userRecord = auth.createUserAsync(user).get();
+    String randomPhoneNumber = randomPhoneNumber();
     try {
-      assertEquals(randomUser.uid, userRecord.getUid());
-      assertEquals("Random User", userRecord.getDisplayName());
-      assertEquals(randomUser.email, userRecord.getEmail());
-      assertEquals(phone, userRecord.getPhoneNumber());
-      assertEquals("https://example.com/photo.png", userRecord.getPhotoUrl());
-      assertTrue(userRecord.isEmailVerified());
-      assertFalse(userRecord.isDisabled());
-
-      assertEquals(2, userRecord.getProviderData().length);
+      UserRecord user = createUser(randomUser.uid, randomPhoneNumber, randomUser.email);
+      assertEquals(randomUser.uid, user.getUid());
+      assertEquals("Random User", user.getDisplayName());
+      assertEquals(randomUser.email, user.getEmail());
+      assertEquals(randomPhoneNumber, user.getPhoneNumber());
+      assertEquals("https://example.com/photo.png", user.getPhotoUrl());
+      assertTrue(user.isEmailVerified());
+      assertFalse(user.isDisabled());
+
+      assertEquals(2, user.getProviderData().length);
       List<String> providers = new ArrayList<>();
-      for (UserInfo provider : userRecord.getProviderData()) {
+      for (UserInfo provider : user.getProviderData()) {
         providers.add(provider.getProviderId());
       }
       assertTrue(providers.contains("password"));
       assertTrue(providers.contains("phone"));
 
-      checkRecreate(randomUser.uid);
+      checkRecreate(user.getUid());
     } finally {
-      auth.deleteUserAsync(userRecord.getUid()).get();
+      auth.deleteUserAsync(randomUser.uid).get();
+    }
+  }
+
+  @Test
+  public void testLookupUserByPhone() throws Exception {
+    RandomUser randomUser1 = RandomUser.create();
+    String phoneNumber1 = null;
+    RandomUser randomUser2 = RandomUser.create();
+    String randomPhoneNumber2 = randomPhoneNumber();
+    RandomUser randomUser3 = RandomUser.create();
+    String randomPhoneNumber3 = randomPhoneNumber();
+    try {
+      UserRecord user1 = createUser(
+          randomUser1.uid, /* phoneNumber= */ null, randomUser1.email);
+      UserRecord user2 = createUser(
+          randomUser2.uid, randomPhoneNumber2, randomUser2.email);
+      UserImportResult user3 = importUser(
+          randomUser3.uid, randomPhoneNumber3, randomUser3.email, "google.com");
+
+      UserRecord lookedUpRecord = auth.getUserByPhoneNumberAsync(randomPhoneNumber2).get();
+      assertEquals(lookedUpRecord.getUid(), randomUser2.uid);
+
+      lookedUpRecord = auth.getUserByPhoneNumberAsync(randomPhoneNumber3).get();
+      assertEquals(lookedUpRecord.getUid(), randomUser3.uid);
+    } finally {
+      auth.deleteUserAsync(randomUser1.uid).get();
+      auth.deleteUserAsync(randomUser2.uid).get();
+      auth.deleteUserAsync(randomUser3.uid).get();
+    }
+  }
+
+  @Test
+  public void testLookupUserByFederatedId() throws Exception {
+    RandomUser randomUser1 = RandomUser.create();
+    String phoneNumber1 = null;
+    RandomUser randomUser2 = RandomUser.create();
+    String randomPhoneNumber2 = randomPhoneNumber();
+    RandomUser randomUser3 = RandomUser.create();
+    String randomPhoneNumber3 = randomPhoneNumber();
+    try {
+      UserRecord user1 = createUser(
+          randomUser1.uid, /* phoneNumber= */ null, randomUser1.email);
+      UserRecord user2 = createUser(
+          randomUser2.uid, randomPhoneNumber2, randomUser2.email);
+      UserImportResult user3 = importUser(
+          randomUser3.uid, randomPhoneNumber3, randomUser3.email, "google.com");
+
+      UserRecord lookedUpRecord = auth.getUserByFederatedIdAsync(
+          randomUser3.uid + "_google.com", "google.com").get();
+      assertEquals(lookedUpRecord.getUid(), randomUser3.uid);
+      assertEquals(2, lookedUpRecord.getProviderData().length);
+      List<String> providers = new ArrayList<>();
+      for (UserInfo provider : lookedUpRecord.getProviderData()) {
+        providers.add(provider.getProviderId());
+      }
+      assertTrue(providers.contains("phone"));
+      assertTrue(providers.contains("google.com"));
+
+      try {
+        // Verify that lookup by federated identifier does not accept "phone".
+        lookedUpRecord = auth.getUserByFederatedIdAsync(
+            randomPhoneNumber3, "phone").get();
+        fail("No error thrown for non-federated provider");
+      } catch (IllegalArgumentException ignored) {
+        // expected
+      }
+    } finally {
+      auth.deleteUserAsync(randomUser1.uid).get();
+      auth.deleteUserAsync(randomUser2.uid).get();
+      auth.deleteUserAsync(randomUser3.uid).get();
     }
   }
 
@@ -590,6 +652,52 @@ public void testGenerateSignInWithEmailLink() throws Exception {
     }
   }
 
+  private UserRecord createUser(
+      String uid,
+      @Nullable String phoneNumber,
+      @Nullable String email) throws Exception {
+    RandomUser randomUser = RandomUser.create();
+    CreateRequest user = new CreateRequest()
+        .setUid(uid)
+        .setDisplayName("Random User")
+        .setPhotoUrl("https://example.com/photo.png")
+        .setPassword("password");
+    if (phoneNumber != null) {
+      user.setPhoneNumber(phoneNumber);
+    }
+    if (email != null) {
+      user.setEmail(email);
+      user.setEmailVerified(true);
+    }
+    return auth.createUserAsync(user).get();
+  }
+
+  private UserImportResult importUser(
+      String uid,
+      @Nullable String phoneNumber,
+      @Nullable String email,
+      String providerId) throws Exception {
+    ImportUserRecord.Builder builder = ImportUserRecord.builder()
+        .setUid(uid)
+        .setDisabled(false)
+        .setUserMetadata(
+            new UserMetadata(/* creationTimestamp= */ 20L, /* lastSignInTimestamp= */ 20L))
+        .addUserProvider(
+            UserProvider.builder()
+            .setProviderId(providerId)
+            .setUid(uid + "_" + providerId)
+            .build());
+    if (phoneNumber != null) {
+      builder.setPhoneNumber(phoneNumber);
+    }
+    if (email != null) {
+      builder.setEmail(email);
+      builder.setEmailVerified(true);
+    }
+    ImportUserRecord user = builder.build();
+    return auth.importUsersAsync(ImmutableList.of(user)).get();
+  }
+
   private Map<String, String> parseLinkParameters(String link) throws Exception {
     Map<String, String> result = new HashMap<>();
     int queryBegin = link.indexOf('?');

src/test/java/com/google/firebase/snippets/FirebaseAuthSnippets.java

@@ -85,6 +85,16 @@ public static void getUserByPhoneNumber(
     // [END get_user_by_phone]
   }
 
+  public static void getUserByFederatedId(
+      String providerUid, String providerId) throws FirebaseAuthException {
+    // [START get_user_by_federated_id]
+    UserRecord userRecord = FirebaseAuth.getInstance().getUserByFederatedId(
+        providerUid, providerId);
+    // See the UserRecord reference doc for the contents of userRecord.
+    System.out.println("Successfully fetched user data: " + userRecord.getUid());
+    // [END get_user_by_federated_id]
+  }
+
   public static void createUser() throws FirebaseAuthException {
     // [START create_user]
     CreateRequest request = new CreateRequest()