iframe: „odrzucił połączenie” – naprawa X-Frame-Options

Co naprawdę oznacza „odrzucił połączenie” w iframe

Dodajesz <iframe> wskazujący na inną witrynę, odświeżasz i zamiast strony widzisz szare pole z ikoną smutnej buźki; po najechaniu kursorem pojawia się napis Serwer example.com odrzucił połączenie. Pierwsza myśl to problem z siecią, bo dokładnie to samo Chrome pokazuje przy martwym serwerze. Ale otwórz DevTools, a konsola opowie inną historię:

Refused to display 'https://emicalcs.com/' in a frame because it set 'X-Frame-Options' to 'sameorigin'.

W sieci nic nie zawiodło. DNS się rozwiązał, połączenie TCP zostało otwarte, TLS się zakończył, a serwer zwrócił zupełnie poprawną odpowiedź 200. Przeglądarka pobrała stronę, odczytała jeden nagłówek odpowiedzi i celowo odmówiła wyświetlenia jej w Twojej stronie. Tym nagłówkiem jest X-Frame-Options, a jego zadaniem jest ochrona przed clickjackingiem — atakiem, w którym złośliwa strona ładuje formularz logowania lub płatności w niewidocznym iframe i nakłania odwiedzających do kliknięcia przycisków, których nie widzą.

To ważne dla diagnozy. Prawdziwa awaria połączenia — ERR_CONNECTION_REFUSED po otwarciu adresu bezpośrednio w karcie — to problem serwera lub zapory, opisany w artykule ERR_CONNECTION_REFUSED. Wersja z iframe pojawia się tylko wtedy, gdy strona jest osadzana, a ten sam adres w osobnej karcie działa bez zarzutu. Jeśli witryna ładuje się bezpośrednio, ale nie w Twojej ramce, masz do czynienia z polityką osadzania, a nie z awarią.

Jak działa X-Frame-Options

X-Frame-Options to nagłówek odpowiedzi HTTP, opisany po raz pierwszy w RFC 7034 — informacyjnym RFC, które obecnie zastępuje standard HTML — i obsługiwany przez każdą przeglądarkę od Internet Explorera 8. Serwer dołącza go do strony; przeglądarka odczytuje go przed renderowaniem i decyduje, czy strona może pojawić się wewnątrz <frame>, <iframe>, <embed> lub <object> na innej stronie.

Ma dwie wartości, które wciąż mają znaczenie, i jedną, która już nie ma:

Nagłówek działa dla każdej odpowiedzi osobno, a nie dla całej witryny. To szczegół, który większość poradników pomija, a który umożliwia rozwiązanie z tego artykułu: serwer może wysyłać SAMEORIGIN na 99% stron i inną politykę na jednej ścieżce przeznaczonej do osadzania.

DENY czy SAMEORIGIN: który wysłać?

Wysyłaj SAMEORIGIN, chyba że masz powód, by tego nie robić. Blokuje każdą ramkę z zewnątrz, a Twoja witryna nadal może osadzać własne strony — widżety pomocy, podglądy, panele ładujące inne wewnętrzne strony.

Wysyłaj DENY na stronach, na których osadzanie nie ma uzasadnienia, a skutki nadużycia są poważne: formularze logowania, strony płatności, akcje jednym kliknięciem, takie jak „usuń konto”. DENY obejmuje też subtelny przypadek, gdy atakujący zdoła wstrzyknąć ramkę na jedną z Twoich stron — przy SAMEORIGIN taka wstrzyknięta ramka nadal byłaby dozwolona.

Cokolwiek wybierzesz, ustaw to raz na poziomie serwera WWW lub CDN, aby obejmowało każdą odpowiedź, w tym strony błędów i zasoby statyczne. Nagłówki ustawiane w kodzie aplikacji często omijają stronę 404 i stronę prac serwisowych, więc ustawiaj je tam, gdzie przechodzi każda odpowiedź.

ALLOW-FROM nie żyje — nie używaj go

