API Storage Access

Il blocco dei cookie di terze parti da parte di browser, le impostazioni utente e il partizionamento dello spazio di archiviazione rappresenta una sfida per i siti e i servizi che si basano sui cookie e su altri tipi di archiviazione in contesti incorporati per i percorsi degli utenti come l'autenticazione. L'API Storage Access (SAA) consente a questi casi d'uso di continuare a funzionare, limitando il più possibile il monitoraggio tra siti.

Stato dell'implementazione

L'API Storage Access è disponibile in tutti i principali browser, ma esistono lievi differenze di implementazione tra i browser. Queste differenze sono state evidenziate nelle sezioni pertinenti di questo post.

Il lavoro continua per risolvere tutti i problemi di blocco rimanenti prima di standardizzare l'API.

Che cos'è l'API Storage Access?

L'API Storage Access è un'API JavaScript che consente agli iframe di richiedere autorizzazioni di accesso allo spazio di archiviazione quando l'accesso verrebbe altrimenti negato dalle impostazioni del browser. Gli incorporamenti con casi d'uso che dipendono dal caricamento di risorse tra siti possono utilizzare l'API per richiedere l'autorizzazione di accesso all'utente, in base alle necessità.

Se la richiesta di spazio di archiviazione viene concessa, l'iframe avrà accesso ai cookie e allo spazio di archiviazione non partizionato, che sono disponibili anche quando gli utenti lo visitano come sito di primo livello.

L'API Storage Access consente di fornire cookie e accesso allo spazio di archiviazione non partizionati specifici con un carico minimo per l'utente finale, impedendo al contempo l'accesso allo spazio di archiviazione e ai cookie non partizionati generici, come spesso avviene per il monitoraggio degli utenti.

Casi d'uso

Alcuni incorporamenti di terze parti richiedono l'accesso a cookie o spazio di archiviazione non partizionati per offrire un'esperienza migliore all'utente, cosa che non sarà disponibile se i cookie di terze parti sono limitati e il partizionamento dello spazio di archiviazione è attivato.

I casi d'uso includono:

• Widget per i commenti incorporati che richiedono i dettagli della sessione di accesso.
• "Mi piace" sui social media pulsanti che richiedono dettagli della sessione di accesso.
• Documenti incorporati che richiedono i dettagli della sessione di accesso.
• Un'esperienza premium fornita a un video incorporato (ad esempio, per non mostrare annunci agli utenti che hanno eseguito l'accesso, per conoscere le preferenze dell'utente per i sottotitoli codificati o per limitare determinati tipi di video).
• Sistemi di pagamento integrati.

Molti di questi casi di utilizzo prevedono la persistenza dell'accesso all'accesso negli iframe incorporati.

Quando utilizzare l'API Accesso allo spazio di archiviazione rispetto ad altre API

L'API Storage Access è una delle alternative all'utilizzo di cookie e spazio di archiviazione non partizionati, quindi è importante capire quando utilizzare questa API rispetto alle altre. È pensata per i casi d'uso in cui si verificano entrambe le seguenti condizioni:

• L'utente interagirà con i contenuti incorporati, ovvero non si tratta di un iframe passivo o nascosto.
• L'utente ha visitato l'origine incorporata in un contesto di primo livello, ovvero quando l'origine non è incorporata in un altro sito.

Esistono API alternative per diversi casi d'uso:

• I cookie con stato partizionato indipendente (CHIPS) consentono agli sviluppatori di attivare la suddivisione dei cookie per i cookie. con un barattolo di cookie separato per ogni sito di primo livello. Ad esempio, un widget di chat web di terze parti potrebbe basarsi sull'impostazione di un cookie per salvare le informazioni della sessione. Le informazioni sulla sessione vengono salvate in base al sito, quindi non è necessario accedere al cookie impostato dal widget su altri siti web in cui è incorporato. L'API Accesso allo spazio di archiviazione è utile quando un widget di terze parti incorporato dipende dalla condivisione delle stesse informazioni tra origini diverse (ad esempio per i dettagli o le preferenze della sessione di accesso).
• Il partizionamento dello spazio di archiviazione consente agli iframe cross-site di utilizzare i meccanismi di archiviazione JavaScript esistenti, suddividendo lo spazio di archiviazione sottostante per sito. In questo modo, lo spazio di archiviazione incorporato in un sito web non è accessibile da parte dello stesso incorporamento su altri siti web.
• Insiemi di siti web correlati (RWS) è un modo per un'organizzazione di dichiarare le relazioni tra i siti, in modo che i browser consentano accesso limitato ai cookie e allo spazio di archiviazione non partizionati per scopi specifici. I siti devono comunque richiedere l'accesso con l'API Accesso allo spazio di archiviazione, ma per i siti all'interno dell'insieme l'accesso può essere concesso senza richieste all'utente.
• La gestione delle credenziali federate (FedCM) è un approccio ai servizi di identità federati che tutela la privacy. L'API Storage Access gestisce l'accesso ai cookie e allo spazio di archiviazione non partizionati dopo l'accesso. Per alcuni casi d'uso FedCM offre una soluzione alternativa all'API Storage Access e potrebbe essere preferibile in quanto presenta una richiesta del browser più orientata all'accesso. Tuttavia, l'adozione di FedCM di solito richiede ulteriori modifiche al codice, ad esempio per supportare i suoi endpoint HTTP.
• Esistono anche API di antifrode, relative agli annunci e di misurazione e l'API Accesso allo spazio di archiviazione non è progettata per risolvere questi problemi.

