docs.rodeo

MDN Web Docs mirror

webRequest.onAuthRequired

{{AddonSidebar}} 

Fired when the server sends a 401 or 407 status code and a WWW-Authenticate header using the Basic scheme (that is, when the server asks the client to provide authentication credentials, such as a username and password).

The listener can respond in one of four ways:

See Examples.

If your extension provides bad credentials, then the listener is called again. For this reason, take care to avoid entering an infinite loop by repeatedly providing bad credentials.

Permissions

In Firefox and Chrome Manifest V2 extensions, you must add the "webRequest" and "webRequestBlocking" API permissions to your manifest.json.

For Manifest V3 extensions, Chrome no longer supports the "webRequestBlocking" permission (except for policy-installed extensions). Instead, the "webRequest" and "webRequestAuthProvider" permissions enable you to supply credentials asynchronously. Firefox continues to support "webRequestBlocking" in Manifest V3 and provides "webRequestAuthProvider" to offer cross-browser compatibility.

Proxy authorization

Firefox does not generally fire webRequest events for system requests, such as browser or extension upgrades or search engine queries. To enable proxy authorization to work smoothly for system requests, from version 57, Firefox supports an exception to this.

If an extension has the "webRequest", "webRequestBlocking", "proxy", and "<all_urls>" permissions, then it can use onAuthRequired to supply credentials for proxy authorization (but not for normal web authorization). The listener cannot cancel system requests or make any other modifications to any system requests.

Syntax

browser.webRequest.onAuthRequired.addListener(
  listener,                    // function
  filter,                      //  object
  extraInfoSpec                //  optional array of strings
)
browser.webRequest.onAuthRequired.removeListener(listener)
browser.webRequest.onAuthRequired.hasListener(listener)

Events have three functions:

addListener syntax

Parameters

Additional objects

details

Examples

This code observes authentication requests for the target URL:

const target = "https://intranet.company.com/";

function observe(requestDetails) {
  console.log(`observing: ${requestDetails.requestId}`);
}

browser.webRequest.onAuthRequired.addListener(observe, { urls: [target] });

This code cancels authentication requests for the target URL:

const target = "https://intranet.company.com/";

function cancel(requestDetails) {
  console.log(`canceling: ${requestDetails.requestId}`);
  return { cancel: true };
}

browser.webRequest.onAuthRequired.addListener(cancel, { urls: [target] }, [
  "blocking",
]);

This code supplies credentials synchronously. It keeps track of outstanding requests to ensure that it doesn’t repeatedly try to submit bad credentials:

const target = "https://intranet.company.com/";

const myCredentials = {
  username: "me@company.com",
  password: "zDR$ERHGDFy",
};

const pendingRequests = [];

// A request has completed.
// We can stop worrying about it.
function completed(requestDetails) {
  console.log(`completed: ${requestDetails.requestId}`);
  let index = pendingRequests.indexOf(requestDetails.requestId);
  if (index > -1) {
    pendingRequests.splice(index, 1);
  }
}

function provideCredentialsSync(requestDetails) {
  // If we have seen this request before, then
  // assume our credentials were bad, and give up.
  if (pendingRequests.includes(requestDetails.requestId)) {
    console.log(`bad credentials for: ${requestDetails.requestId}`);
    return { cancel: true };
  }
  pendingRequests.push(requestDetails.requestId);
  console.log(`providing credentials for: ${requestDetails.requestId}`);
  return { authCredentials: myCredentials };
}

browser.webRequest.onAuthRequired.addListener(
  provideCredentialsSync,
  { urls: [target] },
  ["blocking"],
);

browser.webRequest.onCompleted.addListener(completed, { urls: [target] });

browser.webRequest.onErrorOccurred.addListener(completed, { urls: [target] });

This code supplies credentials asynchronously, fetching them from storage. It also keeps track of outstanding requests to ensure that it doesn’t repeatedly try to submit bad credentials:

const target = "https://httpbin.org/basic-auth/*";

const pendingRequests = [];

/*
 * A request has completed. We can stop worrying about it.
 */
function completed(requestDetails) {
  console.log(`completed: ${requestDetails.requestId}`);
  let index = pendingRequests.indexOf(requestDetails.requestId);
  if (index > -1) {
    pendingRequests.splice(index, 1);
  }
}

function provideCredentialsAsync(requestDetails) {
  // If we have seen this request before,
  // then assume our credentials were bad,
  // and give up.
  if (pendingRequests.includes(requestDetails.requestId)) {
    console.log(`bad credentials for: ${requestDetails.requestId}`);
    return { cancel: true };
  } else {
    pendingRequests.push(requestDetails.requestId);
    console.log(`providing credentials for: ${requestDetails.requestId}`);
    // we can return a promise that will be resolved
    // with the stored credentials
    return browser.storage.local.get(null);
  }
}

browser.webRequest.onAuthRequired.addListener(
  provideCredentialsAsync,
  { urls: [target] },
  ["blocking"],
);

browser.webRequest.onCompleted.addListener(completed, { urls: [target] });

browser.webRequest.onErrorOccurred.addListener(completed, { urls: [target] });

{{WebExtExamples}} 

Browser compatibility

{{Compat}} 

[!NOTE] This API is based on Chromium’s chrome.webRequest API. This documentation is derived from web_request.json in the Chromium code.

In this article

View on MDN