Эта страница переведена с помощью Cloud Translation API.

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

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

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

Browser Support

Source

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

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

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

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

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

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

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

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

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

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

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

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

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

Пользователь будет взаимодействовать со встроенным контентом, то есть это не пассивный или скрытый 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.
    // Note on page load this will always be false initially so we could be
    // skipped in this example, but including for completeness for when this
    // is not so obvious.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

Доступ к хранилищу предоставляется документу iframe только после того, как он вызывает requestStorageAccess(), поэтому hasStorageAccess() изначально всегда возвращает false — за исключением случаев, когда другому документу того же происхождения в том же iframe уже был предоставлен доступ. Предоставление сохраняется при навигации по тому же источнику внутри 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);

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

let handle = null;

async function doClick() {
  if (!handle) {
    try {
      handle = await document.requestStorageAccess({localStorage: true});
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  // Use handle to access unpartitioned local storage.
  handle.localStorage.setItem('foo', 'bar');
}

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

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

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

Запрос разрешения API доступа к хранилищу Chrome

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

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

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

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

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

Ключевой момент: даже если разрешение granted , оно не предоставляет автоматически всем фреймам доступ к неразделенным файлам cookie или хранилищу. Метод requestStorageAccess() по-прежнему должен вызываться при каждой загрузке страницы каждым кадром, для которого требуются неразделенные файлы cookie или доступ к хранилищу. Это гарантирует, что фрейм получает доступ к файлам cookie и хранилищу только тогда, когда они ему нужны, а не предоставляет доступ ко всем фреймам.

Поскольку доступ к файлам cookie и хранилищу может быть предоставлен без запроса или взаимодействия с пользователем, часто можно получить неразделенный доступ к файлам cookie или хранилищу до взаимодействия с пользователем в браузерах, которые это поддерживают (Chrome и Firefox), вызвав 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',
    }],
  },
});

После входа пользователя в систему IdP может вызвать requestStorageAccess() из iframe idp.example , если RP явно разрешил это с помощью Permissions Policy . Встроенному файлу будет автоматически предоставлен доступ к хранилищу его собственного файла 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 .

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

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

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

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

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

Блок-схема, иллюстрирующая поток заголовка доступа к хранилищу — Блок-схема заголовка доступа к хранилищу.

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

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

Поток	Заголовок	Ценить	Описание
Запрос	`Sec-Fetch-Storage-Access` Примечание. Браузер автоматически отправляет этот заголовок в межсайтовых запросах, включающих учетные данные (например, `new Request('request.example', { credentials: 'include' });` ).	`none`	У Embed нет разрешения на доступ к хранилищу.
		`inactive`	Внедрение имеет разрешение, но не использует его. Запрос также должен включать заголовок `Origin` .
		`active`	Embed имеет неразделенный доступ к файлам cookie.
Ответ	`Activate-Storage-Access`	`load`	Указывает браузеру предоставить разработчику доступ к неразделенным файлам cookie для запрошенного ресурса. Включение этого заголовка эквивалентно вызову `document.requestStorageAccess()` , если было предоставлено разрешение `storage-access` . Это означает, что пользователю не будет отображаться никаких дополнительных запросов.
	`Activate-Storage-Access`	`retry`	Указывает браузеру активировать разрешение на доступ к хранилищу, а затем повторить запрос.
	`allowed-origin`	`<origin>`	Указывает, какому источнику разрешено инициировать запросы с учетными данными (например, `https://site.example` или `*` ).

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

  // 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 поддерживается в Chrome и Firefox, но не в Safari. Для пользователей Safari всегда требуется взаимодействие с пользователем (за исключением особого случая перезагрузки страницы после предоставления доступа).

Следующий код добавляет проверку разрешений 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();

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

Изолированные iframe в песочнице

При использовании 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

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

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

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

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

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

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

Метод `requestStorageAccessFor()`

Browser Support

Source

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

Подробнее о том, как использовать requestStorageAccessFor() читайте в разделе «Наборы связанных веб-сайтов: руководство для разработчиков» .

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

Browser Support

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

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

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

	Без РВС	С РВС