Starsze artykuły wciąż polecają X-Frame-Options: ALLOW-FROM https://partner.com, aby zezwolić na jedną osadzającą witrynę. Nigdy nie działało w Chrome ani Safari, a Firefox porzucił je w wersji 70 (październik 2019). Co gorsza, nowoczesna przeglądarka widząca ALLOW-FROM uznaje cały nagłówek za nieprawidłowy i ignoruje go całkowicie, przez co stronę może osadzić każdy — dokładnie odwrotnie, niż zamierzałeś.

Jeśli chcesz zezwolić konkretnym witrynom, odpowiedzią jest CSP frame-ancestors, omówione dalej. X-Frame-Options potrafi powiedzieć tylko „nikt” albo „tylko ja”.

frame-ancestors: dyrektywa CSP, która go zastępuje

Content Security Policy Level 2 wprowadziło frame-ancestors — dyrektywę, która robi wszystko, co X-Frame-Options, i dodaje to, czego tamten nagłówek nie potrafi: prawdziwą listę dozwolonych źródeł. Działa w standardowym nagłówku Content-Security-Policy i przyjmuje jedno lub więcej źródeł:

# Nobody may frame this (same as X-Frame-Options: DENY)
Content-Security-Policy: frame-ancestors 'none'

# Only my own origin (same as SAMEORIGIN)
Content-Security-Policy: frame-ancestors 'self'

# My origin plus two named partners, one with a subdomain wildcard
Content-Security-Policy: frame-ancestors 'self' https://partner.example https://*.trusted.example

# Anyone may frame this — for a public embed endpoint only
Content-Security-Policy: frame-ancestors *

Zanim przełączysz się na nią, warto znać trzy szczegóły:

• Sprawdza każdego przodka, nie tylko rodzica. Jeśli strona A osadza stronę B, a B osadza Twoją stronę, dozwolone muszą być zarówno A, jak i B (CSP). Standard HTML stosuje teraz X-Frame-Options również do każdego przodka (WHATWG), ale starsze przeglądarki sprawdzały tylko rodzica lub stronę najwyższego poziomu.
• Działa wyłącznie jako nagłówek HTTP. frame-ancestors jest jawnie ignorowane, gdy CSP jest dostarczane przez znacznik <meta http-equiv> — przeglądarka musi znać politykę, zanim w ogóle zdecyduje, czy renderować dokument. To samo dotyczy X-Frame-Options. Żadnego z nich nie da się ustawić z poziomu HTML.
• Symbole wieloznaczne działają per host, nie globalnie. https://*.example.com pasuje do dowolnej subdomeny jednej witryny; sama gwiazdka * pasuje do każdego originu w internecie. W sam raz dla widżetu kalkulatora, źle dla wszystkiego, co przenosi sesję.

Co się dzieje, gdy ustawione są oba nagłówki

Większość witryn podczas migracji wysyła oba, a pierwszeństwo jest zdefiniowane: jeśli obecne jest frame-ancestors, przeglądarka je egzekwuje i ignoruje X-Frame-Options. Mówi o tym wprost specyfikacja CSP Level 2, a Chrome, Firefox, Safari i Edge stosują się do niej.

Dzięki temu bezpieczna ścieżka migracji jest prosta. Zostaw X-Frame-Options: SAMEORIGIN dla garstki starych klientów sprzed CSP 2, dodaj obok Content-Security-Policy: frame-ancestors 'self', a każda nowoczesna przeglądarka użyje reguły CSP. Kłopoty zaczynają się tylko wtedy, gdy każesz im mówić różne rzeczy — na przykład X-Frame-Options: DENY obok frame-ancestors * — wtedy nowoczesne przeglądarki zezwalają na osadzanie, a blokują je tylko bardzo stare. Zachowaj spójność, a nie będzie czego debugować.

Krok 1: znajdź nagłówek, który cię blokuje

Zanim cokolwiek zmienisz, ustal, która polityka obowiązuje. Konsola przeglądarki już podała nazwę nagłówka; curl pokaże dokładną wartość wysyłaną przez serwer. Ten przykład używa witryny z omówionego dalej przykładu praktycznego — jej główne strony są celowo zablokowane:

