Introdução à política de recursos

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 ou microphone.
  • 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:

  1. Pelo cabeçalho HTTP Feature-Policy.
  2. Com o atributo allow em iframes.

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.

Violação da política de geolocalização definida
Violação da política de geolocalização definida.

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 e https://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() em about: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.

iframes 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.

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: