Teach ApiKeyCredentialsProvider to respond to server auth challenge (#68)

Author: labkey-adam

CHANGELOG.md

@@ -9,8 +9,10 @@
 * Remove deprecated method `RowsResponse.getRequiredVersion()`.
 * Deprecate `GetUsersCommand` methods `getIncludeDeactivated()` and `setIncludeDeactivated()`; use `getIncludeInactive()`
   and `setIncludeInactive()` instead.
-* Update Commons Logging, Gradle, Gradle Plugins, HttpClient, and HttpCore versions
 * Remove Hamcrest references (unused)
+* Update `ApiKeyCredentialsProvider` to respond to server auth challenges with the `apikey` header and use the session
+  on subsequent requests.
+* Update Commons Logging, Gradle, Gradle Plugins, HttpClient, and HttpCore versions
 
 ## version 6.0.0
 *Released*: 1 December 2023

gradle.properties

@@ -7,12 +7,12 @@ artifactory_contextUrl=https://labkey.jfrog.io/artifactory
 sourceCompatibility=17
 targetCompatibility=17
 
-gradlePluginsVersion=2.0.0
+gradlePluginsVersion=2.2.1
 
 commonsCodecVersion=1.16.0
 commonsLoggingVersion=1.3.0
 
-httpclient5Version=5.3
+httpclient5Version=5.3.1
 httpcore5Version=5.2.4
 
 jsonObjectVersion=20231013

src/org/labkey/remoteapi/ApiKeyCredentialsProvider.java

@@ -18,7 +18,7 @@
 import org.apache.hc.client5.http.classic.methods.HttpUriRequest;
 import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
 import org.apache.hc.client5.http.protocol.HttpClientContext;
-import org.labkey.remoteapi.security.WhoAmICommand;
+import org.labkey.remoteapi.security.EnsureLoginCommand;
 
 import java.io.IOException;
 import java.net.URI;
@@ -40,13 +40,27 @@ public void configureClientBuilder(URI baseURI, HttpClientBuilder builder)
     @Override
     public void configureRequest(URI baseURI, HttpUriRequest request, HttpClientContext httpClientContext)
     {
-        request.setHeader("apikey", _apiKey);
     }
 
     @Override
     public void initializeConnection(Connection connection) throws IOException, CommandException
     {
-        // No point in calling ensureLogin.api since the server doesn't "log in" the session when using an API key
-        new WhoAmICommand().execute(connection, "/home");
+        new EnsureLoginCommand().execute(connection, "/home");
+    }
+
+    @Override
+    public boolean shouldRetryRequest(CommandException exception, HttpUriRequest request)
+    {
+        // Determine if this is a Basic Auth challenge. If so, set the apikey header and retry the request. Subsequent
+        // requests should use the session. This mimics the behavior of BasicAuthCredentialsProvider.
+
+        String authHeaderValue = exception.getAuthHeaderValue();
+
+        boolean authChallenge = (null != authHeaderValue && authHeaderValue.startsWith("Basic realm") && "You must log in to view this content.".equals(exception.getMessage()));
+
+        if (authChallenge)
+            request.setHeader("apikey", _apiKey);
+
+        return authChallenge;
     }
 }

src/org/labkey/remoteapi/ApiVersionException.java

@@ -19,8 +19,8 @@
 
 public class ApiVersionException extends CommandException
 {
-    ApiVersionException(String message, int statusCode, JSONObject jsonProperties, String responseText, String contentType)
+    ApiVersionException(String message, int statusCode, JSONObject jsonProperties, String responseText, String contentType, String authHeaderValue)
     {
-        super(message, statusCode, jsonProperties, responseText, contentType);
+        super(message, statusCode, jsonProperties, responseText, contentType, authHeaderValue);
     }
 }

src/org/labkey/remoteapi/Command.java

@@ -20,9 +20,12 @@
 import org.apache.hc.client5.http.classic.methods.HttpUriRequest;
 import org.apache.hc.client5.http.impl.classic.CloseableHttpResponse;
 import org.apache.hc.core5.http.Header;
