Set di siti web correlati: guida per gli sviluppatori

Gli insiemi di siti web correlati (RWS) sono un meccanismo della piattaforma web che aiuta i browser a comprendere le relazioni tra una raccolta di domini. In questo modo, i browser possono prendere decisioni chiave per attivare determinate funzioni del sito (ad esempio se consentire l'accesso ai cookie tra siti) e presentare queste informazioni agli utenti.

Molti siti si basano su più domini per offrire un'unica esperienza utente. Le organizzazioni potrebbero voler mantenere domini di primo livello diversi per più casi d'uso, ad esempio domini specifici per paese o domini di servizio per l'hosting di immagini o video. Gli insiemi di siti web correlati consentono ai siti di condividere dati tra domini, con controlli specifici.

Che cos'è un insieme di siti web correlati?

A livello generale, un insieme di siti web correlati è una raccolta di domini per i quali esiste un singolo "insieme principale" e potenzialmente più "insiemi membri".

Nell'esempio seguente, primary elenca il dominio principale e associatedSites elenca i domini che soddisfano i requisiti del sottoinsieme associato.

{
  "primary": "https://primary.com",
  "associatedSites": ["https://associate1.com", "https://associate2.com", "https://associate3.com"]
}

I set di siti web correlati sono elencati in un file JSON pubblico ospitato su GitHub. Questa è la fonte canonica per tutti i set approvati. I browser utilizzano questo file per determinare se i siti appartengono o meno allo stesso insieme di siti web correlati.

Solo chi ha il controllo amministrativo di un dominio può creare un insieme con quel dominio. I mittenti sono tenuti a dichiarare la relazione tra ogni "membro del set" e il relativo "set principale". I membri del set possono includere una gamma di diversi tipi di domini e devono far parte di un sottoinsieme basato su un caso d'uso.

Se la tua applicazione dipende dall'accesso ai cookie cross-site (chiamati anche cookie di terze parti) su siti all'interno dello stesso insieme di siti web correlati, puoi utilizzare l'API Storage Access (SAA) e l'API requestStorageAccessFor per richiedere l'accesso a questi cookie. A seconda del sottoinsieme di cui fa parte ogni sito, il browser potrebbe gestire la richiesta in modo diverso.

Per scoprire di più sulla procedura e sui requisiti per l'invio di set, consulta le linee guida per l'invio. I set inviati verranno sottoposti a vari controlli tecnici per convalidare gli invii.

Casi d'uso degli insiemi di siti web correlati

Gli insiemi di siti web correlati sono adatti ai casi in cui un'organizzazione ha bisogno di una forma di identità condivisa su diversi siti di primo livello.

Ecco alcuni casi d'uso per gli insiemi di siti web correlati:

• Personalizzazione per paese. Sfruttare siti localizzati facendo affidamento su un'infrastruttura condivisa (example.co.uk potrebbe fare affidamento su un servizio ospitato da example.ca).
• Integrazione del dominio di servizio. Sfruttando domini di servizio con cui gli utenti non interagiscono direttamente, ma che forniscono servizi nei siti della stessa organizzazione (ad esempio example-cdn.com).
• Separazione dei contenuti utente. Accesso ai dati su domini diversi che separano i contenuti caricati dagli utenti dagli altri contenuti del sito per motivi di sicurezza, consentendo al dominio in sandbox di accedere ai cookie di autenticazione (e ad altri). Se pubblichi contenuti caricati dagli utenti inattivi, potresti anche essere in grado di ospitarli in modo sicuro sullo stesso dominio seguendo le best practice.
  • Contenuti autenticati incorporati. Supporto dei contenuti incorporati nelle proprietà affiliate (video, documenti o risorse limitati all'utente che ha eseguito l'accesso al sito di primo livello).
• Accedi. Supporto dell'accesso nelle proprietà affiliate. L'API FedCM potrebbe essere adatta anche per alcuni casi d'uso.
• Analytics. Implementazione di analisi e misurazioni dei percorsi degli utenti nelle proprietà affiliate per migliorare la qualità dei servizi.

Dettagli di integrazione degli insiemi di siti web correlati

API Storage Access

L'API Storage Access (SAA) consente ai contenuti incorporati multiorigine di accedere allo spazio di archiviazione a cui normalmente avrebbero accesso solo in un contesto proprietario.

Le risorse incorporate possono utilizzare i metodi SAA per verificare se hanno attualmente accesso allo spazio di archiviazione e per richiedere l'accesso allo user agent.

Quando i cookie di terze parti sono bloccati, ma gli insiemi di siti web correlati (RWS) sono attivi, Chrome concederà automaticamente l'autorizzazione nei contesti intra-RWS e mostrerà una richiesta all'utente in caso contrario. Un "contesto intra-RWS" è un contesto, ad esempio un iframe, il cui sito incorporato e sito di primo livello si trovano nello stesso RWS.

Controllare e richiedere l'accesso allo spazio di archiviazione

Per verificare se attualmente hanno accesso allo spazio di archiviazione, i siti incorporati possono utilizzare il metodo Document.hasStorageAccess().

Il metodo restituisce una promessa che si risolve con un valore booleano che indica se il documento ha già accesso ai suoi cookie o meno. La promessa restituisce anche true se l'iframe ha la stessa origine del frame principale.

Per richiedere l'accesso ai cookie in un contesto cross-site, i siti incorporati possono utilizzare Document.requestStorageAccess() (rSA).

L'API requestStorageAccess() deve essere chiamata dall'interno di un iframe. L'iframe deve aver appena ricevuto un'interazione dell'utente (un gesto dell'utente, richiesto da tutti i browser), ma Chrome richiede inoltre che, in un momento qualsiasi degli ultimi 30 giorni, l'utente abbia visitato il sito proprietario dell'iframe e abbia interagito specificamente con il sito, come documento di primo livello, non in un iframe.

