Add method to get user by external uid #427 (#428)

This only works for admin users

src/main/java/org/gitlab4j/api/UserApi.java

@@ -371,6 +371,48 @@ public class UserApi extends AbstractApi {
         }
     }
 
+    /**
+     * Lookup a user by external UID.  Returns null if not found.
+     *
+     * <p>NOTE: This is for admin users only.</p>
+     *
+     * <pre><code>GitLab Endpoint: GET /users?extern_uid=:externalUid&provider=:provider</code></pre>
+     *
+     * @param provider the provider of the external uid
+     * @param externalUid the external UID of the user
+     * @return the User instance for the specified external UID, or null if not found
+     * @throws GitLabApiException if any exception occurs
+     */
+    public User getUserByExternalUid(String provider, String externalUid) throws GitLabApiException {
+        GitLabApiForm formData = createGitLabApiForm()
+                .withParam("provider", provider, true)
+                .withParam("extern_uid", externalUid, true)
+                .withParam(PAGE_PARAM, 1)
+                .withParam(PER_PAGE_PARAM, 1);
+        Response response = get(Response.Status.OK, formData.asMap(), "users");
+        List<User> users = response.readEntity(new GenericType<List<User>>() {});
+        return (users.isEmpty() ? null : users.get(0));
+    }
+
+    /**
+     * Lookup a user by external UID and return an Optional instance.
+     *
+     * <p>NOTE: This is for admin users only.</p>
+     *
+     * <pre><code>GitLab Endpoint: GET /users?extern_uid=:externUid&provider=:provider</code></pre>
+     *
+     * @param provider the provider of the external uid
+     * @param externalUid the external UID of the user
+     * @return the User for the specified external UID as an Optional instance
+     */
+    public Optional<User> getOptionalUserByExternalUid(String provider, String externalUid) {
+        try {
+            return (Optional.ofNullable(getUserByExternalUid(provider, externalUid)));
+        } catch (GitLabApiException glae) {
+            return (GitLabApi.createOptionalFromException(glae));
+        }
+    }
+
     /**
      * Search users by Email or username
      *

src/test/java/org/gitlab4j/api/IntegrationTestSuite.java

@@ -4,15 +4,9 @@ import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.fail;
 
-import java.util.Arrays;
-import java.util.List;
-import java.util.Optional;
-
-import org.gitlab4j.api.models.Group;
-import org.gitlab4j.api.models.Project;
-import org.gitlab4j.api.models.RepositoryFile;
-import org.gitlab4j.api.models.User;
-import org.gitlab4j.api.models.Visibility;
+import java.util.*;
+
+import org.gitlab4j.api.models.*;
 import org.gitlab4j.api.utils.AccessTokenUtils;
 import org.gitlab4j.api.utils.AccessTokenUtils.Scope;
 import org.junit.AfterClass;
@@ -44,6 +38,8 @@ public class IntegrationTestSuite implements PropertyConstants {
     private static final String TEST_GROUP = HelperUtils.getProperty(GROUP_KEY);
     private static final String TEST_GROUP_PROJECT_NAME = HelperUtils.getProperty(GROUP_PROJECT_KEY);
     private static final String TEST_SUB_GROUP = HelperUtils.getProperty(SUB_GROUP_KEY);
+    private static final String TEST_EXTERNAL_PROVIDER = HelperUtils.getProperty(EXTERNAL_PROVIDER_KEY);
+    private static final String TEST_EXTERNAL_UID = HelperUtils.getProperty(EXTERNAL_UID_KEY);
 
     protected static final String TEST_PRIVATE_TOKEN_NAME = "GitLab4J Test Private Token - " + HelperUtils.getRandomInt(1000);
     protected static String TEST_PRIVATE_TOKEN = HelperUtils.getProperty(PRIVATE_TOKEN_KEY);
@@ -168,12 +164,18 @@ public class IntegrationTestSuite implements PropertyConstants {
         // If the tester user doen't exists, create it
         Optional<User> optionalUser = gitLabApi.getUserApi().getOptionalUser(TEST_LOGIN_USERNAME);
         if (!optionalUser.isPresent()) {
+            Identity identity = new Identity();
+            identity.setExternUid(TEST_EXTERNAL_UID);
+            identity.setProvider(TEST_EXTERNAL_PROVIDER);
+
             User userSettings = new User()
                     .withUsername(TEST_LOGIN_USERNAME)
                     .withEmail(TEST_LOGIN_USERNAME + "@gitlab4j.org")
                     .withName("GitLab4J Tester")
                     .withSkipConfirmation(true)
-                    .withIsAdmin(true);
+                    .withIsAdmin(true)
+                    .withIdentities(Collections.singletonList(identity));
+
             gitLabApi.getUserApi().createUser(userSettings, TEST_LOGIN_PASSWORD, false);
             System.out.format("Created %s user (%s)%n", userSettings.getName(), userSettings.getUsername());
         }

src/test/java/org/gitlab4j/api/PropertyConstants.java

@@ -28,4 +28,6 @@ public interface PropertyConstants {
     public static final String TEST_REQUEST_ACCESS_USERNAME_KEY = "TEST_REQUEST_ACCESS_USERNAME";
     public static final String USERNAME_KEY = "TEST_USERNAME";
     public static final String XFER_NAMESPACE_KEY = "TEST_XFER_NAMESPACE";
+    public static final String EXTERNAL_PROVIDER_KEY = "TEST_EXTERNAL_PROVIDER";
+    public static final String EXTERNAL_UID_KEY = "TEST_EXTERNAL_UID";
 }

src/test/java/org/gitlab4j/api/TestUserApi.java

@@ -64,7 +64,9 @@ public class TestUserApi extends AbstractIntegrationTest {
             "IW/2DIlUts7gcB2hzXtt7r7+6DLx82Vb+S2jPZu2JQaB4zfgS7LQgzHUy1aAAgUUpuAbvWzuGHKO0p551Ru4qi" +
             "tyXN2+OUVXcYAsuIIdGGB0wLvTDgiOOSZWnSE+sg6XX user@example.com";
     private static final String TEST_USER_EMAIL = "test-user-email123@gitlab4j.org";
-    
+
+    private static final String TEST_EXTERNAL_PROVIDER = HelperUtils.getProperty(EXTERNAL_PROVIDER_KEY);
+    private static final String TEST_EXTERNAL_UID = HelperUtils.getProperty(EXTERNAL_UID_KEY);
 
     private static GitLabApi gitLabApi;
     private static User blockUser;
@@ -180,6 +182,18 @@ public class TestUserApi extends AbstractIntegrationTest {
         assertFalse(optional.isPresent());
     }
 
+    @Test
+    public void testGetOptionalUserByExternalUid() throws GitLabApiException {
+
+        Optional<User> optional = gitLabApi.getUserApi().getOptionalUserByExternalUid(TEST_EXTERNAL_PROVIDER, TEST_EXTERNAL_UID);
+        assertNotNull(optional);
+        assertTrue(optional.isPresent());
+
+        optional = gitLabApi.getUserApi().getOptionalUserByExternalUid("unknown-provider", "unknown-uid");
+        assertNotNull(optional);
+        assertFalse(optional.isPresent());
+    }
+
     @Test
     public void testSudoAsUser() throws GitLabApiException {
 

src/test/resources/test-gitlab4j.properties

@@ -29,6 +29,12 @@ TEST_LOGIN_PASSWORD=ChangeMeNow
 TEST_PROJECT_NAME=test-project
 TEST_USERNAME=gitlab4j
 
+# This specifies the default external provider to test against and the user served by this provider, change
+# this if you'd like to test against a different project
+TEST_EXTERNAL_PROVIDER=github
+TEST_EXTERNAL_UID=2435223452345
+
+
 # This is the user to test sudo, block, and project transfer.  If the user does not exist
 # it will be created during integration testing
 TEST_SUDO_AS_USERNAME=user1