curl -sI https://emicalcs.com/ | grep -i -E 'x-frame-options|content-security-policy'

# Output:
# x-frame-options: SAMEORIGIN

Wracają trzy możliwości:

• x-frame-options: SAMEORIGIN lub DENY — klasyczna polityka osadzania. Zdjąć ją może tylko zmiana na tamtym serwerze.
• content-security-policy: … frame-ancestors … — polityka CSP. Przeczytaj listę źródeł; jeśli Twojego originu na niej nie ma, jesteś zablokowany. Dyrektywa bywa ukryta w długim nagłówku CSP obok script-src i podobnych, więc przeczytaj całą wartość.
• Żaden z nagłówków: osadzana witryna zezwala na ramkę, a „odrzucił połączenie” ma inną przyczynę: przekierowanie na stronę, która jest zablokowana (często strona logowania; podążaj za nim przez curl -sIL), albo nagłówek Cross-Origin-Embedder-Policy: require-corp na Twojej własnej stronie, który blokuje każdą ramkę niewyrażającą zgody i pokazuje to samo szare pole.

Krok 2: zdecyduj, kto może osadzać stronę

Wszystko dalej zależy od jednego pytania: czy kontrolujesz osadzaną witrynę?

Jeśli nie, zatrzymaj się tutaj. Nie ma obejścia po stronie klienta — ani atrybutu sandbox, ani innego src, ani flagi przeglądarki, którą mieliby Twoi odwiedzający. Właściciel witryny zdecydował, że jego strona nie ma być osadzana, a przeglądarka egzekwuje tę decyzję w jego imieniu. Możesz zamiast tego umieścić link do strony, zapytać właściciela, czy udostępnia endpoint do osadzania, albo skorzystać z oficjalnego widżetu, jeśli istnieje. Wiele usług blokujących główną witrynę takie rozwiązanie oferuje; przykład w następnej sekcji pokazuje, jak to wygląda.

Jeśli ją kontrolujesz, oprzyj się pokusie usunięcia nagłówka z całej witryny. To na nowo otwiera clickjacking na każdej stronie — także tych z sesjami i formularzami — by naprawić osadzanie na jednej. Zamiast tego zdecyduj, które konkretnie ścieżki mają być osadzane i przez kogo:

Właściwy wzorzec: zablokuj witrynę, otwórz jedną ścieżkę embed

Najczystszy przykład tego wzorca z prawdziwego świata, jaki znam, to EMICalcs — darmowy zbiór 45 indyjskich kalkulatorów finansowych (rata kredytu EMI, SIP, podatek dochodowy, GST i inne), które inne witryny mogą osadzać. Główna witryna jest zablokowana; dedykowana ścieżka /embed/ jest otwarta. Porównaj nagłówki obu:

# The calculator page a visitor normally uses — locked
curl -sI https://emicalcs.com/income-tax-calculator/ | grep -i -E 'x-frame|frame-ancestors'
# x-frame-options: SAMEORIGIN

# The same calculator on its embed path — open to any site
curl -sI https://emicalcs.com/embed/income-tax-calculator/ | grep -i -E 'x-frame|frame-ancestors'
# content-security-policy: frame-ancestors *

Zwróć uwagę, czego odpowiedź embed nie zawiera: na /embed/ nie ma w ogóle nagłówka X-Frame-Options. To celowe. Ponieważ dyrektywa CSP ma pierwszeństwo, pozostawienie SAMEORIGIN byłoby w nowoczesnych przeglądarkach nieszkodliwe — ale zmyliłoby kolejnego inżyniera czytającego nagłówki i nadal blokowałoby nieliczne stare klienty rozumiejące wyłącznie X-Frame-Options. Ścieżka embed wysyła jedną politykę i mówi dokładnie jedną rzecz.

