API доступа к хранилищу

Блокировка сторонних файлов cookie браузерами, пользовательскими настройками и разделением хранилища создает проблему для сайтов и сервисов, которые используют файлы cookie и другие хранилища во встроенных контекстах для таких действий пользователя, как аутентификация. API доступа к хранилищу (SAA) позволяет этим сценариям продолжать работу, максимально ограничивая межсайтовое отслеживание.

Статус реализации

API доступа к хранилищу доступен во всех основных браузерах , но в разных браузерах существуют небольшие различия в реализации . Эти различия подробно описаны в соответствующих разделах этой статьи.

Продолжается работа по устранению всех оставшихся проблем с блокировкой перед стандартизацией API .

Что такое API доступа к хранилищу?

Storage Access API — это API JavaScript, который позволяет iframe-ам запрашивать разрешения на доступ к хранилищу, если в противном случае доступ был бы запрещён настройками браузера. Встраиваемые приложения, сценарии использования которых зависят от загрузки межсайтовых ресурсов, могут использовать этот API для запроса разрешения на доступ у пользователя по мере необходимости.

Если запрос на хранилище будет удовлетворен, то iframe получит доступ к своим неразделенным cookie-файлам и хранилищу, которые также доступны, когда пользователи посещают его как сайт верхнего уровня.

API доступа к хранилищу позволяет предоставлять определенный неразделенный доступ к файлам cookie и хранилищу с минимальной нагрузкой на конечного пользователя, в то же время предотвращая общий неразделенный доступ к файлам cookie и хранилищу, который часто используется для отслеживания пользователей.

Варианты использования

Некоторым сторонним встроенным функциям требуется доступ к нераспределенным файлам cookie или хранилищу для предоставления пользователю более удобного интерфейса — эта возможность будет недоступна, если сторонние файлы cookie ограничены и включено разделение хранилища.

Варианты использования включают в себя:

• Встроенные виджеты комментирования, требующие данные сеанса входа.
• Кнопки «Нравится» в социальных сетях, требующие данные сеанса входа в систему.
• Встроенные документы, требующие данных сеанса входа в систему.
• Премиум-возможности, предоставляемые при встраивании видео (например, чтобы не показывать рекламу вошедшим в систему пользователям, или чтобы знать предпочтения пользователя в отношении субтитров, или чтобы ограничить определенные типы видео).
• Встроенные платежные системы.

Многие из этих вариантов использования подразумевают сохранение доступа к учетной записи во встроенных фреймах.

Когда следует использовать API доступа к хранилищу вместо других API

API доступа к хранилищу — одна из альтернатив использованию неразделённых файлов cookie и хранилища, поэтому важно понимать, когда следует использовать этот API по сравнению с другими. Он предназначен для случаев, когда выполняются оба следующих условия:

• Пользователь будет взаимодействовать со встроенным содержимым, то есть это не пассивный iframe или скрытый iframe.
• Пользователь посетил встроенный источник в контексте верхнего уровня, то есть когда этот источник не встроен в другой сайт.

Существуют альтернативные API для различных вариантов использования:

• Файлы cookie с независимым разделением (CHIPS) позволяют разработчикам использовать cookie для «разделенного» хранения, создавая отдельный файл cookie для каждого сайта верхнего уровня. Например, сторонний виджет веб-чата может использовать файл cookie для сохранения информации о сеансе. Информация о сеансе сохраняется для каждого сайта, поэтому к файлу cookie, установленному виджетом, не требуется доступ на других веб-сайтах, где он также встроен. API доступа к хранилищу полезен, когда встроенный сторонний виджет зависит от обмена одной и той же информацией между разными источниками (например, для информации о сеансе входа или настроек).
• Разделение хранилища — это способ, позволяющий межсайтовым iframe использовать существующие механизмы хранения JavaScript, разделяя при этом хранилище по каждому сайту. Это предотвращает доступ к встроенному хранилищу одного сайта с других сайтов.
• Наборы связанных веб-сайтов (RWS) — это способ организации декларировать связи между сайтами, чтобы браузеры предоставляли ограниченный неразделенный доступ к файлам cookie и хранилищу для определенных целей. Сайтам по-прежнему необходимо запрашивать доступ через API доступа к хранилищу, но для сайтов, входящих в набор, доступ может быть предоставлен без запроса пользователя.
• Управление федеративными учётными данными (FedCM) — это подход к федеративным службам идентификации, сохраняющий конфиденциальность. API доступа к хранилищу обеспечивает доступ к неразделённым файлам cookie и хранилищу после входа в систему. В некоторых случаях FedCM предоставляет альтернативное решение API доступа к хранилищу и может быть предпочтительнее, поскольку оно предлагает более ориентированный на вход в систему интерфейс браузера. Однако внедрение FedCM обычно требует дополнительных изменений в коде, например, для поддержки конечных точек HTTP.
• Существуют также API для борьбы с мошенничеством , рекламы и измерений , но API доступа к хранилищу не предназначен для решения этих проблем.

