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 relativi alle autorizzazioni, precedentemente noti come Norme relative alle funzionalità, consentono allo sviluppatore di controllare le funzionalità del browser disponibili per una pagina, i suoi iframe e dichiarando un insieme di criteri che il browser dovrà applicare. Questi I 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 lo sviluppatore per controllare l'accesso proprietario e di terze parti alle funzionalità del browser.

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

Le norme relative alle autorizzazioni consentono al sito di primo livello di definire quale le parti interessate intendono utilizzare ed elimina l'onere per l'utente di determinare se la richiesta di accesso alla funzionalità è legittima o meno. Ad esempio, per bloccare la funzionalità di geolocalizzazione per tutte le terze parti tramite le norme relative alle autorizzazioni; lo sviluppatore può essere certo che nessuna terza parte otterrà l'accesso ai suoi geolocalizzazione.

Modifiche alle norme sulle autorizzazioni

Le norme relative alle autorizzazioni in precedenza erano note come norme sulle funzionalità. I concetti principali rimangono gli stessi, ma ci sono alcune modifiche importanti insieme 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, "Miglioramento di HTTP con i campi di intestazione strutturata".

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

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

Combina le intestazioni con l'attributo allow iframe

Con le norme relative alle funzionalità, puoi aggiungere la caratteristica a un frame multiorigine aggiungendo l'origine all'elenco di origini dell'intestazione o aggiungendo un attributo allow al tag iframe. Con le norme relative alle autorizzazioni, se aggiungi un frame multiorigine all'elenco delle origini, il tag iframe per quell'origine deve includere l'attributo allow. Se la risposta non contiene un'intestazione dei criteri relativi alle autorizzazioni, si considera che l'elenco delle origini abbia il valore predefinito *. L'aggiunta dell'attributo allow all'iframe consente di accedere alla funzionalità.

Pertanto, consigliamo agli sviluppatori di impostare esplicitamente l'intestazione Criteri delle autorizzazioni nella risposta, in modo che gli iframe multiorigine non elencati nell'elenco di origine vengano bloccati dall'accesso a questa funzionalità, anche se è presente allow.

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

