Introdução à política de recursos

Resumo

A política de recursos permite que os desenvolvedores da Web ativem, desativem e modifiquem seletivamente o comportamento de determinadas APIs e recursos da Web no navegador. É como a CSP, mas em vez de controlar a segurança, ela controla os recursos.

As políticas de recursos em si são pequenos contratos de aceitação entre desenvolvedor e navegador que podem ajudar a promover nossas metas de criação (e manutenção) de apps da Web de alta qualidade.

Introdução

Criar para a web é uma aventura cheia de pedras. Já é difícil criar um app da Web de alto nível que otimiza a performance e usa 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 participam, novos recursos são lançados e a base do código cresce. A Great Experience TM que você alcançou pode começar a se deteriorar, e a UX começará a sofrer! A política do recurso foi criada para manter você no caminho certo.

Com a política de recursos, você ativa um conjunto de "políticas" para o navegador aplicar em recursos específicos usados em todo o site. Essas políticas restringem quais APIs o site pode acessar ou modificam o comportamento padrão do navegador para determinados recursos.

Veja exemplos do que você pode fazer com a política de recursos:

  • Mude o comportamento padrão de autoplay em vídeos de dispositivos móveis e de terceiros.
  • Impedir que um site use APIs confidenciais, como camera ou microphone.
  • Permite 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 do layout) e não são muito grandes para a janela de visualização (por exemplo, desperdiçam 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, portanto, ajudam a manter a honestidade quando nosso app tenta sair 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 vai substituir o comportamento por uma melhor UX 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 não permitido 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 restrita de 'none' para o recurso geolocation:

Feature-Policy: geolocation 'none'

Se um trecho de código ou iframe tentar usar a API Geolocation, o navegador o bloqueará. Isso é válido mesmo que o usuário já tenha concedido permissão para compartilhar a localização.

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

Em outros, pode fazer sentido flexibilizar um pouco essa política. Podemos permitir que nossa própria origem use a API Geolocation, mas impedir que conteúdo de terceiros o acesse. Para isso, defina '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 um 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 os atributos de iframe atuais?

Alguns dos recursos controlados pela política de recursos têm um atributo existente para controlar o comportamento deles. Por exemplo, <iframe allowfullscreen> é um atributo que permite que o conteúdo de 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 desses atributos antigos sempre que possível. Para casos em que você precisa oferecer compatibilidade com versões anteriores usando o atributo allow com um atributo legado equivalente é perfeitamente aceitável (por exemplo, <iframe allowfullscreen allow="fullscreen">). No entanto, a política mais restritiva vence. 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>

Como controlar várias políticas de uma 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 enviando 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:

  • Bloqueia o uso de unsized-media para todos os contextos de navegação.
  • Bloqueia o uso de geolocation para todos os contextos de navegação, exceto para a própria origem da página e https://example.com.
  • Permite o acesso do 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 em iframes, a API JavaScript foi adicionada no Chrome 74.

Essa API permite que o código do lado do cliente determine quais recursos têm permissão de 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 de 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 funcionalidades podem ser controladas pela política de recursos?

No momento, não há documentação sobre quais políticas são implementadas e como usá-las. A lista também vai aumentar com o tempo, à medida que navegadores adotarem a especificação e implementarem várias políticas. A política de recursos será um alvo móvel, e certamente precisará de bons documentos de referência.

Por enquanto, há algumas maneiras de saber quais recursos são controláveis.

        ["geolocation",
         "midi",
         "camera",
         "usb",
         "magnetometer",
         "fullscreen",
         "animations",
         "payment",
         "picture-in-picture",
         "accelerometer",
         "vr",
        ...
  • Acesse chromestatus.com para conferir as políticas que foram implementadas ou estão sendo consideradas no Blink.

Para determinar como usar algumas dessas políticas, confira o repositório do GitHub das especificações (em inglês). Ele tem algumas explicações sobre algumas 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 o app for uma galeria de imagens, a política maximum-downscaling-image ajudará a evitar o envio de imagens gigantes 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 um teste para garantir que suas páginas nunca usem essas APIs terríveis.

Uso a política de recursos em desenvolvimento ou 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. Ele o ajudará a detectar regressões inesperadas antes que aconteçam. Mantenha as políticas ativadas na produção para garantir uma determinada UX para os usuários.

Existe uma forma de denunciar violações da política 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, também é possível receber relatórios sobre violações da política de recursos em geral.

Quais são as regras de herança para o conteúdo do iframe?

Os scripts (próprios ou de terceiros) herdam a política do contexto de navegação deles. 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 deles. Se a iframe tiver um atributo allow, a política mais rigorosa entre a página mãe e a lista de 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 refere a uma única resposta de navegação nas páginas. 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 para ver os detalhes mais recentes sobre a compatibilidade com navegadores.

No momento, o Chrome é o único navegador compatível com a política de recursos. No entanto, como toda a plataforma da API é ativada ou detectável por recursos, a política de recursos tem um bom desempenho ao melhorar o 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. Ela é especialmente útil ao desenvolver ou manter um app, já que pode ajudar a evitar possíveis patas antes que eles entrem na sua base de código.

Outros recursos: