API Storage Access

O bloqueio de cookies de terceiros por navegadores, configurações do usuário e particionamento de armazenamento (link em inglês) representam um desafio para sites e serviços que dependem de cookies e outros armazenamentos em contextos incorporados, para jornadas do usuário, como autenticação. A API Storage Access (SAA) permite que esses casos de uso continuem funcionando, limitando ao máximo o rastreamento entre sites.

Status da implementação

A API Storage Access está disponível em todos os principais navegadores, mas há pequenas diferenças de implementação entre eles. Essas diferenças foram destacadas nas seções relevantes desta postagem.

Estamos trabalhando para resolver todos os problemas de bloqueio restantes antes de padronizar a API.

O que é a API Storage Access?

A API Storage Access é uma API JavaScript que permite que iframes solicitem permissões de acesso ao armazenamento, que, de outra maneira, seria negado de acordo com as configurações do navegador. Incorporações com casos de uso que dependem do carregamento de recursos entre sites podem usar a API para solicitar permissão de acesso do usuário, conforme necessário.

Se a solicitação de armazenamento for concedida, o iframe terá acesso aos cookies e ao armazenamento não particionados, que também estão disponíveis quando os usuários o visitam como um site de nível superior.

A API Storage Access permite que cookies e armazenamento não particionados específicos sejam fornecidos com o mínimo de ônus para o usuário final, evitando o acesso genérico a cookies e armazenamento não particionados, que geralmente é usado para rastreamento de usuários.

Casos de uso

Algumas incorporações de terceiros exigem acesso a cookies ou armazenamento não particionados para oferecer uma experiência melhor ao usuário. Isso não estará disponível quando os cookies de terceiros forem restritos e o particionamento de armazenamento estiver ativado.

Os casos de uso incluem o seguinte:

• Widgets de comentários incorporados que exigem detalhes da sessão de login.
• Botões "Gostei" de redes sociais que exigem detalhes da sessão de login.
• Documentos incorporados que exigem detalhes da sessão de login.
• Uma experiência premium fornecida a uma incorporação de vídeo (por exemplo, para não mostrar anúncios a usuários conectados ou para saber as preferências do usuário em relação a legendas descritivas ou restringir determinados tipos de vídeo).
• Sistemas de pagamento incorporados.

Muitos desses casos de uso envolvem a persistência do acesso de login em iframes incorporados.

Quando usar a API Storage Access em vez de outras APIs

A API Storage Access é uma das alternativas ao uso de cookies e armazenamento não particionados. Por isso, é importante entender quando usar essa API em comparação com as outras. Ele é destinado a casos de uso em que as duas condições a seguir são verdadeiras:

• O usuário vai interagir com o conteúdo incorporado, ou seja, não é um iframe passivo ou oculto.
• O usuário visitou a origem incorporada em um contexto de nível superior, ou seja, quando essa origem não está incorporada em outro site.

Há APIs alternativas para vários casos de uso:

• Os cookies com estado particionado independente (CHIPS) permitem que os desenvolvedores ativem um cookie no armazenamento "particionado", com um pote de cookies separado por site de nível superior. Por exemplo, um widget de chat on-line de terceiros pode depender da definição de um cookie para salvar informações da sessão. As informações da sessão são salvas por site. Assim, não é necessário acessar o cookie definido pelo widget em outros sites em que ele também está incorporado. A API Storage Access é útil quando um widget incorporado de terceiros depende do compartilhamento das mesmas informações em origens diferentes (por exemplo, para detalhes ou preferências da sessão conectada).
• O particionamento de armazenamento é uma maneira de iframes entre sites usarem mecanismos de armazenamento JavaScript atuais, dividindo o armazenamento subjacente por site. Isso impede que o armazenamento incorporado em um site seja acessado pela mesma incorporação em outros sites.
• Os conjuntos de sites relacionados (RWS, na sigla em inglês) são uma maneira de uma organização declarar relações entre sites para que os navegadores permitam o acesso limitado a cookies não particionados e ao armazenamento para fins específicos. Os sites ainda precisam solicitar acesso com a API Storage Access, mas, para sites no conjunto, o acesso pode ser concedido sem solicitações ao usuário.
• O Gerenciamento de credenciais federadas (FedCM) é uma abordagem que preserva a privacidade nos serviços de identidade federada. A API Storage Access lida com o acesso a cookies e armazenamento não particionados após o login. Para alguns casos de uso, a FedCM oferece uma solução alternativa à API Storage Access e pode ser preferível porque apresenta um aviso do navegador mais orientado ao login. No entanto, a adoção da FedCM geralmente exige outras mudanças no código, por exemplo, para oferecer suporte aos endpoints HTTP.
• Também existem APIs antifraude, relacionadas a anúncios e de medição, e a API Storage Access não foi criada para resolver esses problemas.

