Uma iframe não está a funcionar, a consola tem uma linha vermelha sobre frames nela, e alguém já disse a palavra CORS. Essa palavra está quase sempre errada aqui, e a razão pela qual está errada importa, porque as duas coisas que as pessoas estão realmente a ver têm donos diferentes e correções opostas.

Há dois tipos de falha. Um significa que a página recusou ser incorporada. O outro significa que a página foi incorporada perfeitamente bem e o seu código não consegue ler dentro dela. Parecem semelhantes numa captura de ecrã e partilham quase nada mais.

Falha um: recusou carregar completamente

O frame está vazio. A consola diz que o documento se recusou a ser exibido porque de X-Frame-Options, ou por causa de uma Content Security Policy.

Esta é uma decisão tomada pelo site que está a incorporar, entregue na resposta que pediu. O MDN é preciso sobre para que serve o cabeçalho: indica “se um navegador deve ser autorizado a renderizar o documento num <frame>, <iframe>, <embed> ou <object>”, e os sites usam-no “para evitar ataques de clickjacking e algumas fugas entre sites, garantindo que o seu conteúdo não é incorporado noutros sites”.

Há dois valores que ainda significam algo. DENY significa que o documento “não pode ser carregado em nenhum frame, independentemente da origem”, incluindo pelo site que o serviu. SAMEORIGIN significa que “só pode ser incorporado se todos os frames antepassados têm a mesma origem que a própria página”.

A parte importante é de quem é o cabeçalho. Viaja com o documento que está a ser enquadrado, não com a página que está a fazer o enquadramento. Então nada no seu HTML, na sua configuração de servidor ou no seu framework vai alterá-lo. Se não controlar aquela outra origem, não pode corrigir isto, e as opções honestas são pedir-lhes que permitam a sua origem ou deixar de incorporá-los.

Três maneiras pelas quais as equipas perdem um dia nisto

Chegar a ALLOW-FROM. Era a directiva para permitir uma origem específica e está obsoleta. A formulação do MDN vale a pena ler cuidadosamente: “Os navegadores modernos que encontram cabeçalhos de resposta com esta directiva ignorarão o cabeçalho completamente.” Portanto, adicioná-lo não restringe nada. Remove a proteção que pensava estar a configurar, e o frame pode muito bem começar a funcionar, pela razão errada. O equivalente moderno é a directiva frame-ancestors numa Content Security Policy.

Colocá-lo numa meta tag. O MDN leva um aviso explícito: defini-lo dentro de um elemento <meta> “não tem efeito. X-Frame-Options é apenas aplicado através de cabeçalhos HTTP.” Uma implementação onde os cabeçalhos de resposta são incómodos é exatamente onde alguém tenta isto, e falha silenciosamente da maneira mais cara, que é parecer feito.

Alterar cabeçalhos no site errado. Adicionar X-Frame-Options às suas próprias respostas não faz nada sobre um terceiro se recusando a ser enquadrado. Apenas muda quem pode incorporá-lo.

Falha dois: carregou, e você não consegue ler

Mensagem diferente, mundo diferente. O frame é renderizado. O seu script chega para dentro dele, pelo documento, pela altura, um campo de formulário, e o navegador bloqueia o acesso com uma mensagem sobre um frame de origem cruzada.

Nada está avariado. Esta é a same-origin policy fazendo a única coisa para a qual existe. Nas palavras do MDN, quando dois documentos não têm a mesma origem, as referências entre documentos “proporcionam acesso muito limitado a objetos Window e Location”.

Muito limitado é uma lista específica em vez de um aviso vago. Entre origens você mantém postMessage, blur, focus e close; você pode ler closed, frames, length, opener, parent, self, top e window; location.href é escritível mas não legível, o que é porque você pode navegar um frame que não consegue inspecionar. Tudo o mais, incluindo todo o documento, desaparece.

A correção não é um cabeçalho. O MDN afirma isto claramente: “Para comunicar entre documentos de origens diferentes, use window.postMessage.” A página incorporada publica o que está disposta a partilhar, o pai ouve, e ambos os lados verificam a origem pelo caminho. Esta é a rota suportada e a única que sobrevive.

E o velho truque já não é um truque. Definir document.domain como um sufixo partilhado está depreciado, e o MDN diz porquê: “compromete as proteções de segurança fornecidas pela same origin policy, e complica o modelo de origem em navegadores, levando a problemas de interoperabilidade e erros de segurança”.

Por que CORS é a palavra errada para ambas

CORS governa se o seu JavaScript pode ler a resposta a um pedido que fez. É sobre fetch e XMLHttpRequest.

O enquadramento não é um pedido que o seu script lê, e chegar a um frame carregado não é um pedido de todo. Então nenhum cabeçalho Access-Control-Allow-Origin corrige nenhuma falha, o que é porquê a tarde passada a adicionar um produz nada. Se o erro genuinamente menciona uma política de CORS, você está a olhar para uma terceira coisa novamente.

Para completar, uma recusa em enquadrar também pode aparecer como ERR_BLOCKED_BY_RESPONSE, que é um dos três erros Chromium que todos lêem como bloqueado e vale a pena distinguir pela mesma razão que estes dois.

A razão pela qual isto chega como um relatório de falha que não consegue reproduzir

Ambas as falhas são invisíveis de um modo que custa tempo real.

A mensagem da consola vive na página do pai, e o que o utilizador vê é um rectângulo em branco onde um widget deveria estar. Uma captura de ecrã daquele rectângulo contém nenhum do diagnóstico. A pessoa a enviá-la não tem razão para abrir as ferramentas de desenvolvedor, e não saberia qual das duas linhas importava se o fizesse.

Pior, ambas são condicionais. Os cabeçalhos do site incorporado podem diferir entre os seus próprios ambientes, um proxy corporativo pode adicionar ou remover um cabeçalho em trânsito, e uma política pode ser apertada numa terça-feira por uma equipa que nunca falou. Portanto o frame funciona na sua máquina e não na deles, ou funcionava semana passada e não funciona hoje, sem nada no seu repositório ter mudado.

O que é a forma ordinária disto: a resposta é uma linha na consola de alguém mais, e o relatório que recebe é uma imagem de uma caixa vazia.

A versão curta

  • Dois erros, não um. “Recusou-se a exibir” é o site incorporado a dizer não. “Bloqueou um frame com origem” é a same-origin policy a recusar-lhe acesso a um frame que carregou bem.
  • O primeiro é governado por um cabeçalho no documento que está a ser enquadrado, portanto não é seu a menos que possua aquela origem.
  • ALLOW-FROM está obsoleto e faz os navegadores ignorarem o cabeçalho completamente, e uma tag <meta> nunca funcionou de todo.
  • O segundo é corrigido com postMessage, não com cabeçalhos, e document.domain está depreciado.
  • CORS não corrige nenhum, porque nenhum é o seu script a ler uma resposta.
  • O utilizador vê uma caixa em branco e a explicação está numa consola que nunca abrirão.