Требуется жест пользователя, чтобы инициировать запрос на доступ к хранилищу.
Требуется, чтобы пользователь посетил запрошенное хранилище в контексте верхнего уровня, прежде чем предоставить доступ.
Запрос пользователя при первом посещении можно пропустить.
`requestStorageAccess` не требуется вызывать, если доступ был ранее предоставлен
Автоматически предоставляет доступ к другим доменам на связанном веб-сайте.
Поддерживает `requestStorageAccessFor` для доступа к страницам верхнего уровня.

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

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

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

хранилище-доступ-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 или более поздней версии с включенным флагом поэтапного отказа от сторонних файлов cookie .

Ресурсы

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

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

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

Browser Support

Source

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

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

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

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

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

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

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

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

Пользователь будет взаимодействовать со встроенным контентом, то есть это не пассивный или скрытый 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()

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

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

// 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.
    // Note on page load this will always be false initially so we could be
    // skipped in this example, but including for completeness for when this
    // is not so obvious.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

Используйте `requestStorageAccess()`

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

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

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

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

let handle = null;

async function doClick() {
  if (!handle) {
    try {
      handle = await document.requestStorageAccess({localStorage: true});
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  // Use handle to access unpartitioned local storage.
  handle.localStorage.setItem('foo', 'bar');
}

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

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

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

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

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

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

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

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

// 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();

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

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

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

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

Блок -схема, иллюстрирующая поток заголовка доступа — Диаграмма потока заголовка для хранения.

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

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

Поток	Заголовок	Ценить	Описание
Запрос	`Sec-Fetch-Storage-Access` ПРИМЕЧАНИЕ. Браузер автоматически отправляет этот заголовок в перекрестных запросах, которые включают учетные данные (например, `new Request('request.example', { credentials: 'include' });` ).	`none`	Embed не имеет разрешения на доступ к хранению.
		`inactive`	У Embed есть разрешение, но не использует его. Запрос также должен включать заголовок `Origin` .
		`active`	Enced имеет невозможный доступ Cookie.
Ответ	`Activate-Storage-Access`	`load`	Показал браузеру предоставить доступ к Embedder к невозможным файлам cookie для запрошенного ресурса. Включение этого заголовка эквивалентно вызова `document.requestStorageAccess()` если было предоставлено разрешение `storage-access` . Это означает, что никакой дополнительной подсказке не будет отображаться пользователю.
	`Activate-Storage-Access`	`retry`	Попросите браузера активировать разрешение на доступ к хранению, а затем повторить запрос.
	`allowed-origin`	`<origin>`	Указывает, какое происхождение разрешено инициировать запросы на учетные данные (например, `https://site.example` или `*` ).

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

  // 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 поддерживается в Chrome и Firefox, но не в сафари. Для пользователей Safari всегда требуется взаимодействие с пользователем (за исключением специального использования повторного использования страницы после предоставления доступа).

Следующий код добавляет проверку разрешений 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();

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

Песочница iframes

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

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

Например:

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

Требования к cookie

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

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

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

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

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

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

Метод `requestStorageAccessFor()`

Browser Support

Source

Метод requestStorageAccessFor() работает аналогичным образом с requestStorageAccess() но для ресурсов высшего уровня. Он может использоваться только для сайтов в соответствующем веб-сайте, чтобы предотвратить предоставление общего доступа к сторонним файлам cookie.

Для получения более подробной информации о том, как использовать requestStorageAccessFor() прочтите соответствующие наборы веб -сайтов: Руководство по разработчику .

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

Browser Support

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

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

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

	Без RWS	С RWS
Требуется жест пользователя, чтобы инициировать запрос на доступ к хранению
Требуется, чтобы пользователь посетил запрашиваемое происхождение хранилища в контексте верхнего уровня перед предоставлением доступа
Первое время пользователя может быть пропущено
`requestStorageAccess` не требуется, если доступ ранее был предоставлен
Автоматически предоставляет доступ к другим доменам на сайте соответствующего сайта
Поддерживает `requestStorageAccessFor` для доступа к странице верхнего уровня

Различия между использованием API доступа к хранилищам без и с соответствующими наборами веб -сайтов

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

Следующая демонстрация показывает, как куки, установленные самостоятельно на первом экране демонстрации, можно получить во встроенной раме на втором сайте демонстрации:

хранилище-access-api-demo.glitch.me

Демо требует браузера со сторонними куки-файлами отключена:

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

Демо: установление локального хранения

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

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

Демонстрация требует хрома 125 или выше с включенным флагом Test-Tearty-Party-Cookie-Phaseout .

Ресурсы

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

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

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

Browser Support

Source

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

Работа продолжает решать все оставшиеся проблемы с блокировкой , прежде чем стандартизировать API .

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

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

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

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

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

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

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

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

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

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

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

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

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

Файлы cookie, имеющие независимое отдельное состояние (чипсы), позволяют разработчикам выбирать печенье для «разделенного» хранения, с отдельной банкой для печенья на сайте верхнего уровня. Например, сторонний виджет веб-чата может полагаться на установку файла cookie для сохранения информации сеанса. Информация о сеансе сохраняется для на площадку, поэтому файлы cookie, установленные виджетом API доступа к хранилищу полезен, когда встроенный сторонний виджет третьего лица зависит от обмена той же информацией по разным происхождению (например, для сведений или предпочтений сеанса).
Распределение хранения -это способ для перекрестных сайтов iframes использовать существующие механизмы хранения JavaScript при разделении базового хранилища на сайте. Это предотвращает доступ к встроенному хранилищу на одном веб -сайте с тем же встроенным на другие веб -сайты.
Связанные наборы веб -сайтов (RWS) - это способ для организации объявить отношения между сайтами, так что браузеры позволяют ограниченный невозможный cookie и доступ к хранению в определенных целях. Сайты по -прежнему должны запросить доступ с помощью API доступа к хранилищам, но для сайтов в наборе доступ может быть предоставлен без пользовательских подсказок.
Федеративное управление учетными данными (FEDCM)-это подход, сохраняющий конфиденциальность, к федеративным услугам идентификации. API API для хранения имеет дело с доступом к невозможным файлам cookie и пост-логину. Для некоторых вариантов использования FedCM предоставляет альтернативное решение для API доступа к хранилищу и может быть предпочтительным, поскольку в нем есть более ориентированная на логин подсказку браузера. Тем не менее, принятие FedCM обычно требует дополнительных изменений в вашем коде, например, для поддержки его конечных точек HTTP.
Также существуют API API , связанные с AD и измерением , и 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.
    // Note on page load this will always be false initially so we could be
    // skipped in this example, but including for completeness for when this
    // is not so obvious.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

Доступ к хранилищу предоставляется только документу iframe только после того, как он вызовет requestStorageAccess(), поэтому hasStorageAccess() всегда будет возвращать false изначально-за исключением того, что другой документ с одинаковым языком в том же iframe уже был предоставлен доступ. Грант сохраняется через навигации с одинаковым происхождением внутри 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);

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

let handle = null;

async function doClick() {
  if (!handle) {
    try {
      handle = await document.requestStorageAccess({localStorage: true});
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  // Use handle to access unpartitioned local storage.
  handle.localStorage.setItem('foo', 'bar');
}

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

Разрешение подсказка

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

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

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

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

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

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

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

Ключевой момент: даже после того, как разрешение granted , это автоматически не дает всем кадрам доступ к невозможным файлам cookie или хранению. Метод requestStorageAccess() все еще должен быть вызван на каждой загрузке страницы каждой кадром, которая требует невозможных файлов cookie или доступа к хранилищу. Это гарантирует, что рамка получает доступ только к файлам cookie и хранилищам, когда он нуждается в них, а не предоставление доступа ко всем кадрам.

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

FedCM как доверительный сигнал для SAA

FEDCM (Federated Decriention Management) является подходом, сохраняющим конфиденциальность, к федеративным услугам идентификации (например, «Вопрос с ...»), который не полагается на сторонние файлы cookie или навигационные перенаправления.

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

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

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

Например, idp.example iframe встроен в rp.example . Когда пользователь входит в систему с FEDCM, idp.example IFRAME может запросить доступ к хранилищам для собственных файлов 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',
    }],
  },
});