requestStorageAccess() restituisce una promessa che viene risolta se l'accesso allo spazio di archiviazione è stato concesso. La promessa viene rifiutata, con l'indicazione del motivo, se l'accesso è stato negato per qualsiasi motivo.

requestStorageAccessFor in Chrome

L'API Storage Access consente ai siti incorporati di richiedere l'accesso allo spazio di archiviazione solo all'interno degli elementi <iframe> che hanno ricevuto l'interazione dell'utente.

Ciò pone delle sfide nell'adozione dell'API Storage Access per i siti di primo livello che utilizzano immagini o tag script cross-site che richiedono cookie.

Per risolvere questo problema, Chrome ha implementato un modo per consentire ai siti di primo livello di richiedere l'accesso allo spazio di archiviazione per conto di origini specifiche con Document.requestStorageAccessFor() (rSAFor).

 document.requestStorageAccessFor('https://target.site')

L'API requestStorageAccessFor() deve essere chiamata da un documento di primo livello. Inoltre, il documento deve aver appena ricevuto un'interazione da parte dell'utente. A differenza di requestStorageAccess(), Chrome non verifica un'interazione in un documento di primo livello negli ultimi 30 giorni perché l'utente si trova già sulla pagina.

Controllare le autorizzazioni di accesso allo spazio di archiviazione

L'accesso ad alcune funzionalità del browser, come la fotocamera o la geolocalizzazione, si basa sulle autorizzazioni concesse dall'utente. L'API Permissions fornisce un modo per controllare lo stato dell'autorizzazione per accedere a un'API, ovvero se è stata concessa, negata o richiede una qualche forma di interazione dell'utente, ad esempio fare clic su un prompt o interagire con la pagina.

Puoi eseguire query sullo stato dell'autorizzazione utilizzando navigator.permissions.query().

Per controllare l'autorizzazione di accesso allo spazio di archiviazione per il contesto corrente, devi passare la stringa 'storage-access':

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

Per controllare l'autorizzazione di accesso all'archiviazione per un'origine specificata, devi trasmettere la stringa 'top-level-storage-access':

navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'})

Tieni presente che, per proteggere l'integrità dell'origine incorporata, questo controllo verifica solo le autorizzazioni concesse dal documento di primo livello utilizzando document.requestStorageAccessFor.

A seconda che l'autorizzazione possa essere concessa automaticamente o richieda un gesto dell'utente, verrà restituito prompt o granted.

Modello per frame

Le concessioni rSA vengono applicate per frame. Le concessioni rSA e rSAFor vengono trattate come autorizzazioni separate.

Ogni nuovo frame dovrà richiedere l'accesso allo spazio di archiviazione singolarmente e l'accesso verrà concesso automaticamente. Solo la prima richiesta richiede l'interazione dell'utente, qualsiasi richiesta successiva avviata dall'iframe, come la navigazione o le sottorisorse, non dovrà attendere l'interazione dell'utente, poiché questa verrà concessa per la sessione di navigazione dalla richiesta iniziale.

