webRequest.onAuthRequired

In Firefox- und Chrome Manifest V2-Erweiterungen müssen Sie die "webRequest" und "webRequestBlocking" API-Berechtigungen zu Ihrer manifest.json hinzufügen.

Für Manifest V3-Erweiterungen unterstützt Chrome die Berechtigung "webRequestBlocking" nicht mehr (außer für policy-installierte Erweiterungen). Stattdessen ermöglichen die Berechtigungen "webRequest" und "webRequestAuthProvider", dass Sie Anmeldeinformationen asynchron bereitstellen können. Firefox unterstützt weiterhin "webRequestBlocking" in Manifest V3 und bietet "webRequestAuthProvider" für die plattformübergreifende Kompatibilität an.

Firefox löst im Allgemeinen keine webRequest-Ereignisse für Systemanfragen aus, wie z. B. Browser- oder Erweiterungsaktualisierungen oder Suchmaschinenanfragen. Um sicherzustellen, dass die Proxy-Authentifizierung reibungslos für Systemanfragen funktioniert, unterstützt Firefox ab Version 57 eine Ausnahme hiervon.

Wenn eine Erweiterung die Berechtigungen "webRequest", "webRequestBlocking", "proxy" und "<all_urls>" hat, kann sie onAuthRequired verwenden, um Anmeldeinformationen für die Proxy-Authentifizierung bereitzustellen (aber nicht für die normale Web-Authentifizierung). Der Listener kann Systemanfragen nicht abbrechen oder andere Änderungen an Systemanfragen vornehmen.

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

Ereignisse haben drei Funktionen:

addListener(listener, filter, extraInfoSpec)

Fügt diesem Ereignis einen Listener hinzu.

removeListener(listener)

Stoppt das Zuhören dieses Ereignisses. Das listener-Argument ist der zu entfernende Listener.

hasListener(listener)

Überprüft, ob listener für dieses Ereignis registriert ist. Gibt true zurück, wenn es zuhört, andernfalls false.

listener

Die Funktion, die aufgerufen wird, wenn dieses Ereignis eintritt. Die Funktion erhält diese Argumente:

details

object. Details zur Anfrage. Weitere Informationen finden Sie im Abschnitt details.

asyncCallback Optional

Eine Funktion, die höchstens einmal aufgerufen wird, um das Anfrageobjekt asynchron zu ändern. Dieser Parameter ist nur vorhanden, wenn der Ereignis-Listener mit "asyncBlocking" im extraInfoSpec-Array registriert ist. asyncCallback ist undefiniert, wenn extraInfoSpec nicht bereitgestellt wird oder "blocking" enthält.

Rückgabe: webRequest.BlockingResponse oder ein Promise abhängig von den Einstellungen in extraInfoSpec.

filter

webRequest.RequestFilter. Ein Filter, der die an diesen Listener gesendeten Ereignisse einschränkt.

extraInfoSpec Optional

array of string. Zusätzliche Optionen für das Ereignis. Sie können einen dieser Werte übergeben:

• "blocking": lässt die Anfrage blockieren, sodass Sie die Anfrage abbrechen oder Authentifizierungsnachweise bereitstellen können. Geben Sie ein BlockingResponse-Objekt mit seinen cancel- oder authCredentials-Eigenschaften zurück.

  • In Chrome muss der Ereignis-Listener synchron antworten.
  • In Firefox kann der Ereignis-Listener synchron antworten oder ein Promise zurückgeben, das zu einem BlockingResponse-Objekt aufgelöst wird, um asynchron zu antworten.

• "asyncBlocking": Bearbeiten Sie die Anfrage asynchron. Der Rückgabewert des Ereignis-Listeners wird ignoriert. Um das Ereignis zu lösen, übergeben Sie dem asyncCallback-Parameter ein BlockingResponse-Objekt.

  • Wird ab Chrome 120 und Firefox 128 unterstützt.
  • Nicht in Safari unterstützt.