После входа пользователя IDP может вызовать requestStorageAccess() из idp.example iframe, пока RP явно разрешил это с политикой разрешений . Вставка будет автоматически предоставлен доступ к хранилищам к собственным 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 применяются к доступу к хранению грантов.

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

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

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

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

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

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

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

Поток	Заголовок	Ценить	Описание
Запрос	`Sec-Fetch-Storage-Access` ПРИМЕЧАНИЕ. Браузер автоматически отправляет этот заголовок в перекрестных запросах, которые включают учетные данные (например, `new Request('request.example', { credentials: 'include' });` ).	`none`	Embed не имеет разрешения на доступ к хранению.
		`inactive`	У Embed есть разрешение, но не использует его. Запрос также должен включать заголовок `Origin` .
		`active`	Enced имеет невозможный доступ Cookie.
Ответ	`Activate-Storage-Access`	`load`	Показал браузеру предоставить доступ к Embedder к невозможным файлам cookie для запрошенного ресурса. Включение этого заголовка эквивалентно вызова `document.requestStorageAccess()` если было предоставлено разрешение `storage-access` . Это означает, что никакой дополнительной подсказке не будет отображаться пользователю.
	`Activate-Storage-Access`	`retry`	Попросите браузера активировать разрешение на доступ к хранению, а затем повторить запрос.
	`allowed-origin`	`<origin>`	Указывает, какое происхождение разрешено инициировать запросы на учетные данные (например, `https://site.example` или `*` ).

  // 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')
  }
});

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