L'aggiornamento, il ricaricamento o la ricreazione dell'iframe richiederanno di richiedere nuovamente l'accesso.

Requisiti dei cookie

I cookie devono specificare gli attributi SameSite=None e Secure come rSA solo fornisce l'accesso per i cookie già contrassegnati per l'utilizzo in contesti cross-site.

I cookie con SameSite=Lax, SameSite=Strict o senza un attributo SameSite sono destinati esclusivamente all'utilizzo proprietario e non verranno mai condivisi in un contesto cross-site indipendentemente dalla crittografia RSA.

Sicurezza

Per rSAFor, le richieste di risorse secondarie richiedono intestazioni Cross-Origin Resource Sharing (CORS) o l'attributo crossorigin nelle risorse, garantendo l'attivazione esplicita.

Esempi di implementazione

Richiedere l'accesso allo spazio di archiviazione da un iframe multiorigine incorporato

Controllare se hai accesso allo spazio di archiviazione

Per verificare se hai già accesso allo spazio di archiviazione, utilizza document.hasStorageAccess().

Se la promessa restituisce true, puoi accedere allo spazio di archiviazione nel contesto multiorigine. Se restituisce il valore false, devi richiedere l'accesso allo spazio di archiviazione.

document.hasStorageAccess().then((hasAccess) => {
    if (hasAccess) {
      // You can access storage in this context
    } else {
      // You have to request storage access
    }
});

Richiedere l'accesso allo spazio di archiviazione

Se devi richiedere l'accesso allo spazio di archiviazione, controlla prima l'autorizzazione di accesso allo spazio di archiviazione navigator.permissions.query({name: 'storage-access'}) per verificare se richiede un gesto dell'utente o se può essere concessa automaticamente.

Se l'autorizzazione è granted, puoi chiamare document.requestStorageAccess() e l'operazione dovrebbe riuscire senza un gesto dell'utente.

Se lo stato dell'autorizzazione è prompt, devi avviare la chiamata document.requestStorageAccess() dopo un gesto dell'utente, ad esempio un clic sul pulsante.

Esempio:

navigator.permissions.query({name: 'storage-access'}).then(res => {
  if (res.state === 'granted') {
    // Permission has already been granted
    // You can request storage access without any user gesture
    rSA();
  } else if (res.state === 'prompt') {
    // Requesting storage access requires user gesture
    // For example, clicking a button
    const btn = document.createElement("button");
    btn.textContent = "Grant access";
    btn.addEventListener('click', () => {
      // Request storage access
      rSA();
    });
    document.body.appendChild(btn);
  }
});

function rSA() {
  if ('requestStorageAccess' in document) {
    document.requestStorageAccess().then(
      (res) => {
        // Use storage access
      },
      (err) => {
        // Handle errors
      }
    );
  }
}

Le richieste successive dall'interno del frame, delle navigazioni o delle risorse secondarie avranno automaticamente l'autorizzazione per accedere ai cookie cross-site. hasStorageAccess() restituisce true e i cookie cross-site dello stesso insieme di siti web correlati vengono inviati a queste richieste senza chiamate JavaScript aggiuntive.

Siti di primo livello che richiedono l'accesso ai cookie per conto di siti cross-origin

I siti di primo livello possono utilizzare requestStorageAccessFor() per richiedere l'accesso allo spazio di archiviazione per conto di origini specifiche.

hasStorageAccess() controlla solo se il sito che lo chiama ha accesso allo spazio di archiviazione, quindi un sito di primo livello può controllare le autorizzazioni per un'altra origine.

Per scoprire se all'utente verrà chiesto o se l'accesso allo spazio di archiviazione è già stato concesso all'origine specificata, chiama navigator.permissions.query({name: 'top-level-storage-access', requestedOrigin: 'https://target.site'}).

Se l'autorizzazione è granted, puoi chiamare document.requestStorageAccessFor('https://target.site'). Deve essere eseguito senza un gesto dell'utente.

Se l'autorizzazione è prompt, dovrai collegare la chiamata document.requestStorageAccessFor('https://target.site') all'azione dell'utente, ad esempio un clic sul pulsante.

Esempio:

