Controlar os recursos do navegador com a política de permissões

Gerencie como a página e os iframes de terceiros nela têm acesso aos recursos do navegador.

Kevin K. Lee

A política de permissões, anteriormente conhecida como política de recursos, permite que o desenvolvedor controle os recursos do navegador disponíveis para uma página, seus iframes e subrecursos, declarando um conjunto de políticas para o navegador aplicar. Essas políticas são aplicadas às origens fornecidas em uma lista de origem de cabeçalho de resposta. A lista de origem pode conter origens iguais e/ou diferentes, e permite que o desenvolvedor controle o acesso próprio e de terceiros aos recursos do navegador.

O usuário tem a decisão final de permitir o acesso a recursos mais avançados e precisa aceitar uma solicitação para dar uma permissão explícita.

A Política de permissões permite que o site de nível superior defina o que ele e terceiros pretendem usar e remove a carga do usuário de determinar se a solicitação de acesso ao recurso é legítima ou não. Por exemplo, ao usar a Política de permissões para bloquear o recurso de geolocalização para todos os terceiros, o desenvolvedor pode ter certeza de que nenhum terceiro terá acesso à geolocalização do usuário.

Observação: o Sandbox de privacidade é uma série de propostas e APIs para atender casos de uso de terceiros sem cookies de terceiros ou outros mecanismos de rastreamento. As APIs do Sandbox de privacidade, como as dicas do cliente do User-Agent e a API Topics, são gerenciadas pela Política de permissões da mesma forma que recursos como geolocation e camera. Para conferir uma lista de APIs da plataforma da Web que dependem da política de permissões, consulte a lista de recursos. Essa lista pode não estar atualizada.

Mudanças na Política de permissões

A Política de permissões era conhecida como Política de recursos. Os principais conceitos continuam os mesmos, mas há algumas mudanças importantes com o nome.

Uso de campos estruturados

Os campos estruturados fornecem um conjunto de estruturas de dados comuns para padronizar a análise e a serialização dos valores do campo do cabeçalho HTTP. Saiba mais sobre os campos estruturados na postagem do blog da Fastly "Como melhorar o HTTP com campos de cabeçalho estruturados".

Antigo

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

Antes da política de recursos.

Novo

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

Agora com a Política de permissões.

Combinar cabeçalhos com o atributo allow do iframe

Com a política de recursos, é possível adicionar o recurso a um frame de origem cruzada adicionando a origem à lista de origem do cabeçalho ou adicionando um atributo allow à tag iframe. Com a Política de permissões, se você adicionar um frame entre origens à lista de origem, a tag iframe dessa origem precisará incluir o atributo allow. Se a resposta não tiver um cabeçalho de política de permissões, a lista de origem terá o valor padrão *. Adicionar o atributo allow ao iframe permite o acesso ao recurso.

Portanto, recomendamos que os desenvolvedores definam explicitamente o cabeçalho da política de permissões na resposta para que os iframes entre origens que não estão listados na lista de origem sejam bloqueados para acessar esse recurso, mesmo que allow esteja presente.

A política de recursos ainda pode ser usada após o Chrome 88, mas funciona como um alias para a política de permissões. Além da sintaxe, não há diferença na lógica. Se os cabeçalhos da Política de permissões e da Política de recursos forem usados juntos, o cabeçalho Permissions-Policy terá prioridade mais alta e vai substituir o valor fornecido pelo cabeçalho Feature-Policy.

Como faço para usar a política de permissões?

Visão rápida

Antes de entrarmos em detalhes, vamos analisar um cenário comum em que você é proprietário de um site e quer controlar como o site e o código de terceiros usam os recursos do navegador.