Come faccio a utilizzare le norme 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 della stessa origine (https://your-site.example).
• Il tuo sito incorpora un iframe di https://trusted-site.example che ritieni attendibile.
• Sul tuo sito vengono mostrati 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 del 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 a 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 utilizzare l'attributo allow.
3. La funzionalità non può essere utilizzata per un iframe pubblicato da un sottodominio diverso (subdomain.your-site-example) che non è stato aggiunto all'elenco di origini e per il quale è impostato l'attributo allow nel tag iframe. Sottodomini diversi sono considerati nello 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 è autorizzato a utilizzare la funzionalità.
5. Un iframe multiorigine (trusted-site.example) aggiunto all'elenco delle origini, senza l'attributo allow, non può utilizzare la funzionalità.
6. Un iframe multiorigine (ad.example) che non è stato aggiunto all'elenco di origine è bloccato per 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 dal server per impostare le origini consentite per una caratteristica. Il valore dell'intestazione può prendere 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ù funzionalità, separale con una virgola. Se indichi più origini, separale con uno spazio. Per le intestazioni che indicano un'origine di una richiesta multiorigine, il tag iframe deve includere l'attributo allow.

Di seguito sono riportate 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 è un'abbreviazione 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 quella dell'incorporatore. Se alla pagina dell'incorporatore non vengono concesse le autorizzazioni, anche gli iframe incorporati al suo interno verranno bloccati anche se vengono aggiunti all'elenco di origini perché le autorizzazioni concesse dal criterio delle autorizzazioni. Puoi anche utilizzare il token self.
• Sintassi: [FEATURE]=()
  • Funzionalità bloccata per tutte le origini
  • Esempio: geolocation=()

Sottodomini e percorsi diversi

sottodomini diversi, come https://your-site.example e https://subdomain.your-site.example, sono considerati lo 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 delle origini. Ad esempio, se l'accesso agli argomenti di navigazione dell'utente è consentito alla 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, pertanto non è necessario elencare percorsi diversi nell'elenco delle origini.

Attributo iframe allow

Per l'utilizzo multiorigine, un iframe richiede l'attributo allow nel tag per poter accedere 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 raggiunge un'altra origine, la norma non viene applicata all'origine a cui accede l'iframe. Indicando l'origine a cui accede l'iframe nell'attributo allow, le norme relative alle autorizzazioni applicate all'iframe originale verranno applicate all'origine a cui indirizza l'iframe.

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

Puoi vedere l'impostazione in azione visitando la demo di navigazione dell'iframe.

Esempi di configurazioni dei criteri delle autorizzazioni

Puoi trovare alcuni esempi delle seguenti configurazioni 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">

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

Questa configurazione è visibile nella demo.

Funzionalità consentita solo sulla stessa origine

Permissions-Policy: geolocation=(self)

L'utilizzo del token self consente l'utilizzo di geolocalizzazione solo per 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 è visibile nella demo.

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

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

Questa sintassi consente l'utilizzo della geolocalizzazione sia per l'utente (https://your-site.example) che per quello di 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 funzione di geolocalizzazione. Solo la pagina originale e https://trusted-site.example elencati nell'elenco delle origini insieme all'attributo allow nel tag iframe avranno accesso alla funzionalità dell'utente.

Questa configurazione è visibile 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 è visibile nella demo.

Utilizzare l'API JavaScript

L'API JavaScript esistente di Feature Policy si trova come 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 relative alle autorizzazioni, con alcune limitazioni. Sono presenti rimanenti domande relative all'implementazione dell'API JavaScript ed è stata fatta una proposta di spostare la logica nell'API Permissions. Partecipa alla discussione se hai domande.

featurePolicy.allowsFeature(feature)

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

featurePolicy.allowsFeature(feature, origin)

• Restituisce true se la caratteristica è 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 il criterio sulle funzionalità. Questo metodo indica che è possibile consentire alla caratteristica di raggiungere quell'origine. Devi eseguire un'ulteriore verifica per verificare se nell'iframe è stato impostato o meno l'attributo allow. Lo sviluppatore deve eseguire un'ulteriore verifica dell'attributo allow nell'elemento iframe per determinare se la funzionalità è consentita per l'origine di terze parti.

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

Puoi utilizzare element.allowsFeature(feature) che prende in considerazione l'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 entrambi i criteri impostati dai criteri relativi alle autorizzazioni e dai criteri relativi alle funzionalità.
• Quando il nodo associato è un iframe, viene preso in considerazione l'attributo allow.

featurePolicy.features()

• Restituisce un elenco delle funzionalità disponibili nel browser.
• Il comportamento è lo stesso per entrambi i criteri impostati dai criteri relativi alle autorizzazioni e dai criteri relativi alle 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 per ogni frame.
3. Nella barra laterale, seleziona il frame che vuoi esaminare. Viene visualizzato un elenco delle funzionalità che il frame selezionato può utilizzare e un elenco delle funzionalità bloccate al suo interno.

Migrazione da Feature-Policy

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

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

Poiché le intestazioni dei criteri relativi alle funzionalità sono supportate solo nei browser basati su Chromium e le intestazioni dei criteri delle autorizzazioni sono supportate da Chrome 88, è sicuro aggiornare le intestazioni esistenti con il criterio relativo 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 il document contenitore. Il metodo element.allowsFeature(feature) tiene conto dell'attributo allow, al contrario di document.allowsFeature(feature, origin).

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

Per continuare a utilizzare document come nodo di base, devi eseguire un'ulteriore verifica dell'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

Invece di 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, mentre 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 delle autorizzazioni in DevTools nella scheda Applicazione:

L'esempio seguente mostra come potrebbe 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 per qualsiasi violazione che si verifica entro quel frame configurando un endpoint denominato "default" come nell'esempio precedente. I frame secondari richiederanno una propria configurazione dei report.

Scopri di più

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

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