navigator.permissions.query({name:'top-level-storage-access',requestedOrigin: 'https://target.site'}).then(res => {
  if (res.state === 'granted') {
    // Permission has already been granted
    // You can request storage access without any user gesture
    rSAFor();
  } else if (res.state === 'prompt') {
    // Requesting storage access requires user gesture
    // For example, clicking a button
    const btn = document.createElement("button");
    btn.textContent = "Grant access";
    btn.addEventListener('click', () => {
      // Request storage access
      rSAFor();
    });
    document.body.appendChild(btn);
  }
});

function rSAFor() {
  if ('requestStorageAccessFor' in document) {
    document.requestStorageAccessFor().then(
      (res) => {
        // Use storage access
      },
      (err) => {
        // Handle errors
      }
    );
  }
}

Dopo una chiamata requestStorageAccessFor() riuscita, le richieste cross-site includeranno i cookie se includono CORS o l'attributo crossorigin, quindi i siti potrebbero voler attendere prima di attivare una richiesta.

Le richieste devono utilizzare l'opzione credentials: 'include' e le risorse devono includere l'attributo crossorigin="use-credentials".

function checkCookie() {
    fetch('https://related-website-sets.glitch.me/getcookies.json', {
        method: 'GET',
        credentials: 'include'
      })
      .then((response) => response.json())
      .then((json) => {
      // Do something
      });
  }

Come eseguire test in locale

Prerequisiti

Per testare i set di siti web correlati a livello locale, utilizza Chrome 119 o versioni successive avviate dalla riga di comando e attiva il test-third-party-cookie-phaseout flag di Chrome.

Attivare il flag di Chrome

Per attivare il flag di Chrome necessario, vai a chrome://flags#test-third-party-cookie-phaseout dalla barra degli indirizzi e imposta il flag su Enabled. Assicurati di riavviare il browser dopo aver modificato i flag.

Avvia Chrome con un insieme di siti web correlati locale

Per avviare Chrome con un insieme di siti web correlati dichiarato localmente, crea un oggetto JSON che contenga gli URL che fanno parte di un insieme e passalo a --use-related-website-set.

Scopri di più su come eseguire Chromium con flag.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

Esempio

Per attivare i set di siti web correlati localmente, devi attivare test-third-party-cookie-phaseout in chrome://flags e avviare Chrome dalla riga di comando con il flag --use-related-website-set con l'oggetto JSON contenente gli URL che fanno parte di un set.

--use-related-website-set="{\"primary\": \"https://related-website-sets.glitch.me\", \"associatedSites\": [\"https://rws-member-1.glitch.me\"]}" \
https://related-website-sets.glitch.me/

Verifica di avere accesso ai cookie cross-site

Chiama le API (rSA o rSAFor) dai siti in fase di test e convalida l'accesso ai cookie cross-site.

Procedura di invio degli insiemi di siti web correlati

Segui questi passaggi per dichiarare la relazione tra i domini e specificare a quale sottoinsieme appartengono.

1. Identificare il tuo RWS

Identifica i domini pertinenti, inclusi set primary e set members che faranno parte dell'insieme di siti web correlati. Identifica anche a quale tipo di sottoinsieme appartiene ogni membro del set.

2. Crea l'invio RWS

Crea una copia locale (clone o fork) del repository GitHub. In un nuovo ramo, apporta le modifiche al file related_website_sets.JSON per riflettere il tuo set. Per assicurarti che il set abbia la formattazione e la struttura JSON corrette, puoi utilizzare lo strumento di generazione JSON.

3. Assicurati che il tuo RWS soddisfi i requisiti tecnici

Assicurati che siano soddisfatti i requisiti di formazione del set e i requisiti di convalida del set.

4. Testare RWS localmente

Prima di creare una pull request (PR) per inviare il set, testa l'invio localmente per assicurarti che superi tutti i controlli richiesti.

5. Inviare l'insieme di siti web correlati

Invia l'insieme di siti web correlati creando una richiesta pull al file related_website_sets.JSON in cui Chrome ospita l'elenco canonico degli insiemi di siti web correlati. Per creare richieste di pull è necessario un account GitHub e dovrai firmare un Contratto di licenza del collaboratore (CLA) prima di poter contribuire all'elenco.

Una volta creata la richiesta pull, viene completata una serie di controlli per garantire che i requisiti del passaggio 3 siano soddisfatti, ad esempio che tu abbia firmato il contratto di licenza del collaboratore e che il file .well-known sia valido.

