Controllare le funzionalità del browser con il criterio di autorizzazione

Gestisci il modo in cui la tua pagina e gli iframe di terze parti sulla tua pagina hanno accesso alle funzionalità del browser.

Kevin K. Lee

I criteri di autorizzazione, precedentemente noti come Criteri delle funzionalità, consentono allo sviluppatore di controllare le funzionalità del browser disponibili per una pagina, i relativi iframe e le relative risorse secondarie, dichiarando un insieme di criteri che il browser dovrà applicare. Questi criteri vengono applicati alle origini fornite in un elenco di origini dell'intestazione della risposta. L'elenco delle origini può contenere le stesse origini e/o più origini e consente allo sviluppatore di controllare l'accesso proprietario e di terze parti alle funzionalità del browser.

L'utente ha la decisione finale di consentire l'accesso a funzionalità più potenti e deve fornire l'autorizzazione esplicita tramite un prompt.

Le norme relative alle autorizzazioni consentono al sito di primo livello di definire l'utilizzo che il sito stesso e le terze parti intendono utilizzare, sollevando l'utente dall'onere di determinare se la richiesta di accesso alle funzionalità è legittima o meno. Ad esempio, se blocchi la funzionalità di geolocalizzazione per tutte le terze parti tramite i criteri sulle autorizzazioni, lo sviluppatore può essere certo che nessuna terza parte potrà accedere alla geolocalizzazione dell'utente.

Modifiche alle norme relative alle autorizzazioni

Le norme relative alle autorizzazioni erano in precedenza note come norme relative alle funzionalità. I concetti chiave rimangono gli stessi, ma sono state apportate alcune modifiche importanti oltre al nome.

Utilizzo dei campi strutturati

I campi strutturati forniscono un insieme di strutture di dati comuni per standardizzare l'analisi e la serializzazione dei valori dei campi di intestazione HTTP. Scopri di più sui campi strutturati nel post del blog di Fastly, "Migliorare il protocollo HTTP con i campi di intestazione strutturati".

  geolocation 'self' https://example.com; camera 'none'

  geolocation=(self "https://example.com"), camera=()

Combina le intestazioni con l'attributo iframe allow

Con le norme relative alle funzionalità, puoi aggiungere la funzionalità a un frame multiorigine aggiungendo l'origine all'elenco di origini dell'intestazione o aggiungendo un attributo allow al tag iframe. Con i criteri relativi alle autorizzazioni, se aggiungi un frame multiorigine all'elenco di origini, il tag iframe per quell'origine deve includere l'attributo allow. Se la risposta non contiene un'intestazione Criteri relativi alle autorizzazioni, l'elenco di origini viene considerato con il valore predefinito di *. L'aggiunta dell'attributo allow all'iframe consente l'accesso alla funzionalità.

Di conseguenza, consigliamo agli sviluppatori di impostare esplicitamente l'intestazione Criteri relativi alle autorizzazioni nella risposta, in modo che gli iframe multiorigine che non sono elencati nell'elenco di origini non possano accedere a questa funzionalità, anche se è presente allow.

I criteri relativi alle funzionalità potranno continuare a essere utilizzati dopo la versione 88 di Chrome, ma fungeranno da alias per i criteri relativi alle autorizzazioni. A parte la sintassi, non c'è alcuna differenza nella logica. Se vengono utilizzate insieme le intestazioni Norme relative alle autorizzazioni e Norme relative alle funzionalità, l'intestazione Permissions-Policy avrà una priorità maggiore e sovrascriverà il valore fornito dall'intestazione Feature-Policy.

Come faccio a utilizzare i criteri sulle autorizzazioni?

Panoramica rapida

Prima di approfondire l'argomento, diamo una rapida occhiata a uno scenario comune in cui sei il proprietario di un sito web e vuoi controllare il modo in cui il tuo sito e il codice di terze parti utilizzano le funzionalità del browser.