Следующий код добавляет проверку разрешений 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();

Песочница iframes

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

Например:

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

Требования к cookie

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

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

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

Метод `requestStorageAccessFor()`

Browser Support

Source

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

Browser Support

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

	Без RWS	С RWS
Требуется жест пользователя, чтобы инициировать запрос на доступ к хранению
Требуется, чтобы пользователь посетил запрашиваемое происхождение хранилища в контексте верхнего уровня перед предоставлением доступа
Первое время пользователя может быть пропущено
`requestStorageAccess` не требуется, если доступ ранее был предоставлен
Автоматически предоставляет доступ к другим доменам на сайте соответствующего сайта
Поддерживает `requestStorageAccessFor` для доступа к странице верхнего уровня

Различия между использованием API доступа к хранилищам без и с соответствующими наборами веб -сайтов

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

хранилище-access-api-demo.glitch.me

Демо требует браузера со сторонними куки-файлами отключена:

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

Демо: установление локального хранения

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

Демонстрация требует хрома 125 или выше с включенным флагом Test-Tearty-Party-Cookie-Phaseout .

Ресурсы

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

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

Browser Support

Source

Работа продолжает решать все оставшиеся проблемы с блокировкой , прежде чем стандартизировать API .

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

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

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

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

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

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

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

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

Файлы cookie, имеющие независимое отдельное состояние (чипсы), позволяют разработчикам выбирать печенье для «разделенного» хранения, с отдельной банкой для печенья на сайте верхнего уровня. Например, сторонний виджет веб-чата может полагаться на установку файла cookie для сохранения информации сеанса. Информация о сеансе сохраняется для на площадку, поэтому файлы cookie, установленные виджетом API доступа к хранилищу полезен, когда встроенный сторонний виджет третьего лица зависит от обмена той же информацией по разным происхождению (например, для сведений или предпочтений сеанса).
Storage Partitioning is a way for cross-site iframes to use existing JavaScript storage mechanisms while dividing the underlying storage per-site. This prevents embedded storage in one website from being accessed by the same embed on other websites.
Related Websites Sets (RWS) is a way for an organization to declare relationships among sites, so that browsers allow limited unpartitioned cookie and storage access for specific purposes. Sites still need to request access with the Storage Access API, but for sites within the set, access can be granted without user prompts.
Federated Credential Management (FedCM) is a privacy-preserving approach to federated identity services. The Storage Access API deals with accessing unpartitioned cookies and storage post-login. For some use cases FedCM provides an alternative solution to the Storage Access API, and may be preferable as it features a more login-oriented browser prompt. However, adopting FedCM usually requires additional changes to your code, for example to support its HTTP endpoints.
Anti-fraud , ad-related , and measurement APIs also exist, and the Storage Access API is not intended to address those concerns.

Use the Storage Access API

The Storage Access API has two promised-based methods:

Document.hasStorageAccess() (also available under the new name Document.hasUnpartitionedCookieAccess() as of Chrome 125)
Document.requestStorageAccess()

It also integrates with the Permissions API . This lets you check the status of the storage-access permission in a third-party context, which indicates whether a call to document.requestStorageAccess() would be automatically granted:

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