Используйте API доступа к хранилищу

В API доступа к хранилищу есть два метода на основе обещаний:

• Document.hasStorageAccess() (также доступно под новым именем Document.hasUnpartitionedCookieAccess() начиная с Chrome 125)
• Document.requestStorageAccess()

Он также интегрируется с API разрешений . Это позволяет проверять статус разрешения на доступ к хранилищу в стороннем контексте, что позволяет определить, будет ли автоматически предоставлен вызов document.requestStorageAccess() :

• navigator.permissions.query({name: "storage-access"});

Используйте метод hasStorageAccess()

При первой загрузке сайта он может использовать метод hasStorageAccess() для проверки того, был ли уже предоставлен доступ к сторонним cookie-файлам.

// Set a hasAccess boolean variable which defaults to false.
let hasAccess = false;

async function handleCookieAccessInit() {
  if (!document.hasStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    hasAccess = true;
  } else {
    // Check whether access has been granted using the Storage Access API.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

API доступа к хранилищу предоставляет доступ к хранилищу документа iframe только после вызова requestStorageAccess(), поэтому hasStorageAccess() может изначально возвращать false, например, если пользователь по умолчанию блокирует сторонние файлы cookie. (Однако настройки пользователя, специфичные для сайта, также могут разрешать доступ к файлам cookie на определенном сайте, даже если пользователь по умолчанию блокирует сторонние файлы cookie.) Доступ к хранилищу с использованием этого API сохраняется при навигации по одному источнику внутри iframe, в частности, чтобы разрешить перезагрузку после предоставления доступа для страниц, которым требуется наличие файлов cookie в первоначальном запросе HTML-документа.

Использовать requestStorageAccess()

Если у iframe нет доступа, возможно, потребуется запросить доступ с помощью метода requestStorageAccess() :

if (!hasAccess) {
  try {
    await document.requestStorageAccess();
  } catch (err) {
    // Access was not granted and it may be gated behind an interaction
    return;
  }
}

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

Во избежание злоупотреблений это приглашение браузера будет отображаться только после взаимодействия с пользователем. Именно поэтому requestStorageAccess() необходимо изначально вызывать из обработчика событий, активируемого пользователем, а не сразу при загрузке iframe:

async function doClick() {

  // Only do this extra check if access hasn't already been given
  // based on the hasAccess variable.
  if (!hasAccess) {
    try {
      await document.requestStorageAccess();
      hasAccess = true; // Can assume this was true if requestStorageAccess() did not reject.
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  if (hasAccess) {
    // Use the cookies
  }
}

document.querySelector('#my-button').addEventListener('click', doClick);

Запросы на разрешение

Когда пользователь нажимает кнопку в первый раз, в большинстве случаев автоматически появляется приглашение браузера, обычно в адресной строке. На следующем снимке экрана показан пример приглашения Chrome, но и другие браузеры имеют похожий интерфейс:

При определенных обстоятельствах браузер может пропустить запрос, и разрешение может быть предоставлено автоматически:

• Если страница и iframe использовались в течение последних 30 дней после принятия приглашения.
• Если встроенный iframe является частью набора связанных веб-сайтов .
• Если FedCM используется как сигнал доверия для доступа к хранилищу.
• В Firefox запрос также пропускается для известных веб-сайтов (тех, с которыми вы взаимодействовали на верхнем уровне) в течение первых пяти попыток.

Кроме того, метод может быть автоматически отклонен без отображения подсказки при определенных обстоятельствах:

• Если пользователь ранее не посещал сайт, которому принадлежит iframe, и не взаимодействовал с ним как с документом верхнего уровня, а не в iframe. Это означает, что API доступа к хранилищу полезен только для встроенных сайтов, которые пользователи ранее посещали в контексте «основной страницы».
• Если метод requestStorageAccess() вызывается вне события взаимодействия с пользователем без предварительного одобрения запроса после взаимодействия.

Хотя при первом использовании пользователю будет выдан запрос, последующие запросы requestStorageAccess() могут быть выполнены без запроса и без взаимодействия с пользователем в Chrome и Firefox. Обратите внимание, что в Safari взаимодействие с пользователем всегда требуется.

Поскольку доступ к файлам cookie и хранилищу может предоставляться без запроса или взаимодействия с пользователем, в браузерах, которые поддерживают эту функцию (Chrome и Firefox), часто можно получить доступ к нераспределенным файлам cookie или хранилищу до взаимодействия с пользователем, вызвав requestStorageAccess() при загрузке страницы. Это может позволить вам получить немедленный доступ к нераспределенным файлам cookie и хранилищу и обеспечить более полный интерфейс, даже до того, как пользователь взаимодействует с iframe. В некоторых ситуациях это может быть удобнее, чем ожидание взаимодействия с пользователем.

FedCM как сигнал доверия для SAA

FedCM (федеративное управление учетными данными) — это сохраняющий конфиденциальность подход к федеративным службам идентификации (например, «Войти с помощью...»), который не использует сторонние файлы cookie или навигационные перенаправления.

Когда пользователь входит в систему проверяющей стороны (RP), содержащей встроенный контент от стороннего поставщика удостоверений (IdP) с помощью FedCM, встроенный контент IdP может автоматически получить доступ к хранилищу своих собственных неразделённых файлов cookie верхнего уровня. Для включения автоматического доступа к хранилищу с помощью FedCM должны быть выполнены следующие условия:

• Аутентификация FedCM (состояние входа пользователя) должна быть активна.
• RP дал свое согласие, установив разрешение identity-credentials-get , например:

<iframe src="https://idp.example" allow="identity-credentials-get"></iframe>

Например, iframe idp.example встроен в rp.example . Когда пользователь входит в систему через FedCM, iframe idp.example может запросить доступ к хранилищу для своих собственных файлов cookie верхнего уровня.

rp.example выполняет вызов FedCM для регистрации пользователя с помощью поставщика удостоверений idp.example :

// The user will be asked to grant FedCM permission.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
});

После входа пользователя в систему поставщик удостоверений может вызвать метод requestStorageAccess() из iframe idp.example , если поставщик удостоверений явно разрешил это в политике разрешений . Встроенному приложению будет автоматически предоставлен доступ к хранилищу его собственного cookie-файла верхнего уровня без активации пользователем или необходимости запроса дополнительного разрешения :

// Make this call within the embedded IdP iframe:

// No user gesture is needed, and the storage access will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

Разрешение будет предоставлено автоматически только при условии, что пользователь вошел в систему FedCM. После деактивации аутентификации для предоставления доступа к хранилищу применяются стандартные требования SAA .

API доступа к хранилищу для хранения данных без файлов cookie

Вы можете запросить доступ к неразмеченному локальному хранилищу, передав параметр types в вызов requestStorageAccess . Например, чтобы запросить доступ к неразмеченному локальному хранилищу, можно вызвать requestStorageAccess({localStorage: true}) .

Если сторонние файлы cookie включены, этот метод предоставит доступ без активации пользователя или запроса разрешения. Если пользователь отключил сторонние файлы cookie, перед предоставлением доступа к хранилищу потребуется запросить разрешение.

Сначала проверьте, имеет ли браузер уже доступ к хранилищу:

async function hasCookieAccess(){
  // Check if Storage Access API is supported
  if (!document.requestStorageAccess) {
    // Storage Access API is not supported, so we assume it's an older browser that doesn't partition storage.
    throw new Error("requestStorageAccess is not supported")
  }

  // Check if access has already been granted or if the user has 3-party cookies enabled
  return document.hasStorageAccess();
}

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

// Request storage access and return the storage handle
async function requestStorageHandle(){
// You can request for multiple types of non-cookie storage
// at once, or request for all of them with all:true
return document.requestStorageAccess({all:true});
}

Если сторонние файлы cookie заблокированы (например, в режиме инкогнито), проверьте разрешения на выполнение запросов, чтобы определить, требуется ли запрос пользователя. Состояние разрешения navigator.permissions.query({name: 'storage-access'}) может иметь следующие значения:

• granted . Пользователь уже предоставил доступ. Вызовите requestStorageAccess , чтобы получить доступ к неразмеченному хранилищу без необходимости дополнительного запроса пользователя.
• prompt . Пользователь ещё не предоставил доступ. Установите прослушиватель кликов и вызовите requestStorageAccess ещё раз после взаимодействия с пользователем.
• error . Разрешение не поддерживается. Если поддерживается API доступа к хранилищу, это разрешение, вероятно, также поддерживается.

// Returns `granted`, or `prompt`; or throws an error if storage-access
// permission is not supported
async function getStorageAccessPermission(){
  // Check the storage-access permission
  // Wrap this in a try/catch for browsers that support the
  // Storage Access API but not this permission check
    return navigator.permissions.query({name: 'storage-access'});
}

Полный поток обработки разделов хранилища, не относящихся к cookie-файлам, можно реализовать следующим образом:

async function getStorageHandle() {
    // Check if the user has 3-party cookie access
    if (await hasCookieAccess()) {
    // If the user has access, requestStorageAccess() will resolve automatically
        return requestStorageHandle();
    }

    // If the browser blocks third party cookies, check if the user has
    // accepted the prompt and granted access. If they have,
    // requestStorageAccess() will resolve automatically
    const permission = await getStorageAccessPermission();
    if (permission == 'granted') { // User has seen prompt and granted access
        return requestStorageHandle();
    }

    // Wait for user activation to prompt the user again
    // (or put your silent failure logic here instead)
    return new Promise((resolve, reject) => {
        document.querySelector('#myButton').addEventListener(e => {
            requestStorageHandle().then(resolve, reject);
        })
    })
}

// Use your storage
getStorageHandle().then(handle=>{
    handle.indexedDB.open(...);
}).catch(() => {
    // If the promise is rejected, you can use regular partitioned storage
    indexedDB.open(...);
})

Последующая загрузка с заголовками доступа к хранилищу

Заголовки доступа к хранилищу — рекомендуемый и более производительный способ загрузки встроенного контента, включая ресурсы, не входящие в iframe. Эта функция доступна с Chrome версии 133. Благодаря заголовкам доступа к хранилищу браузер может распознавать, когда пользователь уже предоставил разрешение storage-access стороннему источнику в текущем контексте, и может загружать ресурсы с доступом к нераспределенным файлам cookie при последующих посещениях.

Поток заголовков доступа к хранилищу

При использовании заголовков доступа к хранилищу последующие посещения страниц будут инициировать следующий поток:

1. Пользователь ранее посетил website.example , в который встроен ресурс calendar.example , и предоставил storage-access с помощью вызова document.requestStorageAccess() .
2. Пользователь снова посещает website.example , в который встроен ресурс calendar.example . Этот запрос, как и раньше, пока не имеет доступа к cookie. Однако пользователь ранее предоставил разрешение storage-access , и запрос включает заголовок Sec-Fetch-Storage-Access: inactive , указывающий на то, что доступ к неразделённым cookie возможен, но не активирован.
3. Сервер calendar.example отвечает заголовком Activate-Storage-Access: retry; allowed-origin='<origin>' (в этом случае <origin> будет https://website.example ), чтобы указать, что для извлечения ресурса требуется использование неразделенных файлов cookie с разрешением storage-access .
4. Браузер повторяет запрос, на этот раз включая неразделенные файлы cookie (активируя разрешение storage-access для этой выборки и последующих выборок).
5. Сервер calendar.example отвечает персонализированным содержимым iframe. Ответ включает заголовок Activate-Storage-Access: load , указывающий, что браузер должен загрузить содержимое с активированным разрешением storage-access (то есть загрузить с неразделённым доступом к cookie, как если бы был вызван document.requestStorageAccess() ).
6. Пользовательский агент загружает содержимое iframe с неразделённым доступом к cookie, используя разрешение storage-access . После этого виджет может работать как и ожидалось.

Использовать заголовки доступа к хранилищу

В следующей таблице перечислены заголовки доступа к хранилищу.

Например, заголовки доступа к хранилищу можно использовать для загрузки изображения из стороннего источника:

  // On the client side
  <img src="https://server.example/image">

В этом случае server.example должен реализовать следующую логику на стороне сервера:

  app.get('/image', (req, res) => {
  const storageAccessHeader = req.headers['sec-fetch-storage-access'];

  if (storageAccessHeader === 'inactive') {
    // The user needs to grant permission, trigger a prompt

    // Check if the requesting origin is allowed
    // to send credentialed requests to this server.
    // Assuming the `validate_origin(origin)` method is previously defined:
    if (!validate_origin(req.headers.origin)) {
      res.status(401).send(req.headers.origin +
        ' is not allowed to send credentialed requests to this server.');
      return;
    }
    // 'retry' header value indicates that the content load request should be re-sent after the user has granted permissions
    res.set('Activate-Storage-Access', `retry; allowed-origin='${req.headers.origin}'`);
    res.status(401).send('This resource requires storage access. Please grant permission.');
  } else if (storageAccessHeader === 'active') {
    // User has granted permission, proceed with access
    res.set('Activate-Storage-Access', 'load');
    // Include the actual iframe content here
    res.send('This is the content that requires cookie access.');
  } else {
    // Handle other cases (e.g., 'Sec-Fetch-Storage-Access': 'none')
  }
});

Демонстрационная версия API доступа к хранилищу встраивает сторонний контент (включая изображения, не являющиеся iframe) с помощью заголовков доступа к хранилищу.

Используйте запрос на разрешение storage-access

Чтобы проверить, можно ли предоставить доступ без взаимодействия с пользователем, можно проверить статус разрешения storage-access и вызывать requestStoreAccess() заранее только в том случае, если никаких действий от пользователя не требуется, а не вызывать его и допускать сбой, когда требуется взаимодействие.

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

Следующий код добавляет проверку разрешения storage-access к предыдущему примеру:

// Set a hasAccess boolean variable which defaults to false except for
// browsers which don't support the API - where we assume
// such browsers also don't block third-party cookies.
let hasAccess = false;

async function hasCookieAccess() {
  // Check if Storage Access API is supported
  if (!document.requestStorageAccess) {
    // Storage Access API is not supported so best we can do is
    // hope it's an older browser that doesn't block 3P cookies.
    return true;
  }

  // Check if access has already been granted
  if (await document.hasStorageAccess()) {
    return true;
  }

  // Check the storage-access permission
  // Wrap this in a try/catch for browsers that support the
  // Storage Access API but not this permission check
  // (e.g. Safari and earlier versions of Firefox).
  let permission;
  try {
    permission = await navigator.permissions.query(
      {name: 'storage-access'}
    );
  } catch (error) {
    // storage-access permission not supported. Assume no cookie access.
    return false;
  }

    if (permission) {
    if (permission.state === 'granted') {
      // Permission has previously been granted so can just call
      // requestStorageAccess() without a user interaction and
      // it will resolve automatically.
      try {
        await document.requestStorageAccess();
        return true;
      } catch (error) {
        // This shouldn't really fail if access is granted, but return false
        // if it does.
        return false;
      }
    } else if (permission.state === 'prompt') {
      // Need to call requestStorageAccess() after a user interaction
      // (potentially with a prompt). Can't do anything further here,
      // so handle this in the click handler.
      return false;
          } else if (permission.state === 'denied') {
            // Not used: see https://github.com/privacycg/storage-access/issues/149
      return false;
          }
    }

  // By default return false, though should really be caught by earlier tests.
  return false;
}

async function handleCookieAccessInit() {
  hasAccess = await hasCookieAccess();

  if (hasAccess) {
    // Use the cookies.
  }
}

handleCookieAccessInit();

Изолированные фреймы

При использовании API доступа к хранилищу в изолированных iframes требуются следующие разрешения для изолированной среды:

• Для разрешения доступа к API доступа к хранилищу требуется allow-storage-access-by-user-activation .
• allow-scripts требуется, чтобы разрешить использование JavaScript для вызова API.
• allow-same-origin требуется для разрешения доступа к файлам cookie и другим хранилищам того же происхождения.

Например:

<iframe sandbox="allow-storage-access-by-user-activation
                 allow-scripts
                 allow-same-origin"
        src="..."></iframe>

Требования к файлам cookie

Для доступа с помощью API доступа к хранилищу в Chrome необходимо установить межсайтовые файлы cookie со следующими двумя атрибутами:

• SameSite=None — требуется, чтобы отметить cookie-файл как межсайтовый.
• Secure — обеспечивает доступ только к файлам cookie, установленным сайтами HTTPS.

В Firefox и Safari для файлов cookie по умолчанию установлено значение SameSite=None , и SAA не ограничивается только Secure файлами cookie, поэтому эти атрибуты не требуются. Рекомендуется явно указывать атрибут SameSite и всегда использовать Secure файлы cookie.

Доступ к странице верхнего уровня

API доступа к хранилищу предназначен для обеспечения доступа к сторонним cookie-файлам во встроенных фреймах.

Существуют и другие случаи, когда странице верхнего уровня требуется доступ к сторонним файлам cookie. Например, изображения или скрипты, доступ к которым ограничен файлами cookie, могут быть включены владельцами сайтов непосредственно в документ верхнего уровня, а не в iframe. Для решения этой проблемы Chrome предложил расширение API доступа к хранилищу , добавляющее метод requestStorageAccessFor() .

Метод requestStorageAccessFor()

Метод requestStorageAccessFor() работает аналогично requestStorageAccess() , но для ресурсов верхнего уровня. Его можно использовать только для сайтов из группы Related Website Set , чтобы предотвратить предоставление общего доступа сторонним файлам cookie.

Более подробную информацию об использовании requestStorageAccessFor() можно найти в руководстве разработчика Related Website Sets :.

Запрос на разрешение top-level-storage-access

Подобно разрешению storage-access , существует разрешение top-level-storage-access для проверки возможности предоставления доступа для requestStorageAccessFor() .

Чем отличается API доступа к хранилищу при использовании с RWS?

При использовании связанных наборов веб-сайтов с API доступа к хранилищу становятся доступны некоторые дополнительные возможности, подробно описанные в следующей таблице:

Демонстрация: настройка и доступ к файлам cookie

В следующей демонстрации показано, как можно получить доступ к cookie-файлу, установленному вами на первом экране демонстрации, во встроенном фрейме на втором сайте демонстрации:

storage-access-api-demo.glitch.me

Для демонстрации требуется браузер с отключенными сторонними файлами cookie:

• Chrome 118 или выше с установленным флагом chrome://flags/#test-third-party-cookie-phaseout и перезапущенным браузером.
• Firefox
• Сафари

Демонстрация: настройка локального хранилища

В следующей демонстрации показано, как получить доступ к неразделенным каналам вещания из стороннего iframe с помощью API доступа к хранилищу:

https://saa-beyond-cookies.glitch.me/

Для демонстрации требуется Chrome 125 или выше с включенным флагом test-third-party-cookie-phaseout .

Ресурсы

• Ознакомьтесь со спецификацией , предоставляющей доступ к сторонним файлам cookie, или перейдите по ссылке и поднимите вопрос .
• Ознакомьтесь со спецификацией , предоставляющей неразделенный доступ к хранилищу, или следуйте ей и поднимайте вопросы .
• Документация и руководство по API.
• Документация Chrome по использованию API доступа к хранилищу в связанных наборах веб-сайтов