Add configurable OAuthWebServerTimeout connection property (#1226)

## Summary
- Adds a new `OAuthWebServerTimeout` connection property to configure
the OAuth browser authentication timeout for U2M (user-to-machine) flows
- Replaces the hardcoded 1-hour timeout in
`ClientConfigurator.setupU2MConfig()` with the configurable value
- Default is **120 seconds**, matching Simba driver parity

## Changes
| File | Change |
|------|--------|
| `DatabricksJdbcUrlParams.java` | New `OAUTH_WEB_SERVER_TIMEOUT` enum
entry (default: `"120"`) |
| `IDatabricksConnectionContext.java` | Added
`getOAuthWebServerTimeout()` interface method |
| `DatabricksConnectionContext.java` | Implemented the getter |
| `ClientConfigurator.java` | Replaced `Duration.ofHours(1)` with
`Duration.ofSeconds(connectionContext.getOAuthWebServerTimeout())` |
| `DatabricksConnectionContextTest.java` | Tests for default (120) and
custom (300) values |
| `ClientConfiguratorTest.java` | Updated 9 browser auth tests to mock
the new method |

## Test plan
- [x] `DatabricksConnectionContextTest#testOAuthWebServerTimeoutDefault`
— verifies default 120s
- [x] `DatabricksConnectionContextTest#testOAuthWebServerTimeoutCustom`
— verifies custom value via URL param
- [x] All 25 `ClientConfiguratorTest` tests pass with the configurable
timeout wired through

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: gopalldb

NEXT_CHANGELOG.md

@@ -3,6 +3,7 @@
 ## [Unreleased]
 
 ### Added
+- Added connection property `OAuthWebServerTimeout` to configure the OAuth browser authentication timeout for U2M (user-to-machine) flows, and also updated hardcoded 1-hour timeout to default 120 seconds timeout.
 
 ### Updated
 

src/main/java/com/databricks/jdbc/api/impl/DatabricksConnectionContext.java

@@ -810,6 +810,12 @@ public List<Integer> getOAuth2RedirectUrlPorts() {
     }
   }
 