In caso di esito positivo, la richiesta pull indicherà che i controlli sono stati superati. Le PR approvate verranno unite manualmente in batch all'elenco canonico di insiemi di siti web correlati una volta alla settimana (il martedì alle 12:00, ora della costa orientale degli Stati Uniti). Se uno dei controlli non va a buon fine, il mittente riceverà una notifica tramite un errore della richiesta pull su GitHub. L'autore della richiesta può correggere gli errori e aggiornare la richiesta pull, tenendo presente che:

• Se la PR non va a buon fine, un messaggio di errore fornirà ulteriori informazioni sul motivo per cui l'invio potrebbe non essere andato a buon fine. (esempio).
• Tutti i controlli tecnici che regolano gli invii dei set vengono eseguiti su GitHub e di conseguenza tutti gli errori di invio risultanti dai controlli tecnici saranno visibili su GitHub.

Policy aziendali

Chrome ha implementato due criteri per soddisfare le esigenze degli utenti aziendali:

• I sistemi che potrebbero non essere in grado di integrarsi con gli insiemi di siti web correlati possono disattivare la funzionalità di insiemi di siti web correlati in tutte le istanze aziendali di Chrome con il RelatedWebsiteSetsEnabled criterio.
  • Alcuni sistemi aziendali hanno siti solo interni (ad esempio una intranet) con domini registrabili diversi da quelli presenti nel loro insieme di siti web correlati. Se devono trattare questi siti come parte del proprio insieme di siti web correlati senza esporli pubblicamente (in quanto i domini potrebbero essere riservati), possono aumentare o sostituire l'elenco pubblico di insiemi di siti web correlati con il criterio RelatedWebsiteSetsOverrides.

Chrome risolve qualsiasi intersezione dei set pubblici e aziendali in uno dei due modi, a seconda che siano specificati replacements o additions.

Ad esempio, per il set pubblico {primary: A, associated: [B, C]}:

Risolvere i problemi relativi agli insiemi di siti web correlati

"Prompt utente" e "gesto dell'utente"

Un "prompt utente" e un "gesto dell'utente" sono due cose diverse. Chrome non mostrerà un prompt di autorizzazione agli utenti per i siti che fanno parte dello stesso insieme di siti web correlati, ma Chrome richiede comunque che l'utente abbia interagito con la pagina. Prima di concedere l'autorizzazione, Chrome richiede un gesto dell'utente, chiamato anche "interazione utente" o "attivazione utente". Ciò è dovuto al fatto che l'utilizzo dell'API Storage Access al di fuori di un contesto di set di siti web correlati (ovvero requestStorageAccess()) richiede anche un gesto dell'utente, a causa dei principi di progettazione della piattaforma web.

Accedere ai cookie o allo spazio di archiviazione di altri siti

Gli insiemi di siti web correlati non uniscono lo spazio di archiviazione per siti diversi: consentono solo chiamate requestStorageAccess() più semplici (senza prompt). I set di siti web correlati riducono solo l'attrito per l'utente nell'utilizzo dell'API Storage Access, ma non dettano cosa fare una volta ripristinato l'accesso. Se A e B sono siti diversi nello stesso insieme di siti web correlati e A incorpora B, B può chiamare requestStorageAccess() e accedere allo spazio di archiviazione proprietario senza chiedere all'utente. Gli insiemi di siti web correlati non eseguono alcuna comunicazione tra siti. Ad esempio, la configurazione di un set di siti web correlati non comporterà l'invio dei cookie appartenenti a B ad A. Se vuoi condividere questi dati, dovrai farlo tu, ad esempio inviando un window.postMessage da un iframe B a un iframe A.

Accesso ai cookie non partizionati per impostazione predefinita

I set di siti web correlati non consentono l'accesso implicito ai cookie non partizionati senza richiamare alcuna API. I cookie cross-site non sono disponibili per impostazione predefinita all'interno del set; i set di siti web correlati consentono solo ai siti all'interno del set di ignorare la richiesta di autorizzazione dell'API Storage Access. Un iframe deve chiamare document.requestStorageAccess() se vuole accedere ai propri cookie oppure la pagina di primo livello può chiamare document.requestStorageAccessFor().

Condividi feedback

L'invio di un set su GitHub e l'utilizzo dell'API Storage Access e dell'API requestStorageAccessFor sono opportunità per condividere la tua esperienza con la procedura e qualsiasi problema riscontrato.

Per partecipare alle discussioni sugli insiemi di siti web correlati:

• Iscriviti alla mailing list pubblica degli insiemi di siti web correlati.
  • Segnala problemi e segui la discussione nel repository GitHub degli insiemi di siti web correlati.