• Il tuo sito è https://your-site.example.
• Il tuo sito incorpora un iframe dalla stessa origine (https://your-site.example).
• Il tuo sito incorpora un iframe di https://trusted-site.example che ritieni attendibile.
• Sul tuo sito vengono visualizzati anche annunci pubblicati da https://ad.example.
• Vuoi consentire la geolocalizzazione solo per il tuo sito e per il sito attendibile, non per l'annuncio.

In questo caso, utilizza la seguente intestazione:

Permissions-Policy: geolocation=(self "https://trusted-site.example")

Inoltre, imposta esplicitamente l'attributo allow sul tag iframe per il sito attendibile:

<iframe src="https://trusted-site.example" allow="geolocation">

In questo esempio, l'elenco delle origini dell'intestazione consente solo al tuo sito (self) e trusted-site.example di utilizzare la funzionalità di geolocalizzazione. ad.example non è autorizzato a utilizzare la geolocalizzazione.

1. Il tuo sito your-site.example è autorizzato a utilizzare la funzionalità di geolocalizzazione con il consenso dell'utente.
2. Un iframe della stessa origine (your-site.example) può utilizzare la funzionalità senza l'utilizzo dell'attributo allow.
3. Un iframe pubblicato da un sottodominio diverso (subdomain.your-site-example) che non è stato aggiunto all'elenco di origine e con l'attributo allow impostato nel tag iframe, viene bloccato per l'utilizzo della funzionalità. Sottodomini diversi sono considerati dello stesso sito, ma multiorigine.
4. Un iframe multiorigine (trusted-site.example) aggiunto all'elenco di origini e con l'attributo allow impostato nel tag iframe può utilizzare la funzionalità.
5. A un iframe multiorigine (trusted-site.example) aggiunto all'elenco di origini senza l'attributo allow viene impedito l'utilizzo della funzionalità.
6. A un iframe multiorigine (ad.example) non aggiunto all'elenco di origini viene impedito l'utilizzo della funzionalità, anche se l'attributo allow è incluso nel tag iframe.

Intestazione della risposta HTTP Permissions-Policy

Permissions-Policy: <feature>=(<token>|<origin(s)>)

Utilizza un'intestazione Permissions-Policy nella risposta del server per impostare le origini consentite per una funzionalità. Il valore dell'intestazione può utilizzare una combinazione di token e stringhe di origini. I token disponibili sono * per tutte le origini e self per la stessa origine.

Se l'intestazione riguarda più elementi, separali con una virgola. Se elenchi più origini, separa ciascuna origine nell'elenco delle origini con uno spazio. Per le intestazioni che elencano un'origine che è una richiesta multiorigine, il tag iframe deve includere l'attributo allow.

Ecco alcune coppie chiave-valore di esempio:

• Sintassi: [FEATURE]=*
  • Criterio applicato a tutte le origini
  • Esempio: geolocation=*
• Sintassi: [FEATURE]=(self)
  • Criterio applicato alla stessa origine
  • Esempio: geolocation=(self)
• Sintassi: [FEATURE]=(self [ORIGIN(s)])
  • Criterio applicato alla stessa origine e alle origini specificate
  • Esempio: geolocation=(self "https://a.example" "https://b.example")
  • self è una forma abbreviata di https://your-site.example
• Sintassi: [FEATURE]=([ORIGIN(s)])
  • Criterio applicato alla stessa origine e alle origini specificate
  • Esempio: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
  • Quando si utilizza questa sintassi, una delle origini deve essere l'origine dell'incorporamento. Se alla pagina stessa non vengono concesse le autorizzazioni, anche gli iframe incorporati in quella pagina verranno bloccati anche se vengono aggiunti all'elenco di origine perché il criterio delle autorizzazioni delega le autorizzazioni. Puoi anche utilizzare il token self.
• Sintassi: [FEATURE]=()
  • Funzionalità bloccata per tutte le origini
  • Esempio: geolocation=()

Sottodomini e percorsi diversi

Diversi sottodomini, come https://your-site.example e https://subdomain.your-site.example, sono considerati stesso sito ma multiorigine. Pertanto, l'aggiunta di un sottodominio nell'elenco di origine non consente l'accesso a un altro sottodominio dello stesso sito. Ogni sottodominio incorporato che vuole utilizzare la funzionalità deve essere aggiunto separatamente all'elenco di origine. Ad esempio, se è consentito l'accesso agli argomenti di navigazione dell'utente per la stessa origine solo con l'intestazione Permissions-Policy: browsing-topics=(self), un iframe di un sottodominio diverso dello stesso sito, https://subdomain.your-site.example, non avrà accesso agli argomenti.

Percorsi diversi, come https://your-site.example e https://your-site.example/embed, sono considerati della stessa origine e non è necessario che percorsi diversi siano elencati nell'elenco di origini.

Attributo iframe allow

Per l'utilizzo multiorigine, un iframe richiede l'attributo allow nel tag per ottenere l'accesso alla funzionalità.

Sintassi: <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>

Ad esempio:

<iframe src="https://trusted-site.example" allow="geolocation">

Gestione della navigazione negli iframe

Per impostazione predefinita, se un iframe passa a un'altra origine, il criterio non viene applicato all'origine a cui va l'iframe. Indicando nell'attributo allow l'origine a cui viene indirizzato l'iframe, la norma relativa alle autorizzazioni applicata all'iframe originale verrà applicata all'origine a cui va l'iframe.

<iframe src="https://trusted-site.example" allow="geolocation https://trusted-site.example https://trusted-navigated-site.example">

Puoi vederlo in azione visitando la demo della navigazione iframe.

Esempi di configurazioni dei criteri di autorizzazione

Gli esempi delle seguenti configurazioni sono disponibili nella demo.

Funzionalità consentita su tutte le origini

Permissions-Policy: geolocation=*

<iframe src="https://trusted-site.example" allow="geolocation">
<iframe src="https://ad.example" allow="geolocation">

Quando l'elenco delle origini è impostato sul token *, la funzionalità è consentita per tutte le origini presenti nella pagina, compresa la stessa e tutti gli iframe. In questo esempio, tutto il codice pubblicato da https://your-site.example e i codici pubblicati da iframe e https://ad.example https://trusted-site.example hanno accesso alla funzionalità di geolocalizzazione nel browser dell'utente. Ricorda che l'attributo allow deve essere impostato anche sull'iframe stesso e aggiungere l'origine all'elenco di origini dell'intestazione.

Questa configurazione può essere visualizzata nella demo.

Funzionalità consentita solo sulla stessa origine

Permissions-Policy: geolocation=(self)

Il token self consente l'utilizzo della geolocalizzazione solo verso la stessa origine. Le origini multiorigine non avranno accesso alla funzionalità. In questo esempio, solo https://trusted-site.example (self) avrà accesso alla geolocalizzazione. Utilizza questa sintassi se vuoi che la funzionalità sia disponibile solo per la tua pagina e per nessun altro.

Questa configurazione può essere visualizzata nella demo.

Funzionalità consentita su stessa origine e su più origini specifiche

Permissions-Policy: geolocation=(self "https://trusted-site.example")

Questa sintassi consente l'utilizzo della geolocalizzazione sia per sé (https://your-site.example) che per https://trusted-site.example. Ricorda di aggiungere esplicitamente l'attributo allow al tag iframe. Se è presente un altro iframe con <iframe src="https://ad.example" allow="geolocation">, https://ad.example non avrà accesso alla funzionalità di geolocalizzazione. Solo la pagina originale e https://trusted-site.example che sono elencati nell'elenco di origine insieme all'attributo allow nel tag iframe avranno accesso alla funzionalità dell'utente.

Questa configurazione può essere visualizzata nella demo.

Funzionalità bloccata su tutte le origini

Permissions-Policy: geolocation=()

Con un elenco delle origini vuoto, la funzionalità viene bloccata per tutte le origini. Questa configurazione può essere visualizzata nella demo.

Utilizzare l'API JavaScript

L'API JavaScript esistente delle norme relative alle funzionalità è stata trovata come un oggetto nel documento o nell'elemento (document.featurePolicy or element.featurePolicy). L'API JavaScript per le norme relative alle autorizzazioni non è stata ancora implementata.

L'API Feature Policy può essere utilizzata per i criteri impostati dalle norme sulle autorizzazioni, con alcune limitazioni. Rimangono rimangono domande relative a un'implementazione dell'API JavaScript ed è stata fatta una proposta per spostare la logica nell'API Permissions. Partecipa alla discussione, se hai qualche idea.

featurePolicy.allowsFeature(feature)

• Restituisce true se la funzionalità è consentita per l'utilizzo dell'origine predefinita.
• Il comportamento è lo stesso sia per i criteri impostati dal criterio relativo alle autorizzazioni sia per i criteri precedenti relativi alle funzionalità
• Quando allowsFeature() viene richiamato su un elemento iframe (iframeEl.featurePolicy.allowsFeature('geolocation')), il valore restituito indica se nell'iframe è impostato l'attributo allow

featurePolicy.allowsFeature(feature, origin)

• Restituisce true se la funzionalità è consentita per l'origine specificata.
• Se il metodo viene chiamato su document, questo metodo non indica più se la funzionalità è consentita per l'origine specificata, come ha fatto l'Informativa sulle funzionalità. Ora, questo metodo indica che è possibile che la caratteristica sia consentita a quell'origine. Devi eseguire un ulteriore controllo per verificare che l'attributo allow dell'iframe sia impostato o meno. Lo sviluppatore deve eseguire un controllo aggiuntivo per l'attributo allow nell'elemento iframe per determinare se la funzionalità è consentita per l'origine di terze parti.

Verifica la presenza di funzionalità in un iframe con l'oggetto element

Puoi utilizzare element.allowsFeature(feature) che tiene conto dell'attributo allow, a differenza di document.allowsFeature(feature, origin) che non lo fa.

const someIframeEl = document.getElementById('some-iframe')
const isCameraFeatureAllowed = someIframeEl.featurePolicy.allowsFeature('camera')

featurePolicy.allowedFeatures()

• Restituisce un elenco di funzionalità consentite per l'utilizzo dell'origine predefinita.
• Il comportamento è lo stesso per i criteri impostati dalle norme relative alle autorizzazioni e quelle per le funzionalità
• Quando il nodo associato è un iframe, viene preso in considerazione l'attributo allow.

featurePolicy.features()

• Restituisce un elenco di funzionalità disponibili nel browser.
• Il comportamento è lo stesso per i criteri impostati dalle norme relative alle autorizzazioni e quelle per le funzionalità

Integrazione di Chrome DevTools

Scopri come funzionano i criteri relativi alle autorizzazioni in DevTools.

1. Apri Chrome DevTools.
2. Apri il riquadro Applicazione per verificare le funzionalità consentite e quelle non consentite di ogni frame.
3. Nella barra laterale, seleziona il frame che vuoi ispezionare. Ti verranno presentati un elenco di funzionalità che il frame selezionato può utilizzare e un elenco di funzionalità bloccate in quel frame.

Migrazione dalle norme sulle funzionalità

Se al momento utilizzi l'intestazione Feature-Policy, puoi implementare i seguenti passaggi per eseguire la migrazione al criterio delle autorizzazioni.

Sostituisci le intestazioni dei criteri delle funzionalità con le intestazioni dei criteri delle autorizzazioni

Poiché le intestazioni dei criteri relative alle funzionalità sono supportate solo nei browser basati su Chromium e le intestazioni dei criteri di autorizzazione sono supportate da Chrome 88, è consigliabile aggiornare le intestazioni esistenti con i criteri relativi alle autorizzazioni.

Feature-Policy:
  autoplay *;
  geolocation 'self';
  camera 'self' 'https://trusted-site.example';
  fullscreen 'none';

Permissions-Policy:
  autoplay=*,
  geolocation=(self),
  camera=(self "https://trusted-site.example"),
  fullscreen=()

Aggiorna l'utilizzo di document.allowsFeature(feature, origin)

Se utilizzi il metodo document.allowsFeature(feature, origin) per verificare le funzionalità consentite per gli iframe, utilizza il metodo allowsFeature(feature) associato all'elemento iframe e non all'elemento document contenitore. Il metodo element.allowsFeature(feature) tiene conto dell'attributo allow, mentre document.allowsFeature(feature, origin) no.

Controllo dell'accesso alle funzionalità con document in corso...

Per continuare a utilizzare document come nodo di base, devi eseguire un ulteriore controllo per l'attributo allow nel tag iframe.

<iframe id="some-iframe" src="https://example.com" allow="camera"></iframe>

Permissions-Policy: camera=(self "https://example.com")

const isCameraPolicySet = document.featurePolicy.allowsFeature('camera', 'https://example.com')

const someIframeEl = document.getElementById('some-iframe')
const hasCameraAttributeValue = someIframeEl.hasAttribute('allow')
&& someIframeEl.getAttribute('allow').includes('camera')

const isCameraFeatureAllowed = isCameraPolicySet && hasCameraAttributeValue

Anziché aggiornare il codice esistente utilizzando document, ti consigliamo di chiamare allowsFeature() sull'oggetto element come nell'esempio precedente.

API di reporting

L'API di reporting fornisce un meccanismo di segnalazione per le applicazioni web in modo coerente e l'API di reporting per le violazioni delle norme relative alle autorizzazioni è disponibile come funzionalità sperimentale.

Se vuoi testare la funzionalità sperimentale, segui la procedura dettagliata e attiva il flag in chrome://flags/#enable-experimental-web-platform-features. Con il flag abilitato, puoi osservare le violazioni dei criteri relativi alle autorizzazioni in DevTools nella scheda Applicazione:

L'esempio seguente mostra come deve essere creata l'intestazione dell'API di reporting:

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;

Nell'implementazione attuale, puoi ricevere report sulle violazioni delle norme da qualsiasi violazione che si verifica all'interno di quel frame configurando un endpoint denominato "default" come nell'esempio precedente. I frame secondari richiederanno la propria configurazione dei report.

Scopri di più

Per una comprensione più approfondita dei criteri relativi alle autorizzazioni, consulta le seguenti risorse:

• Specifiche dei criteri di autorizzazione
• Spiegazione delle norme relative alle autorizzazioni
• Un elenco di funzionalità controllate dai criteri.