Utilizzare l'API Storage Access

L'API Storage Access ha due metodi basati su promise:

• Document.hasStorageAccess() (disponibile anche con il nuovo nome Document.hasUnpartitionedCookieAccess() a partire da Chrome 125)
• Document.requestStorageAccess()

Inoltre, si integra con l'API Permissions. Ciò consente di controllare lo stato dell'autorizzazione di accesso allo spazio di archiviazione in un contesto di terze parti, che indica se una chiamata a document.requestStorageAccess() verrà concessa automaticamente:

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

Utilizzare il metodo hasStorageAccess()

Al primo caricamento, un sito può utilizzare il metodo hasStorageAccess() per verificare se l'accesso ai cookie di terze parti è già stato concesso.

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

L'accesso allo spazio di archiviazione viene concesso a un documento iframe solo dopo che ha chiamato requestStorageAccess(),, pertanto hasStorageAccess() restituirà sempre false inizialmente, tranne quando a un altro documento della stessa origine nello stesso iframe è già stato concesso l'accesso. La concessione viene conservata nelle navigazioni della stessa origine all'interno dell'iframe, in modo specifico per consentire il ricaricamento dopo aver concesso l'accesso alle pagine che richiedono la presenza di cookie nella richiesta iniziale per il documento HTML.

Utilizza requestStorageAccess()

Se l'iframe non ha accesso, potrebbe dover richiedere l'accesso utilizzando il metodo requestStorageAccess():

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

La prima volta che viene richiesta questa richiesta, l'utente potrebbe dover approvare l'accesso con una richiesta del browser, dopodiché la promessa verrà risolta oppure verrà rifiutata, generando un'eccezione se viene usato await.

Per prevenire comportamenti illeciti, questa richiesta del browser verrà visualizzata soltanto dopo l'interazione di un utente. Ecco perché requestStorageAccess() deve essere chiamato inizialmente da un gestore eventi attivato dall'utente, anziché immediatamente al caricamento dell'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);

Se devi utilizzare lo spazio di archiviazione locale anziché i cookie, puoi procedere come segue:

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

Richieste di autorizzazione

Quando l'utente fa clic sul pulsante per la prima volta, la richiesta del browser vengono visualizzati automaticamente, in genere nella barra degli indirizzi. Lo screenshot seguente mostra un esempio della richiesta di Chrome, ma altri browser hanno un'interfaccia utente simile:

La richiesta potrebbe essere ignorata dal browser e l'autorizzazione fornita automaticamente in determinate circostanze:

• Se la pagina e l'iframe sono stati utilizzati negli ultimi 30 giorni dopo l'accettazione della richiesta.
• Se l'iframe incorporato fa parte di un insieme di siti web correlati.
• In Firefox, la richiesta viene ignorata anche per i siti web noti (quelli con cui hai interagito a livello superiore) per i primi cinque tentativi.

In alternativa, il metodo potrebbe essere rifiutato automaticamente senza mostrare la richiesta in determinate circostanze:

• Se l'utente non ha mai visitato o interagito in precedenza con il sito proprietario dell'iframe come documento di primo livello, non in iframe. Ciò significa che l'API Accesso allo spazio di archiviazione è utile solo per i siti incorporati che gli utenti hanno visitato in precedenza in un contesto proprietario.
• Se il metodo requestStorageAccess() viene chiamato al di fuori di un evento di interazione dell'utente senza la previa approvazione della richiesta dopo un'interazione.

Sebbene all'utente venga richiesto all'uso iniziale, le visite successive possono risolvere requestStorageAccess() senza una richiesta e senza richiedere l'interazione dell'utente in Chrome e Firefox. Tieni presente che Safari richiede sempre un'interazione dell'utente.

Poiché l'accesso ai cookie e allo spazio di archiviazione può essere concesso senza richiesta o interazione dell'utente, spesso è possibile ottenere l'accesso ai cookie o allo spazio di archiviazione non partizionato prima di un'interazione dell'utente sui browser che supportano questa funzionalità (Chrome e Firefox) chiamando requestStorageAccess() al caricamento della pagina. Ciò potrebbe consentirti di accedere immediatamente ai cookie e allo spazio di archiviazione non partizionati e offrire un'esperienza più completa, anche prima che l'utente interagisca con l'iframe. In alcune situazioni, l'esperienza utente potrebbe risultare migliore rispetto all'attesa dell'interazione dell'utente.