Cała reszta witryny zachowuje SAMEORIGIN, więc strona główna, artykuły i pełne strony kalkulatorów pozostają chronione przed clickjackingiem. Wersje do osadzania to odchudzone dokumenty bez nawigacji i bez niczego, co warto przechwytywać, dlatego otwarcie ich na * jest rozsądnym kompromisem.

Ich przewodnik po osadzaniu warto przeczytać jako wzór, jeśli publikujesz własny widżet: jeden stały adres URL na kalkulator, stała wysokość pasująca do większości z nich, loading="lazy" we fragmencie kodu i obietnica, że wycofane adresy embed będą przekierowywać zamiast zwracać 404 — bo każda witryna, która Cię osadza, ufa, że Twój adres URL będzie dalej działał.

Nginx (i pułapka add_header)

Oto ten sam wzorzec w trzech miejscach, w których większość witryn ustawia nagłówki. W każdym przypadku reguła dla całej witryny blokuje wszystko, a węższa reguła nadpisuje ją dla ścieżki embed. Najpierw Nginx, bo ma pułapkę:

# Site-wide default (server block)
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Content-Security-Policy "frame-ancestors 'self'" always;
add_header X-Content-Type-Options "nosniff" always;

location /embed/ {
    # WARNING: any add_header here stops ALL add_header inheritance from the
    # server block — re-declare every header you still want on this path.
    add_header Content-Security-Policy "frame-ancestors *" always;
    add_header X-Content-Type-Options "nosniff" always;
}

Ten komentarz nie jest do pominięcia. add_header nie jest scalane między poziomami: gdy tylko blok location zadeklaruje jakikolwiek add_header, przestaje dziedziczyć wszystkie add_header z bloku server. Zespoły regularnie tracą w ten sposób nagłówki HSTS czy nosniff na ścieżce embed i dowiadują się o tym dopiero miesiące później ze skanu bezpieczeństwa. Zadeklaruj ponownie to, czego potrzebujesz, i pomiń X-Frame-Options w bloku embed, aby ścieżka wysyłała jedną jasną politykę. Od nginx 1.29.3 add_header_inherit merge może włączyć dziedziczenie z powrotem (nginx), ale nie używaj go w bloku embed: dodałoby ogólnowitrynowe X-Frame-Options i frame-ancestors 'self' z powrotem do tej ścieżki, a przy dwóch nagłówkach CSP przeglądarka egzekwuje oba, więc ramka pozostaje zablokowana.

Apache

Dyrektywa Header w Apache scala się między zakresami, więc możesz ustawić wartość domyślną raz i zmienić tylko dwa nagłówki na ścieżce embed:

# Site-wide default (needs mod_headers)
Header always set X-Frame-Options "SAMEORIGIN"
Header always set Content-Security-Policy "frame-ancestors 'self'"

<LocationMatch "^/embed/">
    Header always unset X-Frame-Options
    Header always set Content-Security-Policy "frame-ancestors *"
</LocationMatch>

Next.js i Express

W Next.js nagłówki deklaruje się w next.config.js. Gdy dwie reguły pasują do tej samej ścieżki i ustawiają ten sam nagłówek, wygrywa późniejsza — ale nagłówek ustawiony tylko przez wcześniejszą regułę nadal obowiązuje. Aby X-Frame-Options w ogóle nie trafiał na ścieżkę embed, wyłącz go z reguły dla całej witryny za pomocą negatywnego wyprzedzenia (negative lookahead):

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        // Every path EXCEPT /embed/... gets the locked defaults
        source: '/((?!embed/).*)',
        headers: [
          { key: 'X-Frame-Options', value: 'SAMEORIGIN' },
          { key: 'Content-Security-Policy', value: "frame-ancestors 'self'" },
        ],
      },
      {
        source: '/embed/:path*',
        headers: [
          { key: 'Content-Security-Policy', value: 'frame-ancestors *' },
        ],
      },
    ]
  },
}