+import org.apache.hc.core5.http.HttpHeaders;
+import org.apache.hc.core5.http.ProtocolException;
 import org.apache.hc.core5.net.URIBuilder;
 import org.json.JSONObject;
 import org.json.JSONTokener;
+import org.labkey.remoteapi.query.SelectRowsCommand;
 
 import java.io.BufferedReader;
 import java.io.ByteArrayInputStream;
@@ -44,7 +47,7 @@
 /**
  * Abstract base class for all API commands. Developers interact with concrete classes that
  * extend this class. For example, to select data, create an instance of
- * {@link org.labkey.remoteapi.query.SelectRowsCommand}, which provides helpful methods for
+ * {@link SelectRowsCommand}, which provides helpful methods for
  * setting options and obtaining specific result types.
  * <p>
  * If a developer wishes to invoke actions that are not yet supported with a specialized class
@@ -283,6 +286,19 @@ public String getText() throws IOException
             }
         }
 
+        public String getHeaderValue(String name)
+        {
+            Header header = null;
+            try
+            {
+                header = _httpResponse.getHeader(name);
+            }
+            catch (ProtocolException ignored)
+            {
+            }
+            return null == header ? null : header.getValue();
+        }
+
         // Caller is responsible for closing the response
         @Override
         public void close() throws IOException
@@ -291,27 +307,39 @@ public void close() throws IOException
         }
     }
 
-    /* NOTE: Internal experimental API for handling streaming commands. */
     protected Response _execute(Connection connection, String folderPath) throws CommandException, IOException
     {
         assert null != getControllerName() : "You must set the controller name before executing the command!";
         assert null != getActionName() : "You must set the action name before executing the command!";
-        CloseableHttpResponse httpResponse;
 
-        final HttpUriRequest request;
         try
         {
             //construct and initialize the HttpUriRequest
-            request = getHttpRequest(connection, folderPath);
-            LogFactory.getLog(Command.class).info("Requesting URL: " + request.getRequestUri());
-
-            //execute the request
-            httpResponse = connection.executeRequest(request, getTimeout());
+            final HttpUriRequest request = getHttpRequest(connection, folderPath);
+            try
+            {
+                return executeRequest(connection, request);
+            }
+            catch (CommandException e)
+            {
+                if (connection.getCredentialsProvider().shouldRetryRequest(e, request))
+                    return executeRequest(connection, request);
+                else
+                    throw e;
+            }
         }
         catch (URISyntaxException | AuthenticationException e)
         {
             throw new CommandException(e.getMessage());
         }
+    }
+
+    private Response executeRequest(Connection connection, HttpUriRequest request) throws AuthenticationException, IOException, CommandException
+    {
+        LogFactory.getLog(Command.class).info("Requesting URL: " + request.getRequestUri());
+
+        //execute the request
+        CloseableHttpResponse httpResponse = connection.executeRequest(request, getTimeout());
 
         //get the content-type header
         Header contentTypeHeader = httpResponse.getFirstHeader("Content-Type");
@@ -322,10 +350,11 @@ protected Response _execute(Connection connection, String folderPath) throws Com
 
         Response response = new Response(httpResponse, contentType, contentLength);
         checkThrowError(response);
+
         return response;
     }
 
-    protected void checkThrowError(Response response) throws IOException, CommandException
+    private void checkThrowError(Response response) throws IOException, CommandException
     {
         int status = response.getStatusCode();
 
@@ -352,6 +381,8 @@ private void throwError(Response r, boolean throwByDefault) throws IOException,
         //use the status text as the message by default
         String message = null != r.getStatusText() ? r.getStatusText() : "(no status text)";
 
+        String authHeaderValue = r.getHeaderValue(HttpHeaders.WWW_AUTHENTICATE);
+
         // This buffers the entire response in memory, which seems OK for API error responses.
         String responseText = r.getText();
         JSONObject json = null;
@@ -370,15 +401,15 @@ private void throwError(Response r, boolean throwByDefault) throws IOException,
                     message = json.getString("exception");
 
                     if ("org.labkey.api.action.ApiVersionException".equals(json.opt("exceptionClass")))
-                        throw new ApiVersionException(message, r.getStatusCode(), json, responseText, contentType);
+                        throw new ApiVersionException(message, r.getStatusCode(), json, responseText, contentType, authHeaderValue);
 
-                    throw new CommandException(message, r.getStatusCode(), json, responseText, contentType);
+                    throw new CommandException(message, r.getStatusCode(), json, responseText, contentType, authHeaderValue);
                 }
             }
         }
 
         if (throwByDefault)
