Skip to main content
SeleniumDecoded

Pass HTTP Basic Authentication

Get through a browser's basic auth prompt with BiDi's authentication handler, and the URL-embedded fallback for older setups.

Stable Verified against Selenium 4.48.0

Problem

Staging is behind HTTP basic auth. The browser shows a native credentials dialog that WebDriver cannot see, and driver.get hangs until it times out.

Solution

Enable BiDi and register an authentication handler before navigating. It answers the challenge for every matching request.

BiDi authentication handler
Selenium 4 Stable 
ChromeOptions options = new ChromeOptions();
options.setCapability("webSocketUrl", true);
RemoteWebDriver driver = new ChromeDriver(options);


driver.network().addAuthenticationHandler(new UsernameAndPassword(
  System.getenv("STAGING_USER"), System.getenv("STAGING_PASSWORD")));


driver.get("https://staging.example.com/");
assertEquals("Storefront", driver.getTitle());
import os


options = webdriver.ChromeOptions()
options.enable_bidi = True
driver = webdriver.Chrome(options=options)


driver.network.add_auth_handler(os.environ["STAGING_USER"], os.environ["STAGING_PASSWORD"])


driver.get("https://staging.example.com/")
assert driver.title == "Storefront"
const options = new chrome.Options().enableBidi();
const driver = await new Builder().forBrowser('chrome').setChromeOptions(options).build();


await driver.network().addAuthenticationHandler(process.env.STAGING_USER, process.env.STAGING_PASSWORD);


await driver.get('https://staging.example.com/');
assert.strictEqual(await driver.getTitle(), 'Storefront');
var options = new ChromeOptions { UseWebSocketUrl = true };
var driver = new ChromeDriver(options);
var bidi = await driver.AsBiDiAsync();


await bidi.Network.OnAuthRequiredAsync(async e =>
  await e.Request.ContinueWithAuthAsync(new AuthCredentials(
      Environment.GetEnvironmentVariable("STAGING_USER")!,
      Environment.GetEnvironmentVariable("STAGING_PASSWORD")!)));


driver.Navigate().GoToUrl("https://staging.example.com/");
Assert.That(driver.Title, Is.EqualTo("Storefront"));

Why It Works

Basic auth is an HTTP 401 with a WWW-Authenticate challenge. BiDi’s network module intercepts the authRequired phase and lets the test supply credentials, so the browser never shows its dialog. It works in Chrome, Edge and Firefox with the same code.

Gotchas

  • Fallback without BiDi: https://user:pass@staging.example.com/ still works in Chrome and Firefox for the initial navigation, but credentials in URLs are stripped from subsequent requests in some browsers and appear in logs. Use it only where BiDi is unavailable.
  • Scope the handler to the host (Java has the Predicate<URI> overload) when the page also loads third-party resources that challenge for auth.
  • Credentials come from the environment or a secrets manager, never from source.
  • Through a Grid, BiDi requires Grid 4.20+ and a proxy that forwards WebSocket upgrades.

Learn the theory