W Express popularny middleware helmet domyślnie wysyła już X-Frame-Options: SAMEORIGIN oraz CSP zawierające frame-ancestors 'self'. Zamontuj go globalnie, a następnie w routerze embed wywołaj res.removeHeader('X-Frame-Options') i ustaw Content-Security-Policy na frame-ancestors * przed renderowaniem. Kolejność ma znaczenie: Twoje nadpisanie musi działać po helmet, inaczej helmet je nadpisze.

Bezpieczne osadzanie widżetu zewnętrznego dostawcy

Teraz druga strona barykady: to Ty osadzasz, dostawca ma otwartą ścieżkę embed, a Ty chcesz, by ramka zachowywała się poprawnie. Dobrze zrobiony fragment widżetu wygląda tak; jest to ten, który EMICalcs publikuje na każdej stronie kalkulatora:

<iframe src="https://emicalcs.com/embed/income-tax-calculator/"
        title="Income Tax Calculator FY 2026-27 — EMICalcs"
        width="100%" height="760"
        style="max-width:680px;border:0;border-radius:16px;overflow:hidden"
        loading="lazy"></iframe>
<p>Free <a href="https://emicalcs.com/income-tax-calculator/" target="_blank" rel="noopener">Income Tax Calculator FY 2026-27</a> by EMICalcs</p>

Każdy atrybut ma swoje zadanie:

• title — nadaje ramce nazwę dla czytników ekranu. Bez niego technologia asystująca ogłasza tylko „ramka”, a audyty dostępności oblewają stronę.
• width="100%" z max-width w style — wypełnia wąskie kolumny na telefonach, nie wylewając się poza szerokie na komputerach.
• Stała height — strona osadzająca nie może odczytać wysokości zawartości ramki z innego originu, więc wpisana na stałe wartość to jedyny sposób, by uniknąć przesunięcia układu podczas ładowania. Ustaw ją raz dla każdego widżetu.
• loading="lazy" — odkłada żądanie do chwili, gdy ramka zbliży się do widocznego obszaru, więc widżet na dole długiego artykułu nic nie kosztuje przy pierwszym ładowaniu.
• border:0; border-radius; overflow:hidden — usuwa domyślną wciętą ramkę i przycina rogi, aby widżet wyglądał naturalnie na Twojej stronie.

Linia z podaniem źródła znajduje się celowo poza iframe. Wszystko wewnątrz ramki należy do osadzonego dokumentu — jego linki to linki dostawcy, pod adresem dostawcy — więc link wewnątrz ramki nie jest częścią Twojej strony w oczach Twoich czytelników ani robota wyszukiwarki. Jeśli chcesz wskazać źródło albo dostawca o to prosi, umieść zwykły akapit obok ramki we własnym HTML, jak wyżej.

sandbox: co zezwolić dla widżetu kalkulatora

Atrybut sandbox to własna ochrona osadzającego. Dodaj go bez wartości, a osadzona strona nie dostaje niczego: żadnych skryptów, formularzy, wyskakujących okien, nawigowania Twoim oknem, a do tego dostaje nieprzejrzysty origin, który wyłącza jej własne ciasteczka i pamięć. Potem dodaj z powrotem tylko to, czego widżet potrzebuje:

<iframe src="https://emicalcs.com/embed/loan-emi-calculator/"
        sandbox="allow-scripts allow-forms allow-same-origin allow-popups"
        title="Loan EMI Calculator — EMICalcs"
        width="100%" height="760" loading="lazy"></iframe>

allow-scripts i allow-forms to minimum dla wszystkiego, co interaktywne. allow-same-origin pozwala osadzonej stronie zachować własny origin, dzięki czemu działają jej pamięć i ciasteczka — przy osadzeniu z innego originu jest to bezpieczne, bo „jej origin” to nadal origin dostawcy, a nie Twój. allow-popups jest potrzebne tylko wtedy, gdy widżet otwiera linki w nowej karcie, jak robi to link z podaniem źródła wewnątrz osadzenia EMICalcs.

Czego nie należy robić, to łączyć allow-scripts z allow-same-origin w ramce wskazującej na Twój własny origin. Osadzony skrypt może wtedy sięgnąć wyżej i usunąć własny atrybut sandbox, a Ty nie zabezpieczyłeś niczego.

