iframe recusou a conexão: por que acontece e como resolver

iframe recusou a conexão

iframe recusou a conexão: causas e soluções, com verificador | We.Inc

Por que um iframe mostra "recusou a conexão": X-Frame-Options ou CSP frame-ancestors na página incorporada. Cole os cabeçalhos de resposta dela para ver o veredito e copie a correção para o servidor.

A caixa cinza de "recusou a conexão" significa que a página dentro do seu iframe disse ao navegador para não ser incorporada. Ela faz isso com um cabeçalho de resposta X-Frame-Options (DENY ou SAMEORIGIN) ou com uma regra frame-ancestors na Content-Security-Policy. Só o servidor do site incorporado pode liberar isso. Cole os cabeçalhos dele abaixo para ver qual regra está bloqueando você.

O que cada valor de cabeçalho significa para o seu iframe

Cabeçalho na página incorporada
Quem pode incorporá-la

X-Frame-Options: DENY
Ninguém, nem o próprio site

X-Frame-Options: SAMEORIGIN
Apenas páginas da mesma origem

X-Frame-Options: ALLOW-FROM ...
Obsoleto, ignorado pelos navegadores modernos

Content-Security-Policy: frame-ancestors 'none'
Ninguém

Content-Security-Policy: frame-ancestors 'self' https://a.example
A mesma origem mais os sites listados

Nenhum dos dois cabeçalhos
Qualquer um

Esse erro não é uma falha de rede e não há nada errado com a sua tag iframe. O navegador buscou a página, leu um cabeçalho que proíbe a incorporação e substituiu o conteúdo por um erro. O motivo é a proteção contra clickjacking: uma página que qualquer um pode incorporar pode ser coberta com botões invisíveis. A solução depende de qual servidor enviou o cabeçalho.

Abra a página que você quer incorporar em uma aba normal, abra as ferramentas de desenvolvedor e selecione a requisição do documento no painel Network.
Copie os cabeçalhos de resposta e cole no verificador, ou edite o exemplo que já está lá.
Informe a origem da página que contém o iframe. O verificador aplica as mesmas regras que o navegador usa e diz qual cabeçalho decide.
Se for o seu próprio servidor, copie a correção correspondente nos exemplos de servidor. Se for o site de outra pessoa, coloque um link para ele em vez de incorporá-lo.

Quando frame-ancestors está presente em uma Content-Security-Policy aplicada, os navegadores ignoram o X-Frame-Options por completo. Corrija a CSP primeiro.
Nenhum dos dois cabeçalhos funciona a partir de uma meta tag. Os dois precisam ser cabeçalhos de resposta HTTP de verdade, enviados pelo servidor ou pela CDN.
Um cabeçalho Content-Security-Policy-Report-Only nunca bloqueia a incorporação. Ele só reporta, então procure o cabeçalho que aplica a regra.
Se você precisa liberar alguns sites parceiros, use frame-ancestors com uma lista. O X-Frame-Options não tem nenhuma forma funcional de indicar outro site.
Muitos sites grandes bloqueiam a incorporação de propósito. Respeite isso: use a URL de incorporação oficial, se oferecerem, ou um link simples.

Perguntas frequentes

Posso contornar o recusou a conexão a partir da minha página?

Não. A regra é aplicada pelo navegador do visitante em nome do site incorporado, e nenhum atributo no seu iframe consegue sobrescrevê-la. Os únicos caminhos são mudar os cabeçalhos do site incorporado, usar uma URL de incorporação que o site fornece para iframes ou colocar um link.

Por que meu próprio site se recusa a carregar no próprio iframe?

Verifique se há X-Frame-Options: DENY ou frame-ancestors 'none'. Os dois bloqueiam qualquer página pai, incluindo páginas do mesmo domínio. Troque para SAMEORIGIN ou frame-ancestors 'self'. Lembre que um subdomínio ou uma porta diferente é outra origem.

Devo usar X-Frame-Options ou frame-ancestors?

Use frame-ancestors, porque ele pode listar vários pais permitidos e vence sempre que os dois estão presentes. Se você também enviar X-Frame-Options, mantenha-o coerente com a regra da CSP para não confundir a próxima pessoa que ler a configuração.