• Seu site é https://your-site.example.
• Seu site incorpora um iframe de mesma origem (https://your-site.example).
• Seu site incorpora um iframe do https://trusted-site.example em que você confia.
• Seu site também exibe anúncios veiculados por https://ad.example.
• Você quer permitir geolocalização apenas para seu site e site confiável, não para o anúncio.

Nesse caso, use o seguinte cabeçalho:

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

E defina explicitamente o atributo allow para a tag iframe do site confiável:

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

Neste exemplo, a lista de origem do cabeçalho permite que apenas seu site (self) e trusted-site.example usem o recurso de geolocalização. ad.example não tem permissão para usar geolocalização.

1. O site your-site.example tem permissão para usar o recurso de geolocalização com o consentimento do usuário.
2. Um iframe de mesma origem (your-site.example) pode usar o recurso sem o uso do atributo allow.
3. Um iframe veiculado de um subdomínio diferente (subdomain.your-site-example) que não foi adicionado à lista de origem e tem o atributo de permissão definido na tag do iframe não pode usar o recurso. Subdomínios diferentes são considerados do mesmo site, mas de origem cruzada.
4. Um iframe entre origens (trusted-site.example) que foi adicionado à lista de origem e tem o atributo allow definido na tag de iframe pode usar o recurso.
5. Um iframe de origem cruzada (trusted-site.example) adicionado à lista de origens, sem o atributo allow, está impedido de usar o recurso.
6. Um iframe entre origens (ad.example) que não foi adicionado à lista de origem não pode usar o recurso, mesmo que o atributo allow seja incluído na tag de iframe.

Cabeçalho de resposta HTTP Permissions-Policy

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

Use um cabeçalho Permissions-Policy na resposta do servidor para definir as origens permitidas para um recurso. O valor do cabeçalho pode ter uma combinação de tokens e strings de origens. Os tokens disponíveis são * para todas as origens e self para a mesma origem.

Se o cabeçalho for para vários recursos, separe-os com uma vírgula. Se você listar várias origens, separe cada uma delas com um espaço. Para cabeçalhos que listam uma origem que é uma solicitação de origem cruzada, a tag de iframe precisa incluir o atributo allow.

Aqui estão alguns exemplos de pares de chave-valor:

• Sintaxe: [FEATURE]=*
  • Política aplicada a todas as origens
  • Exemplo: geolocation=*
• Sintaxe: [FEATURE]=(self)
  • Política aplicada à mesma origem
  • Exemplo: geolocation=(self)
• Sintaxe: [FEATURE]=(self [ORIGIN(s)])
  • Política aplicada à mesma origem e às origens especificadas
  • Exemplo: geolocation=(self "https://a.example" "https://b.example")
  • self é uma abreviação de https://your-site.example.
• Sintaxe: [FEATURE]=([ORIGIN(s)])
  • Política aplicada à mesma origem e às origens especificadas
  • Exemplo: geolocation=("https://your-site.example" "https://a.example" "https://b.example")
  • Ao usar essa sintaxe, uma das origens precisa ser a do incorporador. Se a página de incorporação não receber as permissões, os iframes incorporados nela também serão bloqueados, mesmo que sejam adicionados à lista de origem, porque a Política de permissões delega permissões. Também é possível usar o token self.
• Sintaxe: [FEATURE]=()
  • Recurso bloqueado para todas as origens
  • Exemplo: geolocation=()

Aviso: se o cabeçalho da política de permissão não estiver presente na resposta, o valor padrão do token * será usado. Isso permite que todos os iframes na página com um atributo allow usem o recurso. Portanto, é altamente recomendável que a lista de origem seja definida explicitamente no cabeçalho Permissions-Policy para controlar o acesso.

Importante: com a mudança na política de permissões da política de recursos, adicionar a origem à lista de origem do cabeçalho não é mais suficiente para ativar o recurso para um iframe de várias origens. O iframe precisa incluir o atributo allow se tiver origem cruzada, independentemente do que está definido na lista de origem do cabeçalho.

Diferentes subdomínios e caminhos

Subdomínios diferentes, como https://your-site.example e https://subdomain.your-site.example, são considerados com o mesmo site, mas com origem cruzada. Portanto, adicionar um subdomínio à lista de origens não permite o acesso a outro subdomínio do mesmo site. Cada subdomínio incorporado que quiser usar o recurso precisa ser adicionado separadamente à lista de origem. Por exemplo, se o acesso aos tópicos de navegação do usuário for permitido apenas com o cabeçalho Permissions-Policy: browsing-topics=(self) na mesma origem, um iframe de um subdomínio diferente do mesmo site, https://subdomain.your-site.example, não terá acesso aos tópicos.

Caminhos diferentes, como https://your-site.example e https://your-site.example/embed, são considerados de mesma origem, e caminhos diferentes não precisam ser listados na lista de origem.

Atributo allow do iframe

Para uso entre origens, um iframe precisa do atributo allow na tag para ter acesso ao recurso.

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

Exemplo:

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

Observação: a sintaxe allow="geolocation" é uma abreviação de allow="geolocation 'src'". src é um token especial que se expande para a origem do atributo src do iframe.

Processar a navegação no iframe

Por padrão, se um iframe navegar para outra origem, a política não será aplicada àquela em que o iframe navegar. Ao listar a origem para a qual o iframe navega no atributo allow, a Política de permissões aplicada ao iframe original será aplicada à origem para a qual o iframe navega.

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

Para conferir em ação, acesse a demonstração de navegação de iframe.

Exemplos de configurações de políticas de permissões

Os exemplos das configurações a seguir podem ser encontrados na demonstração.

Recurso permitido em todas as origens

Permissions-Policy: geolocation=*

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

Quando a lista de origem está definida como o token *, o recurso é permitido para todas as origens presentes na página, incluindo a própria e todos os iframes. Neste exemplo, todo o código veiculado pelo https://your-site.example e os códigos veiculados pelo iframe https://trusted-site.example e https://ad.example têm acesso ao recurso de geolocalização no navegador do usuário. O atributo "allow" também precisa ser definido no iframe, além de adicionar a origem à lista de origem do cabeçalho.

Confira essa configuração na demonstração.

Recurso permitido apenas na mesma origem

Permissions-Policy: geolocation=(self)

Com o token self, é possível usar a geolocalização apenas para a mesma origem. As origens cruzadas não terão acesso ao recurso. Neste exemplo, apenas https://trusted-site.example (self) terá acesso à geolocalização. Use essa sintaxe se quiser o recurso apenas para sua página e mais ninguém.

Confira essa configuração na demonstração.

Recurso permitido em mesma origem e origens cruzadas específicas

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

Essa sintaxe permite o uso da geolocalização para o próprio app (https://your-site.example) e para https://trusted-site.example. Adicione explicitamente o atributo "allow" à tag iframe. Se houver outro iframe com <iframe src="https://ad.example" allow="geolocation">, https://ad.example não terá acesso ao recurso de geolocalização. Somente a página original e o https://trusted-site.example listado na lista de origem, além de ter o atributo de permissão na tag iframe, terão acesso ao recurso do usuário.

Confira essa configuração na demonstração.

Recurso bloqueado em todas as origens

Permissions-Policy: geolocation=()

Com uma lista de origem vazia, o recurso é bloqueado para todas as origens. Confira essa configuração na demonstração.

Importante: não é possível permitir o recurso para origens cruzadas incorporadas se ele estiver bloqueado para a mesma origem. Como as permissões aplicadas à página mãe são delegadas aos iframes incorporados, o recurso precisa ser ativado para a mesma origem se for permitido para origens cruzadas.

Usar a API JavaScript

A API JavaScript da política de recursos é encontrada como um objeto no documento ou no elemento (document.featurePolicy or element.featurePolicy). A API JavaScript da política de permissões ainda não foi implementada.

A API Feature Policy pode ser usada para políticas definidas pela política de permissões, com algumas limitações. Há perguntas pendentes sobre a implementação de uma API JavaScript, e uma proposta foi feita para mover a lógica para a API Permissions. Participe da discussão se você tiver alguma ideia.

featurePolicy.allowsFeature(feature)

• Retornará true se o recurso for permitido para o uso de origem padrão.
• O comportamento é o mesmo para as duas políticas definidas pela Política de permissões e pela política de recursos anterior
• Quando allowsFeature() é chamado em um elemento iframe (iframeEl.featurePolicy.allowsFeature('geolocation')), o valor retornado reflete se o atributo de permissão está definido no iframe.

featurePolicy.allowsFeature(feature, origin)

• Retorna true se o recurso for permitido para a origem especificada.
• Se o método for chamado em document, ele não vai mais informar se o recurso é permitido para a origem especificada, como fazia a política de recursos. Esse método informa que o recurso pode ser permitido para essa origem. É necessário realizar uma verificação adicional para saber se o iframe tem o atributo allow definido ou não. O desenvolvedor precisa realizar uma verificação adicional do atributo allow no elemento iframe para determinar se o recurso é permitido para a origem de terceiros.

Verificar se há recursos em um iframe com o objeto element

Você pode usar element.allowsFeature(feature), que considera o atributo "allow", ao contrário de document.allowsFeature(feature, origin).

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

featurePolicy.allowedFeatures()

• Retorna uma lista de recursos permitidos para o uso de origem padrão.
• O comportamento é o mesmo para as duas políticas definidas pela política de permissões e pela política de recursos.
• Quando o nó associado é um iframe, o atributo "allow" é levado em consideração.

featurePolicy.features()

• Retorna uma lista de recursos disponíveis no navegador.
• O comportamento é o mesmo para as duas políticas definidas pela Política de permissões e pela Política de recursos.

Integração com o Chrome DevTools

Confira como a Política de permissões funciona no DevTools.

1. Abra o Chrome DevTools.
2. Abra o painel Application para verificar os recursos permitidos e não permitidos de cada frame.
3. Na barra lateral, selecione o frame que você quer inspecionar. Você verá uma lista de recursos que o frame selecionado pode usar e uma lista de recursos que estão bloqueados nesse frame.

Migração da política de recursos

Se você estiver usando o cabeçalho Feature-Policy, implemente as etapas a seguir para migrar para a política de permissões.

Substituir cabeçalhos da política de recursos por cabeçalhos da política de permissões

Como os cabeçalhos da política de recursos só são compatíveis com navegadores baseados no Chromium, e os cabeçalhos da política de permissões são compatíveis desde o Chrome 88, é seguro atualizar os cabeçalhos existentes com a política de permissões.

Antigo

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

Antes da política de recursos.

Novo

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

Agora com a Política de permissões.

Atualizar o uso do document.allowsFeature(feature, origin)

Se você estiver usando o método document.allowsFeature(feature, origin) para verificar os recursos permitidos para iframes, use o método allowsFeature(feature) anexado ao elemento iframe, e não o document que o contém. O método element.allowsFeature(feature) considera o atributo de permissão, enquanto document.allowsFeature(feature, origin) não.

Verificar o acesso a recursos com document

Para continuar usando document como o nó base, faça uma verificação adicional do atributo allow na 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

Em vez de atualizar o código atual usando document, é recomendável chamar allowsFeature() no objeto element, como no exemplo anterior.

API Reporting

A API Reporting oferece um mecanismo de relatórios para aplicativos da Web de maneira consistente. A API Reporting para violações da política de permissões está disponível como um recurso experimental.

Se você quiser testar o recurso experimental, siga o tutorial e ative a flag em chrome://flags/#enable-experimental-web-platform-features. Com a flag ativada, é possível observar violações da política de permissões no DevTools, na guia "Application":

O exemplo a seguir mostra como o cabeçalho da API Reporting pode ser criado:

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;

Na implementação atual, você pode receber relatórios de violação da política de qualquer violação ocorrida nesse frame configurando um endpoint chamado "default", como no exemplo anterior. Os subframes precisam de uma configuração própria para geração de relatórios.

Observação: se você quiser que a API Reporting ofereça suporte à Política de permissões por padrão, adicione seu apoio ou comentários à discussão.

Saiba mais

Para entender melhor a Política de permissões, consulte estes recursos:

• Especificações da política de permissões
• Explicação da política de permissões
• Uma lista de recursos controlados por políticas.