+  /** {@inheritDoc} */
+  @Override
+  public int getOAuthWebServerTimeout() {
+    return Integer.parseInt(getParameter(DatabricksJdbcUrlParams.OAUTH_WEB_SERVER_TIMEOUT));
+  }
+
   @Override
   public Boolean getUseEmptyMetadata() {
     String param = getParameter(DatabricksJdbcUrlParams.USE_EMPTY_METADATA);

src/main/java/com/databricks/jdbc/api/internal/IDatabricksConnectionContext.java

@@ -234,6 +234,9 @@ public interface IDatabricksConnectionContext {
   /** Returns the list of OAuth2 redirect URL ports used for OAuth authentication. */
   List<Integer> getOAuth2RedirectUrlPorts();
 
+  /** Returns the OAuth browser authentication timeout in seconds for U2M authentication. */
+  int getOAuthWebServerTimeout();
+
   String getGcpAuthType() throws DatabricksParsingException;
 
   String getGoogleServiceAccount();

src/main/java/com/databricks/jdbc/common/DatabricksJdbcUrlParams.java

@@ -35,6 +35,8 @@ public enum DatabricksJdbcUrlParams {
   OAUTH_REFRESH_TOKEN("Auth_RefreshToken", "OAuth2 Refresh Token"),
   OAUTH_REFRESH_TOKEN_2("OAuthRefreshToken", "OAuth2 Refresh Token"), // Same as OAUTH_REFRESH_TOKEN
   OAUTH_REDIRECT_URL_PORT("OAuth2RedirectUrlPort", "OAuth2 Redirect URL port", "8020"),
+  OAUTH_WEB_SERVER_TIMEOUT(
+      "OAuthWebServerTimeout", "OAuth browser authentication timeout in seconds", "120"),
   PWD("pwd", "Password (used when AUTH_MECH = 3)", true),
   POLL_INTERVAL("asyncexecpollinterval", "Async execution poll interval", "200"),
   HTTP_PATH("httppath", "HTTP path", true),

src/main/java/com/databricks/jdbc/dbclient/impl/common/ClientConfigurator.java

@@ -206,7 +206,7 @@ public void setupU2MConfig() throws DatabricksParsingException {
         .setHost(host)
         .setClientId(clientId)
         .setOAuthBrowserAuthTimeout(
-            Duration.ofHours(1)) // TODO : add a browser timeout connection config
+            Duration.ofSeconds(connectionContext.getOAuthWebServerTimeout()))
         .setClientSecret(connectionContext.getClientSecret())
         .setOAuthRedirectUrl(redirectUrl);
 

src/test/java/com/databricks/jdbc/api/impl/DatabricksConnectionContextTest.java

@@ -1342,4 +1342,19 @@ public void testGetThriftMaxBatchesInMemoryInvalidFallback() throws DatabricksSQ
             DatabricksConnectionContext.parse(TestConstants.VALID_URL_1, props);
     assertEquals(3, ctx.getThriftMaxBatchesInMemory()); // Should fall back to default
   }
+
+  @Test
+  public void testOAuthWebServerTimeoutDefault() throws DatabricksSQLException {
+    IDatabricksConnectionContext connectionContext =
+        DatabricksConnectionContext.parse(TestConstants.VALID_URL_1, properties);
+    assertEquals(120, connectionContext.getOAuthWebServerTimeout());
+  }
+
+  @Test
+  public void testOAuthWebServerTimeoutCustom() throws DatabricksSQLException {
+    IDatabricksConnectionContext connectionContext =
+        DatabricksConnectionContext.parse(
+            TestConstants.VALID_URL_1 + ";OAuthWebServerTimeout=300", properties);
+    assertEquals(300, connectionContext.getOAuthWebServerTimeout());
+  }
 }

src/test/java/com/databricks/jdbc/dbclient/impl/common/ClientConfiguratorTest.java

@@ -191,6 +191,7 @@ void getWorkspaceClient_OAuthWithBrowserBasedAuthentication_AuthenticatesCorrect
     when(mockContext.getOAuth2RedirectUrlPorts()).thenReturn(List.of(8020));
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(true);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
     configurator = new ClientConfigurator(mockContext);
     WorkspaceClient client = configurator.getWorkspaceClient();
     assertNotNull(client);
@@ -217,6 +218,7 @@ void getWorkspaceClient_OAuthWithBrowserBasedAuthentication_ScopesExcludeOffline
     when(mockContext.getOAuth2RedirectUrlPorts()).thenReturn(List.of(8030));
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(true);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
 
     configurator = new ClientConfigurator(mockContext);
     DatabricksConfig config = configurator.getDatabricksConfig();
@@ -246,6 +248,7 @@ void getWorkspaceClient_OAuthWithBrowserBasedAuthentication_ScopesExcludeOffline
     when(mockContext.getOAuth2RedirectUrlPorts()).thenReturn(List.of(8020));
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(true);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
     configurator = new ClientConfigurator(mockContext);
     WorkspaceClient client = configurator.getWorkspaceClient();
     assertNotNull(client);
@@ -491,6 +494,7 @@ void getWorkspaceClient_OAuthWithBrowserBasedAuthentication_SetsCustomRedirectUr
     when(mockContext.getHttpConnectionPoolSize()).thenReturn(100);
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(true);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
 
     configurator = new ClientConfigurator(mockContext);
     WorkspaceClient client = configurator.getWorkspaceClient();
@@ -501,7 +505,7 @@ void getWorkspaceClient_OAuthWithBrowserBasedAuthentication_SetsCustomRedirectUr
     assertEquals("browser-client-id", config.getClientId());
     assertEquals("browser-client-secret", config.getClientSecret());
     assertEquals(List.of("scope1", "scope2"), config.getScopes());
-    assertEquals(Duration.ofHours(1), config.getOAuthBrowserAuthTimeout());
+    assertEquals(Duration.ofSeconds(120), config.getOAuthBrowserAuthTimeout());
     assertEquals("http://localhost:" + testPort, config.getOAuthRedirectUrl());
     assertEquals(DatabricksJdbcConstants.U2M_AUTH_TYPE, config.getAuthType());
   }
@@ -522,6 +526,7 @@ void testSetupU2MConfig_WithTokenCache()
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(true);
     when(mockContext.isTokenFederationEnabled()).thenReturn(true);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
 
     configurator = new ClientConfigurator(mockContext);
     WorkspaceClient client = configurator.getWorkspaceClient();
@@ -556,6 +561,7 @@ void testSetupU2MConfig_WithTokenCacheNoPassphrase()
     when(mockContext.getTokenCachePassPhrase()).thenReturn(null);
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(true);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
 
     assertThrows(DatabricksException.class, () -> new ClientConfigurator(mockContext));
   }
@@ -575,6 +581,7 @@ void testSetupU2MConfig_WithoutTokenCache()
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(true);
     when(mockContext.isTokenFederationEnabled()).thenReturn(true);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
 
     configurator = new ClientConfigurator(mockContext);
     WorkspaceClient client = configurator.getWorkspaceClient();
@@ -686,6 +693,7 @@ void testAuthScope_U2MWithCustomScope()
     when(mockContext.getOAuth2RedirectUrlPorts()).thenReturn(List.of(8020));
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(true);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
 
     configurator = new ClientConfigurator(mockContext);
     DatabricksConfig config = configurator.getDatabricksConfig();
@@ -710,6 +718,7 @@ void testAuthScope_U2MWithDefaultScopes()
     when(mockContext.getOAuth2RedirectUrlPorts()).thenReturn(List.of(8020));
     when(mockContext.getHttpMaxConnectionsPerRoute()).thenReturn(100);
     when(mockContext.getDisableOauthRefreshToken()).thenReturn(false);
+    when(mockContext.getOAuthWebServerTimeout()).thenReturn(120);
 
     configurator = new ClientConfigurator(mockContext);
     DatabricksConfig config = configurator.getDatabricksConfig();