Por que um link de vídeo ou de mapa recusa a conexão?

A página comum de assistir ou do local normalmente envia um cabeçalho de incorporação, enquanto o serviço publica um endereço de incorporação separado, feito para iframes, que costuma ficar em Compartilhar e depois Incorporar. Nosso gerador de código de incorporação converte links compatíveis nesses endereços para você.

O frame-ancestors verifica todos os frames pai?

Sim. Se o seu iframe está dentro de outro iframe, todos os ancestrais até a página do topo precisam corresponder à política, não só o pai direto.

Leia o cabeçalho, não o erro

Os navegadores mostram a mesma caixa cinza seja qual for a regra acionada, mas o console diz qual foi. Procure uma mensagem que mencione X-Frame-Options ou frame-ancestors e depois abra o painel Network para ver o valor exato que o servidor enviou.
Redirecionamentos também importam. Se o endereço do iframe redireciona para uma página de login, o cabeçalho que conta é o da resposta final, que muitas vezes é mais rígido que o da página que você esperava.

Como corrigir em um servidor que você controla

Decida quem deve poder incorporar a página e expresse isso uma única vez, de preferência como uma diretiva frame-ancestors na sua Content-Security-Policy. Se um framework ou middleware de segurança adiciona X-Frame-Options por padrão, mude a configuração dele em vez de adicionar um segundo cabeçalho conflitante.
Depois do deploy, limpe o cache da CDN e confira de novo os cabeçalhos de resposta em produção, porque muitas hospedagens adicionam os próprios cabeçalhos de segurança na borda.

Quando o site não é seu

Um site que bloqueia a incorporação decidiu que não quer aparecer dentro de outras páginas. Um link, uma captura de tela com link ou o widget de incorporação do próprio site são as alternativas honestas.
Passar as páginas de outro site pelo seu servidor para remover o cabeçalho costuma quebrar os logins dele e pode violar os termos de uso, então não é uma solução que valha a pena publicar.

Correções de servidor para copiar

Cada exemplo libera o próprio site mais um parceiro. Troque https://partner.example pela origem que deve poder incorporar você, ou use 'none' para bloquear todo mundo.

always mantém o cabeçalho também nas páginas de erro. Remova qualquer linha antiga de X-Frame-Options para que as duas regras não fiquem divergentes.

Apache (.htaccess ou virtual host)

Precisa do mod_headers. Header always set substitui qualquer valor anterior do mesmo cabeçalho.

Express com Helmet

O Helmet define X-Frame-Options como SAMEORIGIN por padrão. Desligar isso e definir frame-ancestors mantém uma única fonte de verdade.

Next.js (next.config.js)

headers() adiciona cabeçalhos de resposta a cada rota correspondente. As plataformas de hospedagem podem adicionar os próprios, então confira a resposta em produção depois.

Verificador de cabeçalhos de resposta

Cole os cabeçalhos de resposta da página dentro do iframe. Tudo roda nesta página; nada é buscado.

Cabeçalhos de resposta da página incorporada

Origem da página que contém o iframe

Origem da página incorporada

Restaurar os cabeçalhos de exemplo

Veredito

Esta página pai pode incorporar a página.

O navegador vai se recusar a mostrar esta página no iframe.

Ainda não há um veredito claro.

Bloqueado pela Content-Security-Policy: frame-ancestors 'none'.

Permitido pelo frame-ancestors: {v} corresponde à origem pai.

Bloqueado pelo frame-ancestors: nenhuma fonte da lista corresponde a {v}.

O X-Frame-Options está presente, mas é ignorado, porque o frame-ancestors decide.

Bloqueado pelo X-Frame-Options: DENY.

Permitido pelo X-Frame-Options: SAMEORIGIN, e as origens coincidem.

Bloqueado pelo X-Frame-Options: SAMEORIGIN, e {v} é uma origem diferente.

ALLOW-FROM é obsoleto e ignorado, então não bloqueia.

O X-Frame-Options tem vários valores diferentes. Envie exatamente um.

A Content-Security-Policy-Report-Only nunca bloqueia; ela foi ignorada.

Nenhum cabeçalho de incorporação encontrado, então qualquer site pode incorporar esta página.

iframe recusou a conexão: por que acontece e como resolver