Usar a API Storage Access

A API Storage Access tem dois métodos baseados em promessas:

• Document.hasStorageAccess() (também disponível com o novo nome Document.hasUnpartitionedCookieAccess() a partir do Chrome 125)
• Document.requestStorageAccess()

Ela também se integra à API Permissions. Isso permite verificar o status da permissão de acesso ao armazenamento em um contexto de terceiros, o que indica se uma chamada para document.requestStorageAccess() seria concedida automaticamente:

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

Use o método hasStorageAccess()

Quando um site é carregado pela primeira vez, ele pode usar o método hasStorageAccess() para verificar se o acesso a cookies de terceiros já foi concedido.

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

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

A API Storage Access só concede acesso ao armazenamento a um documento iframe depois que ele chama requestStorageAccess(),. Portanto, hasStorageAccess() pode retornar "false" inicialmente, por exemplo, se o usuário bloquear cookies de terceiros por padrão. No entanto, as configurações de usuário específicas do site também podem permitir o acesso a cookies em um site específico, mesmo que o usuário bloqueie cookies de terceiros por padrão. O acesso ao armazenamento usando essa API é preservado em navegações de mesma origem dentro do iframe especificamente para permitir recarregamentos após a concessão de acesso para páginas que exigem a presença de cookies na solicitação inicial do documento HTML.

Usar requestStorageAccess()

Se o iframe não tiver acesso, ele precisará solicitar usando o método requestStorageAccess():

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

Na primeira vez que isso for solicitado, o usuário talvez precise aprovar o acesso com um comando do navegador. Depois disso, a promessa será resolvida ou rejeitada, resultando em uma exceção se await for usado.

Para evitar abusos, essa solicitação do navegador só será mostrada após uma interação do usuário. Por isso, requestStorageAccess() precisa ser chamado inicialmente de um manipulador de eventos ativado pelo usuário, e não imediatamente quando o iframe é carregado:

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

Solicitações de permissão

Quando o usuário clica no botão pela primeira vez, o navegador aparece automaticamente na maioria dos casos, geralmente na barra de endereço. A captura de tela a seguir mostra um exemplo do aviso do Chrome, mas outros navegadores têm uma interface semelhante:

O navegador pode ignorar a solicitação e conceder a permissão automaticamente em determinadas circunstâncias:

• Se a página e o iframe foram usados nos últimos 30 dias após a aceitação da solicitação.
• Se o iframe incorporado fizer parte de um conjunto de sites relacionados.
• Se a FedCM for usada como um indicador de confiança para acesso ao armazenamento.
• No Firefox, o aviso também é ignorado para sites conhecidos (com os quais você interagiu no nível superior) nas cinco primeiras tentativas.

Como alternativa, o método pode ser rejeitado automaticamente sem mostrar a solicitação em determinadas circunstâncias:

• Se o usuário não tiver acessado e interagido com o site proprietário do iframe como um documento de nível superior, não em um iframe. Isso significa que a API Storage Access só é útil para sites incorporados que os usuários já visitaram em um contexto próprio.
• Se o método requestStorageAccess() for chamado fora de um evento de interação do usuário sem aprovação prévia do aviso após uma interação.

Embora o usuário receba uma solicitação no uso inicial, as visitas subsequentes podem resolver requestStorageAccess() sem uma solicitação e sem exigir interação do usuário no Chrome e no Firefox. O Safari sempre exige uma interação do usuário.

Como o acesso a cookies e armazenamento pode ser concedido sem um aviso ou interação do usuário, geralmente é possível obter acesso a cookies ou armazenamento não particionados antes de uma interação do usuário em navegadores que oferecem suporte a isso (Chrome e Firefox) chamando requestStorageAccess() no carregamento da página. Isso permite acessar cookies e armazenamento não particionados imediatamente e oferecer uma experiência mais completa, mesmo antes de o usuário interagir com o iframe. Isso pode ser uma experiência melhor para o usuário em algumas situações do que esperar pela interação dele.

A API FedCM como um indicador de confiança para a SAA

O FedCM (gerenciamento de credenciais federadas) é uma abordagem que preserva a privacidade nos serviços de identidade federada (como "Fazer login com...") e não depende de cookies de terceiros ou redirecionamentos de navegação.

Quando um usuário faz login em uma parte confiável (RP) que tem conteúdo incorporado de um provedor de identidade (IdP) de terceiros com o FedCM, o conteúdo incorporado do IdP pode receber automaticamente acesso ao armazenamento dos próprios cookies não particionados de nível superior. Para ativar o acesso automático ao armazenamento com a FedCM, estas condições precisam ser atendidas:

• A autenticação do FedCM (o estado de login do usuário) precisa estar ativa.
• O RP ativou a configuração da permissão identity-credentials-get, por exemplo:

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

Por exemplo, um iframe idp.example é incorporado em rp.example. Quando o usuário faz login com a FedCM, o iframe idp.example pode solicitar acesso ao armazenamento dos próprios cookies de nível superior.

O rp.example faz uma chamada da API FedCM para fazer login do usuário com o provedor de identidade 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',
    }],
  },
});

Depois que o usuário faz login, o IdP pode chamar requestStorageAccess() de dentro do iframe idp.example, desde que o RP tenha permitido isso explicitamente com a Política de permissões. A incorporação vai receber automaticamente acesso de armazenamento ao próprio cookie de nível superior, sem ativação do usuário ou a necessidade de outra solicitação de permissão:

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

A permissão será concedida automaticamente apenas enquanto o usuário estiver conectado com o FedCM. Quando a autenticação estiver inativa, os requisitos padrão de SAA serão aplicados para conceder acesso ao armazenamento.

API Storage Access para armazenamento sem cookies

É possível solicitar acesso ao armazenamento local não particionado transmitindo o types parâmetro para sua chamada requestStorageAccess. Por exemplo, para solicitar acesso ao armazenamento local não particionado, você pode chamar requestStorageAccess({localStorage: true}).

Se os cookies de terceiros estiverem ativados, esse método vai conceder acesso sem exigir ativação do usuário ou qualquer solicitação de permissão. Se o usuário tiver desativado cookies de terceiros, ele precisará ser solicitado antes de receber acesso ao armazenamento.

Primeiro, verifique se o navegador já tem acesso ao armazenamento:

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

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

Se os cookies de terceiros estiverem ativados, solicite o acesso ao armazenamento:

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

Se os cookies de terceiros estiverem bloqueados (por exemplo, no modo de navegação anônima), verifique as permissões de consulta para decidir se é necessário pedir confirmação ao usuário. O estado da permissão navigator.permissions.query({name: 'storage-access'}) pode ter os seguintes valores:

• granted. O usuário já concedeu acesso. Chame requestStorageAccess para ter acesso ao armazenamento não particionado sem precisar de uma solicitação adicional do usuário.
• prompt. O usuário ainda não concedeu acesso. Defina um listener de clique e chame requestStorageAccess novamente após uma interação do usuário.
• error. A permissão não é aceita. Quando a API Storage Access é compatível, essa permissão também é.

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

O fluxo completo para processar o armazenamento não particionado por cookies pode ser implementado da seguinte maneira:

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

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

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

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

Carregamento subsequente com cabeçalhos de acesso ao armazenamento

Os cabeçalhos de acesso ao armazenamento são uma maneira recomendada e mais eficiente de ativar o carregamento de conteúdo incorporado, incluindo recursos que não são iframes. O recurso está disponível a partir do Chrome 133. Com os cabeçalhos de acesso ao armazenamento, o navegador pode reconhecer quando o usuário já concedeu permissão de storage-access à origem de terceiros no contexto atual e pode carregar recursos com acesso a cookies não particionados durante visitas subsequentes.

Fluxo de cabeçalhos de acesso ao armazenamento

Com os cabeçalhos de acesso ao armazenamento, as visitas às páginas subsequentes vão acionar o seguinte fluxo:

1. O usuário já visitou website.example, que incorpora um recurso calendar.example, e concedeu storage-access com a chamada document.requestStorageAccess().
2. O usuário visita website.example, que tem o recurso calendar.example incorporado novamente. Essa solicitação ainda não tem acesso ao cookie, como antes. No entanto, o usuário já concedeu a permissão storage-access, e a busca inclui um cabeçalho Sec-Fetch-Storage-Access: inactive para indicar que o acesso a cookies não particionados está disponível, mas não ativado.
3. O servidor calendar.example responde com um cabeçalho Activate-Storage-Access: retry; allowed-origin='<origin>' (neste caso, <origin> seria https://website.example) para indicar que a busca de recursos exige o uso de cookies não particionados com a permissão storage-access.
4. O navegador tenta novamente a solicitação, desta vez incluindo cookies não particionados (ativando a permissão storage-access para esta busca e as buscas subsequentes).
5. O servidor calendar.example responde com o conteúdo personalizado do iframe. A resposta inclui um cabeçalho Activate-Storage-Access: load para indicar que o navegador precisa carregar o conteúdo com a permissão storage-access ativada. Em outras palavras, carregar com acesso a cookies não particionados, como se document.requestStorageAccess() tivesse sido chamado.
6. O user agent carrega o conteúdo do iframe com acesso a cookies não particionados usando a permissão storage-access. Depois dessa etapa, o widget poderá funcionar como esperado.

Usar cabeçalhos de acesso ao armazenamento

A tabela a seguir lista os cabeçalhos de acesso ao armazenamento.

Por exemplo, os cabeçalhos de acesso ao armazenamento podem ser usados para carregar uma imagem de terceiros:

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

Nesse caso, server.example precisa implementar a seguinte lógica no lado do servidor:

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

A demonstração da API Storage Access incorpora conteúdo de terceiros (incluindo uma imagem que não é um iframe) usando cabeçalhos de acesso ao armazenamento.

Usar a consulta de permissão storage-access

Para verificar se o acesso pode ser concedido sem uma interação do usuário, confira o status da permissão storage-access e faça a chamada requestStoreAccess() antecipadamente apenas se nenhuma ação do usuário for necessária, em vez de fazer a chamada e ter uma falha quando uma interação for necessária.

Isso também permite lidar com a necessidade de um aviso antecipado mostrando conteúdo diferente, como um botão de login.

O código a seguir adiciona a verificação de permissão storage-access ao exemplo anterior:

// 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 no modo sandbox

Ao usar a API Storage Access em iframes em sandbox, as seguintes permissões de sandbox são necessárias:

• O allow-storage-access-by-user-activation é necessário para permitir o acesso à API Storage Access.
• O allow-scripts é necessário para permitir o uso do JavaScript para chamar a API.
• allow-same-origin é necessário para permitir o acesso a cookies de mesma origem e outros armazenamentos.

Exemplo:

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

Requisitos de cookies

Para serem acessados com a API Storage Access no Chrome, os cookies entre sites precisam ser definidos com os dois atributos a seguir:

• SameSite=None, que é obrigatório para marcar o cookie como entre sites.
• Secure, que garante que apenas cookies definidos por sites HTTPS possam ser acessados.

No Firefox e no Safari, os cookies são definidos como SameSite=None por padrão e não restringem o SAA a cookies Secure. Portanto, esses atributos não são necessários. É recomendável ser explícito sobre o atributo SameSite e sempre usar cookies Secure.

Acesso à página de nível superior

A API Storage Access foi criada para permitir o acesso a cookies de terceiros em iframes incorporados.

Há também outros casos de uso em que a página de nível superior exige acesso a cookies de terceiros. Por exemplo, imagens ou scripts restritos por cookies, que os proprietários de sites podem querer incluir diretamente no documento de nível superior em vez de um iframe. Para resolver esse caso de uso, o Chrome propôs uma extensão da API Storage Access, que adiciona um método requestStorageAccessFor().

O método requestStorageAccessFor()

O método requestStorageAccessFor() funciona de maneira semelhante ao requestStorageAccess(), mas para recursos de nível superior. Ele só pode ser usado para sites em um conjunto de sites relacionados para evitar a concessão de acesso geral a cookies de terceiros.

Para mais detalhes sobre como usar requestStorageAccessFor(), leia o Guia para desenvolvedores sobre conjuntos de sites relacionados.

A consulta de permissão top-level-storage-access

Semelhante à permissão storage-access, há uma permissão top-level-storage-access para verificar se o acesso pode ser concedido para requestStorageAccessFor().

Como a API Storage Access é diferente quando usada com RWS?

Quando os conjuntos de sites relacionados são usados com a API Storage Access, alguns recursos adicionais ficam disponíveis, conforme detalhado na tabela a seguir:

Demonstração: como definir e acessar cookies

A demonstração a seguir mostra como um cookie definido por você na primeira tela pode ser acessado em um frame incorporado no segundo site da demonstração:

storage-access-api-demo.glitch.me

A demonstração exige um navegador com cookies de terceiros desativados:

• Chrome 118 ou mais recente com a flag chrome://flags/#test-third-party-cookie-phaseout definida e o navegador reiniciado.
• Firefox
• Safari

Demonstração: como definir o armazenamento local

A demonstração a seguir mostra como acessar canais de transmissão não particionados de um iframe de terceiros usando a API Storage Access:

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

A demonstração exige o Chrome 125 ou versões mais recentes com a flag test-third-party-cookie-phaseout ativada.

Recursos

• Leia a especificação que fornece acesso a cookies de terceiros ou siga e levante problemas.
• Leia a especificação que fornece acesso ao armazenamento não particionado ou siga e levante problemas.
• Documentação da API e guia.
• Documentação do Chrome sobre como usar a API Storage Access em conjuntos de sites relacionados