Dlaczego po stronie osadzającego nie ma rozwiązania

Wyszukanie „iframe odrzucił połączenie” pokazuje trzy popularne obejścia. Wszystkie są złe i warto dokładnie wiedzieć dlaczego.

• Rozszerzenia przeglądarki usuwające X-Frame-Options — działają tylko w Twojej przeglądarce. Każdy odwiedzający Twoją witrynę nadal widzi szare pole, a Ty tymczasem wyłączasz ochronę przed clickjackingiem na każdej odwiedzanej witrynie.
• Przepuszczanie strony przez własny serwer — pobierasz HTML zewnętrznej witryny po stronie serwera i serwujesz go ze swojego originu, więc nagłówek nigdy nie dociera do przeglądarki. To psuje linki względne, ciasteczka, logowania i wszystko oparte na skryptach; bierzesz na siebie odpowiedzialność za ich treść; i zwykle łamie to regulamin dostawcy. Witryny, które to wykryją, blokują adres IP Twojego serwera.
• Usługi zrzutów ekranu lub „web-to-image” — dostajesz statyczny obrazek, a nie działającą stronę. Dobre na miniaturę podglądu, bezużyteczne dla kalkulatora.

Nagłówek to oświadczenie właściciela witryny, egzekwowane przez przeglądarkę, o tym, co wolno robić z jego stroną. Jedyne uczciwe drogi to dwie już omówione: właściciel otwiera ścieżkę embed albo Ty linkujesz na zewnątrz. Dostawcy, którzy chcą być osadzani, ułatwiają to — dobrzy publikują fragment kodu, utrzymują stały adres URL i otwierają tylko ścieżkę, którą bezpiecznie otworzyć.

Sprawdzaj nagłówki po każdej zmianie

Nagłówki osadzania ustawia się w pliku konfiguracyjnym i zapomina o nich, a CDN, reverse proxy lub wtyczka bezpieczeństwa z dobrymi intencjami mogą je w każdej chwili dodać, usunąć lub zduplikować. Po wdrożeniu sprawdź je spoza własnej sieci:

# The locked pages should show SAMEORIGIN and/or frame-ancestors 'self'
curl -sI https://example.com/ | grep -i -E 'x-frame-options|content-security-policy'

# The embed path should show ONLY frame-ancestors, with the sources you intended
curl -sI https://example.com/embed/widget/ | grep -i -E 'x-frame-options|content-security-policy'

# Error pages should carry the header too
curl -sI https://example.com/this-does-not-exist | grep -i -E 'x-frame-options|content-security-policy'

Potem przetestuj to tak, jak robi to przeglądarka: umieść adres embed w <iframe> na stronie serwowanej z innego originu — lokalna strona file:// się nie nadaje, bo przeglądarki traktują ją specjalnie — i otwórz konsolę. Czyste załadowanie oznacza brak linii Refused to display lub Refused to frame.

Jeśli witryna stoi za Cloudflare lub innym CDN, kopia z pamięci podręcznej albo reguła na brzegu może mieć inne nagłówki niż Twój serwer źródłowy. Checker nagłówków HTTP pobiera adres z naszego serwera, spoza Twojej przeglądarki i sieci, i pokazuje X-Frame-Options oraz Content-Security-Policy wraz z werdyktem dotyczącym osadzania (SAMEORIGIN lub DENY, przez CSP frame-ancestors, lub niewysłane): to szybki sposób na wychwycenie reguły CDN, która po cichu przywróciła SAMEORIGIN na Twojej ścieżce embed.

Objaw → przyczyna → rozwiązanie

Użyj tego, by przejść od razu do rozwiązania zamiast czytać cały poradnik od nowa:

Jeśli adres zawodzi także w osobnej karcie, ramka jest fałszywym tropem. Przejdź warstwy sieci po kolei — DNS, port, TLS, nagłówki — według poradnika testowania publicznego endpointu, zanim ruszysz jakiekolwiek nagłówki osadzania.