challenger

object. Der Server, der die Authentifizierung anfordert. Dies ist ein Objekt mit den folgenden Eigenschaften:

host

string. Der Hostname des Servers.

port

integer. Die Portnummer des Servers.

cookieStoreId

string. Wenn die Anfrage von einem Tab mit geöffnetem kontextuellem Identitätsfenster stammt, die ID des Cookie-Speichers der kontextuellen Identität. Weitere Informationen finden Sie unter Arbeiten mit kontextuellen Identitäten.

frameId

integer. Dies ist 0, wenn die Anfrage im Hauptframe erfolgt; ein positiver Wert ist die ID eines Unterrahmens, in dem die Anfrage erfolgt. Wenn das Dokument eines (Unter-)Frames geladen wird (type ist main_frame oder sub_frame), zeigt frameId die ID dieses Frames an, nicht die ID des äußeren Frames. Frame-IDs sind eindeutig innerhalb eines Tabs.

incognito

boolean. Ob die Anfrage aus einem privaten Browserfenster stammt.

isProxy

boolean. true für Proxy-Authenticate, false für WWW-Authenticate.

Hinweis: webRequest.onAuthRequired wird nur für HTTP- und HTTPS/TLS-Proxyserver aufgerufen, die eine Authentifizierung erfordern, nicht für SOCKS-Proxyserver, die eine Authentifizierung erfordern.

method

string. Standard-HTTP-Methode (z. B. "GET" oder "POST").

parentFrameId

integer. ID des Frames, der den Frame enthält, der die Anfrage gesendet hat. Ist auf -1 gesetzt, wenn kein übergeordneter Frame vorhanden ist.

proxyInfo

object. Diese Eigenschaft ist nur vorhanden, wenn die Anfrage über einen Proxy geleitet wird. Sie enthält die folgenden Eigenschaften:

host

string. Der Hostname des Proxyservers.

port

integer. Die Portnummer des Proxyservers.

type

string. Der Typ des Proxyservers. Einer von:

• "http": HTTP-Proxy (oder SSL CONNECT für HTTPS)
• "https": HTTP-Proxydienste über TLS-Verbindung zum Proxy
• "socks": SOCKS v5-Proxy
• "socks4": SOCKS v4-Proxy
• "direct": kein Proxy
• "unknown": unbekannter Proxy

username

string. Benutzername für den Proxydienst.

proxyDNS

boolean. Wahr, wenn der Proxy die DNS-Auflösung basierend auf dem bereitgestellten Hostnamen durchführt, was bedeutet, dass der Client keine eigene DNS-Suche durchführen sollte.

failoverTimeout

integer. Failover-Zeitüberschreitung in Sekunden. Wenn die Verbindung zum Proxyserver nach dieser Anzahl von Sekunden fehlschlägt, wird der nächste Proxyserver im Array verwendet, das von FindProxyForURL() zurückgegeben wird.

realm Optional

string. Der vom Server bereitgestellte Authentifizierungs-Domain, falls vorhanden.

requestId

string. Die ID der Anfrage. Anfragen-IDs sind innerhalb einer Browsersitzung eindeutig, sodass Sie verschiedene Ereignisse miteinander in Verbindung bringen können, die mit der gleichen Anfrage zusammenhängen.

responseHeaders Optional

webRequest.HttpHeaders. Die HTTP-Response-Header, die mit dieser Antwort erhalten wurden.

scheme

string. Das Authentifizierungsschema: "basic" oder "digest".

statusCode

integer. Standard-HTTP-Statuscode, der vom Server zurückgegeben wird.

statusLine

string. HTTP-Statuszeile der Antwort, die 'HTTP/0.9 200 OK'-Zeichenkette für HTTP/0.9-Antworten (d.h. Antworten ohne Statuszeile) oder eine leere Zeichenkette, wenn keine Header vorhanden sind.

tabId