Use the `hasStorageAccess()` method

When a site first loads, it can use the hasStorageAccess() method to check whether access to third-party cookies has already been granted.

// 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.
    // Note on page load this will always be false initially so we could be
    // skipped in this example, but including for completeness for when this
    // is not so obvious.
    hasAccess = await document.hasStorageAccess();
    if (!hasAccess) {
      // Handle the lack of access (covered later)
    }
  }
  if (hasAccess) {
    // Use the cookies.
  }
}
handleCookieAccessInit();

Storage access is only granted to an iframe document after it calls requestStorageAccess(), so hasStorageAccess() will always return false initially—except when another same-origin document in the same iframe had already been granted access. The grant is preserved across same-origin navigations inside the iframe specifically to allow reloads after granting access for pages that require cookies to be present in the initial request for the HTML document.

Use `requestStorageAccess()`

If the iframe does not have access it may need to request access using the requestStorageAccess() method:

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

The first time this is requested, the user may need to approve this access with a browser prompt, after which the promise will resolve, or will reject resulting in an exception if await is used.

To prevent abuse, this browser prompt will only be shown after a user interaction. That's why requestStorageAccess() initially needs to be called from a user-activated event handler, rather than immediately as the iframe loads:

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

If you need to use local storage instead of cookies, you could do the following:

let handle = null;

async function doClick() {
  if (!handle) {
    try {
      handle = await document.requestStorageAccess({localStorage: true});
    } catch (err) {
      // Access was not granted.
      return;
    }
  }

  // Use handle to access unpartitioned local storage.
  handle.localStorage.setItem('foo', 'bar');
}

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

Permission prompts

When the user clicks the button for the first time, the browser prompt will automatically appear in most cases, typically in the address bar. The following screenshot shows an example of Chrome's prompt, but other browsers have a similar UI:

Chrome Storage Access API permission prompt — Chrome's Storage Access API permission prompt

The prompt may be skipped by the browser and permission automatically provided in certain circumstances:

If the page and iframe have been used in the last 30 days after accepting the prompt.
If the embedded iframe is part of a Related Website Set .
If FedCM is used as a trust signal for storage access.
In Firefox, the prompt is also skipped for known websites (those you have interacted with at the top level) for the first five attempts.

Alternatively, the method may be automatically rejected without showing the prompt in certain circumstances:

If the user has not previously visited and interacted with the site that owns the iframe as a top-level document, not in an iframe. This means the Storage Access API is only useful for embedded sites that users have previously visited in a first-party context.
If the requestStorageAccess() method is called outside of a user interaction event without prior approval of the prompt after an interaction.

While the user will be prompted on the initial use, subsequent visits can resolve requestStorageAccess() without a prompt and without requiring user interaction in Chrome and Firefox. Note that Safari always requires a user interaction.

Key point: Even once the permission is granted , that does not automatically give all frames access to unpartitioned cookies or storage. The requestStorageAccess() method must still be called on each page load by each frame that requires unpartitioned cookies or storage access. This ensures the frame only receives access to cookies and storage when it needs them, rather than granting access to all frames.

As cookie and storage access may be granted without a prompt, or user interaction, it is often possible to get unpartitioned cookie or storage access before a user interaction on browsers that support this (Chrome and Firefox) by calling requestStorageAccess() on page load. This may allow you to access unpartitioned cookies and storage immediately and provide a fuller experience, even before the user interacts with the iframe. This can be a better user experience for some situations than waiting for user interaction.

FedCM as a trust signal for SAA

FedCM (Federated Credential Management) is a privacy-preserving approach to federated identity services (such as "Sign in with...") that doesn't rely on third-party cookies or navigational redirects.

When a user logs in to a Relying Party (RP) that has some embedded content from a third-party identity provider (IdP) with FedCM, the embedded IdP content can automatically get storage access to its own top-level unpartitioned cookies. To enable automatic storage access with FedCM, these conditions must be met:

The FedCM authentication (the user sign-in state) must be active.
The RP has opted in by setting the identity-credentials-get permission, for example:

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

For example, an idp.example iframe is embedded in rp.example . When the user logs in with FedCM, the idp.example iframe can request storage access for its own top-level cookies.

