Resumo
A Política de recursos permite que os desenvolvedores Web ativem, desativem e modifiquem o comportamento de determinadas APIs e recursos da Web no navegador. É como o CSP, mas em vez de controlar a segurança, ele controla os recursos.
As próprias políticas de recursos são pequenos contratos de aceitação entre o desenvolvedor e o navegador que podem ajudar a promover nossos objetivos de criar (e manter) apps da Web de alta qualidade.
Introdução
Criar para a web é uma aventura rochosa. Já é difícil criar um app da Web de alto nível, que valorize o desempenho e use todas as práticas recomendadas mais recentes. É ainda mais difícil manter essa experiência excelente ao longo do tempo. À medida que seu projeto evolui, os desenvolvedores aderem, novos recursos são lançados e a base de código aumenta. Essa grande experiência TM que você alcançou uma vez pode começar a deteriorar e a UX começar a ser afetada! A política de recursos foi criada para ajudar você a se manter no caminho certo.
Com a Política de recursos, você ativa um conjunto de "políticas" para o navegador aplicar a recursos específicos usados em todo o site. Essas políticas restringem quais APIs o site pode acessar ou modificar o comportamento padrão do navegador para determinados recursos.
Confira alguns exemplos do que é possível fazer com a política de recursos:
- Mude o comportamento padrão
de
autoplay
em vídeos para dispositivos móveis e de terceiros. - Impeça que um site use APIs confidenciais, como
camera
oumicrophone
. - Permitir que os iframes usem a API
fullscreen
. - Bloqueie o uso de APIs desatualizadas, como XHR síncrono e
document.write()
. - Verifique se as imagens estão dimensionadas corretamente (por exemplo, para evitar a sobrecarga de layouts) e não são grandes demais para a janela de visualização (por exemplo, desperdiçando a largura de banda do usuário).
As políticas são um contrato entre o desenvolvedor e o navegador. Elas informam ao navegador qual é a intenção do desenvolvedor e, assim, ajudam a manter a honestidade quando o app tenta fugir dos trilhos e fazer algo ruim. Se o site ou o conteúdo incorporado de terceiros tentar violar qualquer uma das regras pré-selecionadas do desenvolvedor, o navegador modificará o comportamento para uma UX melhor ou bloqueará a API completamente.
Como usar a política de recursos
A política de recursos oferece duas maneiras de controlar os recursos:
- Pelo cabeçalho HTTP
Feature-Policy
. - Com o atributo
allow
em iframes.
Cabeçalho HTTP Feature-Policy
A maneira mais fácil de usar a Política de recursos é enviar o cabeçalho HTTP Feature-Policy
com a resposta de uma página. O valor desse cabeçalho é uma política ou um conjunto
de políticas que você quer que o navegador respeite para uma determinada origem:
Feature-Policy: <feature> <allow list origin(s)>
A lista de permissões de origem pode ter vários valores diferentes:
*
: o recurso é permitido em contextos de navegação de nível superior e em contextos de navegação aninhados (iframes).'self'
: o recurso é permitido em contextos de navegação de nível superior e em contextos de navegação aninhados de mesma origem. Ela não é permitida em documentos de origem cruzada em contextos de navegação aninhados.'none'
: o recurso não é permitido em contextos de navegação de nível superior e em contextos de navegação aninhados.<origin(s)>
: origens específicas para ativar a política (por exemplo,https://example.com
).
Exemplo
Digamos que você queira impedir que todo o conteúdo
use a API Geolocation no seu site. Para fazer isso, envie uma lista de permissões
estrita de 'none'
para o recurso geolocation
:
Feature-Policy: geolocation 'none'
Se um trecho de código ou iframe tentar usar a API Geolocation, ele será bloqueado pelo navegador. Isso é válido mesmo que o usuário tenha concedido permissão para compartilhar a localização deles.
Em outros casos, pode fazer sentido flexibilizar um pouco essa política. Podemos permitir que nossa origem use a API Geolocation, mas impedir que conteúdo de terceiros a acesse definindo 'self'
na lista de permissões:
Feature-Policy: geolocation 'self'
O atributo iframe allow
A segunda maneira de usar a Política de recursos é controlar o conteúdo em
uma iframe
. Use o atributo allow
para especificar uma lista de políticas para
conteúdo incorporado:
<!-- Allow all browsing contexts within this iframe to use fullscreen. -->
<iframe src="https://example.com..." allow="fullscreen"></iframe>
<!-- Equivalent to: -->
<iframe src="https://example.com..." allow="fullscreen *"></iframe>
<!-- Allow only iframe content on a particular origin to access the user's location. -->
<iframe
src="https://another-example.com/demos/..."
allow="geolocation https://another-example.com"
></iframe>
E quanto aos atributos de iframe existentes?
Alguns dos recursos controlados pela política de recursos têm um atributo
para controlar o comportamento deles. Por exemplo, <iframe allowfullscreen>
é um atributo que permite que o conteúdo iframe use a
API HTMLElement.requestFullscreen()
. Há também os atributos allowpaymentrequest
e allowusermedia
para permitir a API Payment Request e getUserMedia()
, respectivamente.
Tente usar o atributo allow
em vez dos atributos
antigos sempre que possível. Nos casos em que é necessário oferecer compatibilidade com versões anteriores,
o uso do atributo allow
com um atributo legado equivalente
é perfeitamente aceitável (por exemplo, <iframe allowfullscreen allow="fullscreen">
).
Apenas a política mais restritiva prevalece. Por exemplo, o iframe a seguir
não poderia entrar em tela cheia porque
allow="fullscreen 'none'"
é mais restritivo que allowfullscreen
:
<!-- Blocks fullscreen access if the browser supports feature policy. -->
<iframe allowfullscreen allow="fullscreen 'none'" src="..."></iframe>
Controle de várias políticas de uma só vez
Vários recursos podem ser controlados ao mesmo tempo enviando o cabeçalho HTTP
com uma lista separada por ;
de diretivas de política:
Feature-Policy: unsized-media 'none'; geolocation 'self' https://example.com; camera *;
ou envie um cabeçalho separado para cada política:
Feature-Policy: unsized-media 'none'
Feature-Policy: geolocation 'self' https://example.com
Feature-Policy: camera *;
Esse exemplo faria o seguinte:
- Não permite o uso de
unsized-media
em todos os contextos de navegação. - Não permite o uso de
geolocation
para todos os contextos de navegação, exceto a origem da própria página ehttps://example.com
. - Concede acesso ao
camera
para todos os contextos de navegação.
Exemplo: configurar várias políticas em um iframe
<!-- Blocks the iframe from using the camera and microphone
(if the browser supports feature policy). -->
<iframe allow="camera 'none'; microphone 'none'"></iframe>
JavaScript API
Embora o Chrome 60 tenha adicionado suporte ao cabeçalho HTTP Feature-Policy
e ao
atributo allow
nos iframes, a API JavaScript foi adicionada no Chrome 74.
Essa API permite que o código do lado do cliente determine quais recursos são permitidos por uma página, frame ou navegador. É possível acessar os recursos adicionais em
document.featurePolicy
para o documento principal ou frame.featurePolicy
para
iframes.
Exemplo
O exemplo abaixo ilustra os resultados do envio de uma política do Feature-Policy: geolocation 'self'
no site https://example.com
:
/* @return {Array<string>} List of feature policies allowed by the page. */
document.featurePolicy.allowedFeatures();
// → ["geolocation", "midi", "camera", "usb", "autoplay",...]
/* @return {boolean} True if the page allows the 'geolocation' feature. */
document.featurePolicy.allowsFeature('geolocation');
// → true
/* @return {boolean} True if the provided origin allows the 'geolocation' feature. */
document.featurePolicy.allowsFeature(
'geolocation',
'https://another-example.com/'
);
// → false
/* @return {Array<string>} List of feature policies allowed by the browser
regardless of whether they are in force. */
document.featurePolicy.features();
// → ["geolocation", "midi", "camera", "usb", "autoplay",...]
/* @return {Array<string>} List of origins (used throughout the page) that are
allowed to use the 'geolocation' feature. */
document.featurePolicy.getAllowlistForFeature('geolocation');
// → ["https://example.com"]
Lista de políticas
Quais recursos podem ser controlados pela Política de recursos?
No momento, há uma falta de documentação sobre quais políticas são implementadas e como usá-las. A lista também aumenta com o tempo, à medida que diferentes navegadores adotam a especificação e implementam várias políticas. A política de recursos será um destino em movimento, e com certeza serão necessários bons documentos de referência.
Por enquanto, existem algumas maneiras de saber quais recursos podem ser controlados.
- Confira nossas demonstrações na Política de recursos da pia. Ela traz exemplos de cada política implementada no Blink.
- Verifique a lista de nomes de recursos em Origem do Chrome.
- Consulte
document.featurePolicy.allowedFeatures()
emabout:blank
para encontrar a lista:
["geolocation",
"midi",
"camera",
"usb",
"magnetometer",
"fullscreen",
"animations",
"payment",
"picture-in-picture",
"accelerometer",
"vr",
...
- Acesse chromestatus.com para ver as políticas que foram implementadas ou estão sendo consideradas no Blink.
Para determinar como usar algumas dessas políticas, consulte o repositório do GitHub da especificação (link em inglês). Ele contém explicações sobre algumas das políticas.
Perguntas frequentes
Quando devo usar a Política de recursos?
Todas as políticas são opcionais, portanto, use a Política de recursos quando/onde fizer sentido. Por
exemplo, se seu app for uma galeria de imagens, a política maximum-downscaling-image
ajudará a evitar o envio de imagens enormes para janelas de visualização de dispositivos móveis.
Outras políticas, como document-write
e sync-xhr
, precisam ser usadas com mais cuidado. Ativar esse recurso pode corromper conteúdo de terceiros, como anúncios. Por
outro lado, a Política de recursos pode ser uma verificação intrinseca para garantir que suas páginas
nunca usem essas APIs horríveis.
Eu uso a Política de recursos no desenvolvimento ou na produção?
Ambos. Recomendamos ativar as políticas durante o desenvolvimento e mantê-las ativas durante a produção. Ativar as políticas durante o desenvolvimento pode ajudar você a começar no caminho certo. Isso ajudará você a detectar regressões inesperadas antes que elas aconteçam. Mantenha as políticas ativadas na produção para garantir uma UX específica para os usuários.
É possível denunciar violações de políticas ao meu servidor?
Uma API Reporting está em desenvolvimento. Assim como os sites podem ativar o recebimento de relatórios sobre violações da CSP ou descontinuações, você poderá receber denúncias sobre violações da política de recursos em qualquer lugar.
Quais são as regras de herança para conteúdo iframe?
Os scripts (próprios ou de terceiros) herdam a política do contexto de navegação. Isso significa que os scripts de nível superior herdam as políticas do documento principal.
iframe
s herdam as políticas da página pai. Se o iframe
tiver um
atributo allow
, a política mais rigorosa entre a página mãe e a lista allow
vence. Para mais informações sobre o uso de iframe
, consulte o
atributo allow
em iframes.
Se eu aplicar uma política, ela dura todas as navegações nas páginas?
Não. O ciclo de vida de uma política se aplica a uma única resposta de navegação de página. Se
o usuário navegar para uma nova página, o cabeçalho Feature-Policy
precisará ser enviado explicitamente
na nova resposta para que a política seja aplicada.
Quais navegadores são compatíveis com a política de recursos?
Acesse caniuse.com (link em inglês) para conferir os detalhes mais recentes sobre o suporte a navegadores.
No momento, o Chrome é o único navegador que aceita a política de recursos. No entanto, como toda a plataforma da API pode ser ativada ou detectada por recursos, a Política de recursos se adapta bem ao aprimoramento progressivo.
Conclusão
A política de recursos pode ajudar a fornecer um caminho bem iluminado para uma melhor UX e um bom desempenho. Isso é especialmente útil ao desenvolver ou manter um app, já que pode ajudar a evitar possíveis alvos antes que eles entrem na sua base de código.
Outros recursos:
- Explicação sobre a política de recursos
- Especificações da política de recursos
- Demonstrações de pia de cozinha
- Extensão DevTools política de recursos: testador para testar políticas de recursos em uma página.
- Entradas de chromestatus.com