webRequest.onAuthRequired

В общем случае Firefox не вызывает события webRequest для системных запросов, таких как обновления браузера или расширений, или запросы поисковых систем. Чтобы обеспечить бесперебойную работу авторизации прокси-сервера для системных запросов, с версии 57 Firefox реализует исключение из этого правила.

Если у расширения есть разрешения "webRequest", "webRequestBlocking", "proxy", и "<all_urls>", оно сможет использовать onAuthRequired для предоставления учетных данных для авторизации прокси-сервера (но не для обычной веб-авторизации). Обработчик не сможет отменять системные запросы или вносить какие-либо другие изменения в системные запросы.

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

События имеют три функции:

addListener(callback, filter, extraInfoSpec)

Добавляет обработчик на это событие.

removeListener(listener)

Остановить прослушивание этого события. Аргумент listener — это обработчик для удаления.

hasListener(listener)

Проверка, зарегистрирован ли listener для этого события. Возвращает true если прослушивание активное, false в противном случае.

callback

Функция, которая будет вызываться при возникновении этого события. Функция получит следующие аргументы:

details

object. Сведения о запросе. Смотрите раздел details для получения дополнительной информации.

Возвращает: webRequest.BlockingResponse или Promise.

• Для обработки запроса синхронно, включите "blocking" в параметр extraInfoSpec и верните объект BlockingResponse, с установленным свойством cancel или authCredentials
• Для обработки запроса асинхронно, включите "blocking" в параметр extraInfoSpec и верните Promise, который разрешается объектом BlockingResponse, с установленным свойством cancel или authCredentials

filter

webRequest.RequestFilter. Фильтр, ограничивающий события, которые будут отправлены в этот обработчик.

extraInfoSpec Необязательно

array string. Дополнительные параметры для события. Вы можете передать следующие значения:

• "blocking": заблокировать запрос, чтобы вы могли отменить запрос или предоставить учетные данные для аутентификации
• "responseHeaders": включить responseHeaders в объект details переданный обработчику

challenger

object. Сервер, запрашивающий аутентификацию. Это объект со следующими свойствами:

host

string. Имя хоста сервера.

port

integer. Номер порта сервера.

cookieStoreId

string. Если запрос поступает из вкладки, открытой в контекстной идентичности, идентификатор хранилища cookie контекстной идентичности.

frameId

integer. Это 0 если запрос происходит в основном фрейме; положительное значение — это идентификатор подфрейма, в котором происходит запрос. Если документ (под)фрейма загружен (type — main_frame или sub_frame), frameId указывает идентификатор этого фрейма, а не идентификатор внешнего фрейма. Идентификаторы фреймов уникальны в пределах вкладки.

incognito

boolean. Является ли запрос из окна приватного просмотра.

isProxy

boolean. true для Proxy-Authenticate, false для WWW-Authenticate.

Примечание: webRequest.onAuthRequired вызывается только для HTTP и HTTPS/SSL прокси-серверов, требующих аутентификации, и не для прокси-серверов SOCKS, требующих аутентификации.

method

string. Стандартный HTTP-метод (например, "GET" или "POST").

parentFrameId

integer. Идентификатор фрейма, содержащего фрейм, который отправил запрос. Установлено в -1 если родительский фрейм отсутствует.

proxyInfo

object. Это свойство присутствует только в случае проксирования запроса. Оно содержит следующие свойства:

host

string. Имя хоста прокси-сервера.

port

integer. Номер порта прокси-сервера.

type

string. Тип прокси-сервера. Один из:

• "http": HTTP-прокси (или SSL CONNECT для HTTPS)
• "https": HTTP-проксирование через TLS-соединение с прокси
• "socks": SOCKS v5 прокси
• "socks4": SOCKS v4 прокси
• "direct": без прокси
• "unknown": неизвестный прокси

username

string. Имя пользователя для службы прокси.

proxyDNS

boolean. Истинно, если прокси выполнит разрешение доменных имен на основе предоставленного имени хоста, что означает, что клиент не должен выполнять собственный поиск DNS.

failoverTimeout

integer. Время ожидания переключения в секундах. Если соединение не удается подключиться к прокси-серверу после этого количества секунд, будет использован следующий прокси-сервер из массива, возвращаемого функцией FindProxyForURL().

realm Опционально

string. Предоставленный сервером аутентификационный realm, если он есть.

requestId

string. Идентификатор запроса. Идентификаторы запросов уникальны в сессии браузера, поэтому их можно использовать для связывания различных событий, связанных с одним запросом.

responseHeaders Опционально

webRequest.HttpHeaders. HTTP-заголовки ответа, полученные вместе с этим ответом.

scheme

string. Схема аутентификации: "basic" или "digest".

statusCode

integer. Стандартный HTTP-код состояния, возвращаемый сервером.

statusLine

string. Строка состояния HTTP ответа или строка 'HTTP/0.9 200 OK' для ответов HTTP/0.9 (т.е. ответов, не содержащих строки состояния) или пустая строка, если заголовков нет.

tabId

integer. Идентификатор вкладки, в которой происходит запрос. Установлено в -1 если запрос не связан с вкладкой.

thirdParty

boolean. Указывает, является ли запрос и его иерархия окна сторонними.

timeStamp

number. Время срабатывания этого события в миллисекундах с момента эпохи.

type

webRequest.ResourceType. Тип запрашиваемого ресурса: например, "image", "script", "stylesheet".

url

string. Цель запроса.

urlClassification

object. Тип отслеживания, связанный с запросом, если запрос классифицирован функцией Защитой от отслеживания Firefox. Это объект со следующими свойствами:

firstParty

array strings. Флаги классификации для первой стороны запроса.

thirdParty

array strings. Флаги классификации для запроса или сторонних участников иерархии его окна.

Флаги классификации включают:

• fingerprinting и fingerprinting_content: указывает, что запрос участвует в определении личности. fingerprinting_content указывает, что запрос загружается из источника, который, как было установлено, определяет личность, но не считается участником отслеживания, например, поставщик платежных услуг.
• cryptomining и cryptomining_content: аналогично категории определения личности, но для ресурсов майнинга криптовалюты.
• tracking, tracking_ad, tracking_analytics, tracking_social, и tracking_content: указывает, что запрос участвует в отслеживании. tracking — любой общий запрос отслеживания, суффиксы ad, analytics, social, и content идентифицируют тип отслеживателя.
• any_basic_tracking: метафлаг, объединяющий все флаги отслеживания и определения личности, за исключением tracking_content и fingerprinting_content.
• any_strict_tracking: метафлаг, объединяющий все флаги отслеживания и определения личности, включая tracking_content и fingerprinting_content.
• any_social_tracking: метафлаг, объединяющий все флаги социального отслеживания.

Этот код просто наблюдает за запросами на аутентификацию для целевого URL:

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

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

browser.webRequest.onAuthRequired.addListener(
  observe,
  {urls: [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"]
);

Этот код предоставляет учетные данные синхронно. Он должен отслеживать ожидающие запросы, чтобы убедиться, что он не пытается повторно отправлять плохие учетные данные:

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

Этот код предоставляет учетные данные асинхронно, извлекая их из хранилища. Он также должен отслеживать ожидающие запросы, чтобы убедиться, что он не пытается повторно отправлять плохие учетные данные:

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

• stored-credentials