Usa la query sulle autorizzazioni storage-access

Per verificare se l'accesso può essere concesso senza l'interazione dell'utente, puoi controllare lo stato dell'autorizzazione storage-access ed eseguire la chiamata anticipata a requestStoreAccess() solo se non è richiesta alcuna azione dell'utente, anziché chiamarla e farla fallire quando è richiesta un'interazione.

In questo modo, puoi anche gestire in anticipo la necessità di una richiesta visualizzando contenuti diversi, ad esempio un pulsante di accesso.

Il codice seguente aggiunge il controllo dell'autorizzazione storage-access all'esempio precedente:

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

iframe con sandbox

Quando utilizzi l'API Storage Access negli iframe con sandbox, sono necessarie le seguenti autorizzazioni sandbox:

• allow-storage-access-by-user-activation è necessario per consentire l'accesso all'API Storage Access.
• allow-scripts è necessario per consentire l'utilizzo di JavaScript per chiamare l'API.
• allow-same-origin è necessario per consentire l'accesso ai cookie della stessa origine e ad altro spazio di archiviazione.

Ad esempio:

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

Requisiti dei cookie

Per poter essere accessibili con l'API Accesso allo spazio di archiviazione in Chrome, i cookie cross-site devono essere impostati con i seguenti due attributi:

• SameSite=None, necessaria per contrassegnare il cookie come cross-site
• Secure, che garantisce che sia possibile accedere solo ai cookie impostati dai siti HTTPS.

In Firefox e Safari, i cookie hanno per impostazione predefinita il valore SameSite=None e non limitano l'ASA ai cookie Secure, pertanto questi attributi non sono obbligatori. Ti consigliamo di specificare esplicitamente l'attributo SameSite e di utilizzare sempre i cookie Secure.

Accesso alla pagina di primo livello

L'API Storage Access è progettata per abilitare l'accesso ai cookie di terze parti all'interno di iframe incorporati.

Esistono anche altri casi d'uso in cui la pagina di primo livello richiede l'accesso a cookie di terze parti. Ad esempio, immagini o script limitati dai cookie, che i proprietari dei siti potrebbero voler includere direttamente nel documento di primo livello anziché in un iframe. Per risolvere questo caso d'uso, Chrome ha proposto un'estensione dell'API Accesso allo spazio di archiviazione che aggiunge un metodorequestStorageAccessFor().

Il metodo requestStorageAccessFor()

Il metodo requestStorageAccessFor() funziona in modo simile a requestStorageAccess(), ma per le risorse di primo livello. Può essere utilizzata solo per i siti all'interno di un insieme di siti web correlati per impedire l'accesso generale ai cookie di terze parti.

Per ulteriori dettagli su come utilizzare requestStorageAccessFor(), leggi la pagina Insiemi di siti web correlati: guida per gli sviluppatori.

La query sull'autorizzazione top-level-storage-access

Analogamente all'autorizzazione storage-access, esiste un'autorizzazione top-level-storage-access per verificare se è possibile concedere l'accesso per requestStorageAccessFor().

In che modo l'API Accesso allo spazio di archiviazione è diversa se utilizzata con RWS?

Quando i set di siti web correlati vengono utilizzati con l'API Accesso allo spazio di archiviazione, sono disponibili alcune funzionalità aggiuntive, come descritto nella tabella seguente:

Demo: impostazione e accesso ai cookie

La seguente demo mostra come è possibile accedere a un cookie impostato dall'utente nella prima schermata della demo in un frame incorporato nel secondo sito della demo:

storage-access-api-demo.glitch.me

La demo richiede un browser con i cookie di terze parti disattivati:

• Chrome 118 o versioni successive con il flag chrome://flags/#test-third-party-cookie-phaseout impostato e il browser riavviato.
• Firefox
• Safari

Demo: impostazione dello spazio di archiviazione locale

La seguente demo mostra come accedere a canali di trasmissione non partizionati da un iframe di terze parti utilizzando l'API Storage Access:

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

La demo richiede Chrome 125 o versioni successive con il flag test-third-party-cookie-phaseout abilitato.

Risorse

• Leggi la specifica che fornisce l'accesso ai cookie di terze parti o segui e segnala i problemi.
• Leggi la specifica relativa all'accesso non partizionato allo spazio di archiviazione oppure segui e segnala i problemi.
• Documentazione e guida dell'API.
• Documentazione di Chrome sull'utilizzo dell'API Storage Access negli insiemi di siti web correlati