-            throw new CommandException(message, r.getStatusCode(), json, responseText, contentType);
+            throw new CommandException(message, r.getStatusCode(), json, responseText, contentType, authHeaderValue);
 
         // If we didn't encounter an exception property on the json object, save the fully consumed text and parsed json on the Response object
         r._json = json;

src/org/labkey/remoteapi/CommandException.java

@@ -38,6 +38,7 @@
 public class CommandException extends Exception
 {
     private final String _contentType;
+    private final String _authHeaderValue;
     private final int _statusCode;
     private final JSONObject _jsonProperties;
     private final String _responseText;
@@ -49,7 +50,7 @@ public class CommandException extends Exception
      */
     public CommandException(String message)
     {
-        this(message, 0, null, null, null);
+        this(message, 0, null, null, null, null);
     }
 
     /**
@@ -60,14 +61,16 @@ public CommandException(String message)
      * @param jsonProperties The exception property JSONObject (may be null)
      * @param responseText The full response text (may be null)
      * @param contentType The response content type (may be null)
+     * @param authHeaderValue The value of the WWW-Authenticate header (may be null)
      */
-    public CommandException(String message, int statusCode, JSONObject jsonProperties, String responseText, String contentType)
+    public CommandException(String message, int statusCode, JSONObject jsonProperties, String responseText, String contentType, String authHeaderValue)
     {
         super(buildMessage(message, statusCode));
         _statusCode = statusCode;
         _jsonProperties = jsonProperties;
         _responseText = responseText;
         _contentType = contentType;
+        _authHeaderValue = authHeaderValue;
     }
 
     private static String buildMessage(String message, int statusCode)
@@ -114,6 +117,15 @@ public String getResponseText()
         return _responseText;
     }
 
+    /**
+     * Returns the value of the WWW-Authenticate header
+     * @return The value or null
+     */
+    public String getAuthHeaderValue()
+    {
+        return _authHeaderValue;
+    }
+
     /**
      * Returns the exception property map, or null if no map was set.
      * @return The exception property map or null.

src/org/labkey/remoteapi/Connection.java

@@ -398,7 +398,7 @@ CloseableHttpResponse executeRequest(HttpUriRequest request, Integer timeout) th
 
         CloseableHttpClient client = getHttpClient();
 
-        // Set the timeout on the request if it is different the client's default
+        // Set the timeout on the request if it's different from the client's default
         if (request instanceof HttpUriRequestBase r && timeout != null && timeout != getTimeout())
         {
             RequestConfig base = r.getConfig();
@@ -490,6 +490,11 @@ public void setUserAgent(String userAgent)
         _userAgent = userAgent;
     }
 
+    public CredentialsProvider getCredentialsProvider()
+    {
+        return _credentialsProvider;
+    }
+
     /**
      * @param name The cookie name
      * @param value The cookie value

src/org/labkey/remoteapi/CredentialsProvider.java

@@ -29,8 +29,16 @@ public interface CredentialsProvider
     void configureRequest(URI baseURI, HttpUriRequest request, HttpClientContext httpClientContext) throws AuthenticationException;
 
     /**
-     * Initialize the connection before its first request. If connection-based, authenticate the user. In all cases,
-     * retrieve the CSRF token and session ID to use with subsequent requests on this connection.
+     * Initialize the connection before its first request. For example, make a request to retrieve CSRF token & session
+     * ID and/or ensure the user is logged in.
      */
     void initializeConnection(Connection connection) throws IOException, CommandException;
+
+    /**
+     * Should the Command attempt to retry the request?
+     */
+    default boolean shouldRetryRequest(CommandException exception, HttpUriRequest request)
+    {
+        return false;
+    }
 }