The rp.example makes a FedCM call to log the user in with the identity provider 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',
    }],
  },
});

After the user logs in, IdP can call requestStorageAccess() from within the idp.example iframe, as long as the RP has explicitly allowed this with Permissions Policy . The embed will be automatically granted storage access to its own top-level cookie, without user activation or the need for another permission prompt :

// 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();

The permission will be auto-granted only as long as the user is signed in with FedCM. Once the authentication is inactive, standard SAA requirements apply to grant storage access.

Subsequent loading with Storage Access Headers

Storage Access Headers is a recommended, more performant way to enable loading of embedded content, including non-iframe resources. The feature is available from Chrome 133. With Storage Access Headers, the browser can recognize when the user has already granted storage-access permission to the third-party origin in the current context, and can load resources with access to unpartitioned cookies during subsequent visits.

Storage access headers flow

With Storage Access Headers, the subsequent pages visits will trigger the following flow:

The user has previously visited website.example that embeds a calendar.example resource and granted storage-access with the document.requestStorageAccess() call .
The user visits website.example that has the calendar.example resource embedded again . This request doesn't yet have access to the cookie, as before. However, the user has previously granted storage-access permission, and the fetch includes a Sec-Fetch-Storage-Access: inactive header, to indicate that unpartitioned cookie access is available but not activated.
The calendar.example server responds with an Activate-Storage-Access: retry; allowed-origin='<origin>' header (in this case, <origin> would be https://website.example ), to indicate that the resource fetch requires the use of unpartitioned cookies with the storage-access permission.
The browser retries the request, this time including unpartitioned cookies (activating the storage-access permission for this fetch and subsequent fetches).
The calendar.example server responds with the personalized iframe content. The response includes an Activate-Storage-Access: load header, to indicate that the browser should load the content with the storage-access permission activated (in other words, load with unpartitioned cookie access, as if document.requestStorageAccess() had been called).
The user agent loads the iframe content with unpartitioned cookie access using the storage-access permission. After this step, the widget can work as expected.

A flowchart illustrating the Storage Access Header flow — Storage Access Header flow diagram.

Use storage access headers

The following table lists Storage Access headers.

Поток	Заголовок	Ценить	Описание
Запрос	`Sec-Fetch-Storage-Access` Note: The browser automatically sends this header in cross-site requests that include credentials (for example, `new Request('request.example', { credentials: 'include' });` ).	`none`	Embed has no storage access permission.
		`inactive`	Embed has permission, but isn't using it. The request must also include the `Origin` header.
		`active`	Embed has unpartitioned cookie access.
Ответ	`Activate-Storage-Access`	`load`	Instructs the browser to grant the embedder access to unpartitioned cookies for the requested resource. Including this header is equivalent to calling `document.requestStorageAccess()` if the `storage-access` permission has been granted. This means that no additional prompt will be displayed to the user.
	`Activate-Storage-Access`	`retry`	Instructs the browser to activate the storage-access permission, and then retry the request.
	`allowed-origin`	`<origin>`	Specifies which origin is allowed to initiate credentialed requests (eg, `https://site.example` or `*` ).

For example, Storage Access Headers can be used to load an image image from a third-party:

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

In this case, server.example should implement the following logic on the server side:

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

The Storage Access API demo embeds third-party content (including a non-iframe image) using Storage Access Headers.

Use the `storage-access` permission query

To check whether access can be granted without a user interaction, you can check the status of the storage-access permission and only make the requestStoreAccess() call early if no user action is required, rather than call it and have it fail when an interaction is required.

This also lets you potentially handle the need for a prompt upfront by displaying different content—for example, a login button.

Caution: The storage-access permission is supported in Chrome and Firefox, but not in Safari. For Safari users, a user interaction is always required (except for the special use case of a page reload after access is granted).

The following code adds the storage-access permission check to the earlier example:

// 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();

Key point: For privacy reasons, it is not possible to tell if the prompt was shown and rejected , or not shown based on browser heuristics—both will return prompt as the current state even when queried again.

Sandboxed iframes

When using the Storage Access API in sandboxed iframes , the following sandbox permissions are required:

allow-storage-access-by-user-activation is required to allow access to the Storage Access API.
allow-scripts is required to allow use of JavaScript to call the API.
allow-same-origin is required to allow access to same-origin cookies and other storage.

Например:

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

Cookie requirements

To be accessed with the Storage Access API in Chrome, cross-site cookies must be set with the following two attributes:

SameSite=None - which is required to mark the cookie as cross-site
Secure - which ensures only cookies set by HTTPS sites can be accessed.

In Firefox and Safari, cookies are defaulted to SameSite=None and they don't restrict SAA to Secure cookies so these attributes are not required. It is recommended to be explicit about the SameSite attribute and to always use Secure cookies.

Top-level page access

The Storage Access API is intended for enabling access to third-party cookies within embedded iframes.

There are also other use cases when the top-level page requires access to third-party cookies. For example, images or scripts which are restricted by cookies, which site owners may want to include directly in the top-level document rather than in an iframe. To address this use case Chrome has proposed an extension to the Storage Access API which adds a requestStorageAccessFor() method.

The `requestStorageAccessFor()` method

Browser Support

Source

requestStorageAccessFor() method works in a similar way to requestStorageAccess() but for top-level resources. It can only be used for sites within a Related Website Set to prevent granting general access to third-party cookies.

For more details on how to use requestStorageAccessFor() read the Related Website Sets: developer guide .

The `top-level-storage-access` permission query

Browser Support

Similar to the storage-access permission, there is a top-level-storage-access permission to check whether access can be granted for requestStorageAccessFor() .

How is the Storage Access API different when used with RWS?

When Related Website Sets are used with the Storage Access API, certain additional capabilities are available as detailed in the following table:

	Without RWS	With RWS
Requires a user gesture to initiate the request for storage access
Requires user to visit requested storage origin in a top-level context before granting access
First time user prompt can be skipped
`requestStorageAccess` not required to be called if access has been previously granted
Automatically grants access across other domains in a Related Website Site
Supports `requestStorageAccessFor` for top-level page access

Differences between using Storage Access API without and with Related Website Sets

Demo: setting and accessing cookies

The following demo shows how a cookie set by yourself in the first screen of the demo can be accessed in an embedded frame in the second site of the demo:

storage-access-api-demo.glitch.me

The demo requires a browser with third-party cookies disabled:

Chrome 118 or higher with the chrome://flags/#test-third-party-cookie-phaseout flag set and browser restarted.
Firefox
Сафари

Demo: setting Local Storage

The following demo shows how to access unpartitioned Broadcast Channels from a third-party iframe using the Storage Access API:

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

The demo requires Chrome 125 or higher with the test-third-party-cookie-phaseout flag enabled.

Ресурсы

Read the specification providing third-party cookie access or follow and raise issues .
Read the specification providing unpartitioned storage access or follow and raise issues .
API documentation and guide .
Chrome documentation on using Storage Access API in Related Website Sets

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

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

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

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

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

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

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

Используйте requestStorageAccess()

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

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

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

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

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

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

Изолированные iframe в песочнице

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

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

Метод requestStorageAccessFor()

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

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

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

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

Ресурсы

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

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

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

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

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

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

Используйте requestStorageAccess()

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

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

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

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

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

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

Песочница iframes

Требования к cookie

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

Метод requestStorageAccessFor()

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

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

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

Демо: установление локального хранения

Ресурсы

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

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

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

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

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

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

Используйте requestStorageAccess()

Разрешение подсказка

FedCM как доверительный сигнал для SAA

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

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

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

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

Песочница iframes

Требования к cookie

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

Метод requestStorageAccessFor()

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

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

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

Демо: установление локального хранения

Ресурсы

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

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

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

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

Use the Storage Access API

Use the hasStorageAccess() method

Use requestStorageAccess()

Permission prompts

FedCM as a trust signal for SAA

Subsequent loading with Storage Access Headers

Storage access headers flow

Use storage access headers

Use the storage-access permission query

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

Используйте `requestStorageAccess()`

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

Метод `requestStorageAccessFor()`

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

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

Используйте `requestStorageAccess()`

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

Метод `requestStorageAccessFor()`

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

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

Используйте `requestStorageAccess()`

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

Метод `requestStorageAccessFor()`

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

Use the `hasStorageAccess()` method

Use `requestStorageAccess()`

Use the `storage-access` permission query

The `requestStorageAccessFor()` method

The `top-level-storage-access` permission query