integer. ID des Tabs, in dem die Anfrage stattfindet. Ist auf -1 gesetzt, wenn die Anfrage nicht mit einem Tab zusammenhängt.

thirdParty

boolean. Gibt an, ob die Anfrage und ihre Inhaltsfenster-Hierarchie von Dritten stammen.

timeStamp

number. Die Zeit, zu der dieses Ereignis ausgelöst wurde, in Millisekunden seit dem Unix-Epoch.

type

webRequest.ResourceType. Der Typ der angeforderten Ressource: zum Beispiel "image", "script" oder "stylesheet".

url

string. Ziel der Anfrage.

urlClassification

object. Die Art der Verfolgung, die mit der Anfrage in Verbindung steht, wenn die Anfrage von Firefox Tracking Protection klassifiziert wird. Dies ist ein Objekt mit diesen Eigenschaften:

firstParty

array von string. Klassifikationsmarkierungen für die First Party der Anfrage.

thirdParty

array von string. Klassifikationsmarkierungen für die Anfrage oder ihre Fensterhierarchie von Dritten.

Die Klassifikationsmarkierungen enthalten:

• fingerprinting und fingerprinting_content: zeigt an, dass die Anfrage an Fingerprinting beteiligt ist ("ein Ursprung, der zur Fingerabdruck-Erkennung eingesetzt wird").
  • fingerprinting zeigt an, dass die Domain in der Kategorie Fingerabdruck und Tracking ist. Beispiele für diese Art von Domain sind Werbetreibende, die ein Profil mit dem besuchenden Benutzer in Verbindung bringen möchten.
  • fingerprinting_content zeigt an, dass die Domain in der Kategorie Fingerabdruck, aber nicht in der Kategorie Tracking ist. Beispiele für diese Art von Domain sind Zahlungsanbieter, die Fingerabdrucktechniken verwenden, um den besuchenden Benutzer zum Zwecke des Betrugsschutzes zu identifizieren.
• cryptomining und cryptomining_content: ähnlich der Fingerabdruck-Kategorie, aber für Kryptomining-Ressourcen.
• tracking, tracking_ad, tracking_analytics, tracking_social und tracking_content: zeigt an, dass die Anfrage an Tracking beteiligt ist. tracking ist jede allgemeine Tracking-Anfrage. Die Suffixe ad, analytics, social und content identifizieren die Art des Trackers.
• emailtracking und emailtracking_content: zeigt an, dass die Anfrage an der E-Mail-Nachverfolgung beteiligt ist.
• any_basic_tracking: ein Meta-Flag, das Tracking- und Fingerabdruck-Markierungen kombiniert, ohne tracking_content und fingerprinting_content.
• any_strict_tracking: ein Meta-Flag, das alle Tracking- und Fingerabdruck-Markierungen kombiniert.
• any_social_tracking: ein Meta-Flag, das alle sozialen Tracking-Markierungen kombiniert.

Weitere Informationen zu Trackertypen finden Sie auf der disconnect.me Website. Das content-Suffix zeigt Tracker an, die Content verfolgen und bereitstellen. Ihre Blockierung schützt Benutzer, kann jedoch dazu führen, dass Websites kaputtgehen oder Elemente nicht angezeigt werden.

Dieser Code beobachtet Authentifizierungsanfragen für die Ziel-URL:

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

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

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

Dieser Code bricht Authentifizierungsanfragen für die Ziel-URL ab:

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",
]);

Dieser Code liefert Anmeldeinformationen synchron. Er verfolgt ausstehende Anfragen, um sicherzustellen, dass er nicht wiederholt versucht, falsche Anmeldeinformationen zu übermitteln:

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] });

Dieser Code liefert Anmeldeinformationen asynchron, indem er sie aus dem Speicher abruft. Er verfolgt ebenfalls ausstehende Anfragen, um sicherzustellen, dass er nicht wiederholt versucht, falsche Anmeldeinformationen zu übermitteln:

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 };
  }
  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] });

• stored-credentials