Windows, iframes & postMessage

Several windows, one careful page

A web app is not always one page in one tab. It often uses other windows too:

• A popup: a new tab or window, for example for signing in.
• An iframe: a box inside your page that shows another page, for example a payment form.
• A sandboxed frame: an iframe with most of its powers turned off, for content you don't trust.

Each of these is a browsing context: a separate place where a page lives. Each one has its own window object.

The main idea of this lesson is: a reference is not permission. A reference is a variable that points at another window. Holding one doesn't mean you can look inside. The browser still decides what you may read, change, or send.

The browser decides with the same-origin policy from the CORS lesson. Two pages have the same origin when their scheme (like https), host, and port all match. Only then may one page freely read the other.

When one page opens a new one, the new page gets window.opener. That is a reference back to the page that opened it. An untrusted new page can use it to send your page to a fake login page. This attack is called reverse-tabnabbing.

The noopener option cuts that reference, so the new page sees null. For a link, write target="_blank" together with rel="noopener". That attribute does the same job for links as the noopener option does for window.open.

The table compares the two kinds of extra window. Each row is one question, answered for a popup and for an iframe.

This lesson teaches five safe habits:

1. Open a popup only when the user clicks.
2. Treat a frame from another origin as closed.
3. Send each message to one named origin.
4. Check every message when it arrives.
5. Stop other sites from putting your important pages in a frame.

A popup is a new tab or window. JavaScript opens one with window.open(url, target, features):

• url is the page to load.
• target is a name for the new window.
• features is a text list of options, such as the size or noopener.

It returns a reference to the new window. But browsers have popup blockers. They usually allow a popup only when window.open runs right inside a user action, such as a button click. This is called a user gesture. A call from a timer or from page load is often blocked. Then window.open returns null.

Safe popup code has four steps:

1. Open the popup from a click.
2. Check whether you got null.
3. Use only what the browser allows.
4. Close the popup when you are done.

const link = document.createElement("a");
link.href = "https://news.example";
link.target = "_blank";
link.rel = "noopener";
console.log(link.rel);

const popup = { opener: null };
console.log(popup.opener);

Lines 1 to 4 build a link that opens news.example in a new tab, with rel="noopener". Line 5 prints noopener. Line 7 makes a stand-in object for a new tab opened with noopener. Its opener is null, so line 8 prints null.

The lab below opens about:blank. That is an empty page with the same origin as the page that opened it, so the lab may write into it. The lab writes a heading, reads the popup's closed property, and closes it. The second button opens a popup with noopener. It shows that window.open then returns null.

1button.addEventListener("click", () => {2  const popup = window.open("about:blank", "lessonPopup", "width=360,height=240");3  if (!popup) return "blocked";4  popup.document.write("<h1>Hello from the opener</h1>");5  console.log(popup.closed);6  popup.close();7});8 9const safePopup = window.open("about:blank", "_blank", "noopener");10console.log(safePopup);

Iframes and same-origin access

An iframe element shows another page inside the current page. The page around it is called the parent. What the parent may do depends on the frame's origin:

• Same origin: the parent may read and change the frame's DOM (its elements), call its functions, and use the same storage.
• Another origin: the parent still gets a reference to the frame's window. But most reads through it throw a SecurityError.

<iframe id="preview" srcdoc="<p>Preview</p>"></iframe>

const frame = document.querySelector("#preview");
console.log(frame.contentDocument.body.textContent);
console.log(frame.contentWindow === frame.contentDocument.defaultView);

Line 1 is an iframe. Its srcdoc attribute holds the frame's HTML right in the attribute. A page made this way has the same origin as the parent, so the parent may read it.

• Line 3 finds the iframe element.
• Line 4 reads the frame's text through contentDocument, the frame's document.
• Line 5 checks that contentWindow, the frame's window object, is the window of that same document.

If src pointed to another origin, contentWindow would still exist. But contentDocument would be null, and reading the frame's document through its window would throw.

The table sums this up. Each row is one kind of frame: what your code can usually do with it, and what it can't.

A frame from another origin still allows a short list of things through its window reference:

• Send it a message with postMessage.
• Call focus, blur, or close.
• Read a few simple properties: closed, length, and frames.
• Set its location to load a new page, in limited ways.

It can't read the other page's DOM, cookies, storage, variables, or full URL.

Frames can hold frames, so the windows on a page form a tree, like folders inside folders. Each window has names for the windows around it.

const frame = document.querySelector("iframe");
console.log(window.parent === window);
console.log(window.top === window);
console.log(window.frames.length);
console.log(frame.contentWindow === window.frames[0]);

• Line 1 finds the iframe element.
• Line 2 checks whether parent, the window just outside this one, is this window itself.
• Line 3 checks whether top, the outermost window, is this window itself.
• Line 4 prints how many child frames this page has.
• Line 5 checks that frames[0] is the same window as the iframe's contentWindow.

The table lists these names. Read each row as: this name, what it points to, and when you use it.

On a page that is not inside a frame, window.parent === window and window.top === window are both true. Inside an iframe, parent is the page just outside it, and top is the outermost page. These names only point at windows. They don't get past the origin checks.

Two windows from different origins can't read each other. They can still work together by sending messages. The sender calls otherWindow.postMessage(data, targetOrigin). A little later, the other window gets a message event. The event has three parts you will check:

• event.data: a copy of what was sent.
• event.origin: the origin of the page that sent it.
• event.source: the window object that sent it.

targetOrigin is the origin the receiving window must have. If that window has moved to a page from another origin, the browser doesn't deliver the message.

Sandboxed frames need extra care. A sandboxed frame is an iframe with the sandbox attribute, which turns off most of its powers. Without the allow-same-origin token, the frame gets an opaque origin: an origin with no name. Message events show it as the text "null".

You can't write an opaque origin as a targetOrigin. So to send to such a frame, you must use "*", which means "any origin". That makes the checks on the receiving side even more important.

1const frame = document.querySelector("iframe");2const trustedWindow = frame.contentWindow;3 4window.addEventListener("message", (event) => {5  if (event.origin !== "null") return;6  if (event.source !== trustedWindow) return;7  show("accepted", event.data);8});9 10trustedWindow.postMessage({ kind: "ping" }, "*");

The lab has two sandboxed frames made from srcdoc. Both have the origin "null". Only one is the trusted frame: its contentWindow is saved in trustedWindow. The stranger frame can send the same data, but it fails the event.source check.

Step through the same checks below. Pick the trusted frame or the stranger, then watch lines 5 and 6 decide.

1const trustedOrigin = "null";Run2const trustedFrame = "lesson-frame";3 4function receiveMessage(event) {5  const originOK = event.origin === trustedOrigin;6  const sourceOK = event.source === trustedFrame;7  if (!originOK || !sourceOK) return "rejected";8  return "accepted: " + event.data.kind;9}10 11receiveMessage(incomingEvent);

The message data is copied with structured clone: the browser makes a full copy of the data for the other window. The two windows never share one object. Functions and DOM elements can't be copied, so you can't send them. The next lesson covers copying in detail. Here, the habit to learn is: check a message before you act on it.

function acceptMessage(data) {
  if (!data || data.type !== "cart-ready" || typeof data.id !== "number") return "reject";
  return "accept";
}
console.log(acceptMessage({ type: "cart-ready", id: 3 }));
console.log(acceptMessage({ type: "cart-ready", id: "3" }));

• Line 2 returns "reject" unless type is "cart-ready" and id is a number.
• Line 5 passes an id of 3, a number, so it prints accept.
• Line 6 passes "3", a string that only looks like a number. typeof gives "string", so it prints reject.

The origin and source checks tell you who sent a message. This check makes sure the data is what your code expects.

The sandbox attribute starts an iframe with most of its powers turned off. An empty sandbox blocks scripts, forms, popups, and dialogs. It also takes away the frame's real origin.

You add powers back one at a time with tokens: words you list in the attribute. Each token turns one power back on:

• allow-scripts lets scripts run.
• allow-forms lets forms submit.
• allow-popups lets the frame open popups.
• allow-modals lets it show dialogs, such as alert.
• allow-same-origin keeps the frame's real origin instead of "null".

<iframe
  sandbox="allow-scripts"
  allow="fullscreen; payment"
  srcdoc="<p>Limited preview</p>"
></iframe>

Line 2 lets this frame run scripts, and nothing else from the sandbox list. Line 3 is a different attribute, allow. It is a permissions policy: it turns on chosen browser features, here full screen and payments.

The two attributes do different jobs. sandbox limits what the page may do. allow turns on browser features. So allow="payment" does not let a frame read the parent page.

1// The parent rebuilds the iframe with selected tokens.2frame.sandbox = "allow-scripts allow-forms";3frame.srcdoc = predefinedHtml;4 5// Inside predefinedHtml:6parent.postMessage({7  scriptRan: true,8  origin: self.origin,9  canSubmitForms: sandbox.contains("allow-forms"),10  canOpenPopups: sandbox.contains("allow-popups"),11  canShowModals: sandbox.contains("allow-modals")12}, "*");

That's why the sandbox demo in the CORS lesson and the message lab here both use fixed srcdoc HTML with sandbox="allow-scripts". The code can run, but the frame keeps an opaque origin. Everything it says goes through a few checked messages.

Clickjacking tricks a user into clicking a button on another page. It is also called UI redressing. It doesn't read the other page. It works like this:

1. The attacker puts an important page, such as a bank page, in an iframe on their own site.
2. They make that frame invisible and show a harmless-looking decoy instead.
3. They line up the bank's real button with the decoy's fake button.
4. The user clicks the fake button, but the click lands on the real one.

In the lab, a decoy covers a fake bank frame. Lower the decoy's opacity to see the page hiding behind it.

1<iframe title="fake bank" sandbox srcdoc="...bank button..."></iframe>2<div class="decoy">3  <p>Looks like a video player.</p>4  <button>Play</button>5</div>6 7/* Lower the decoy opacity to reveal the hidden frame underneath. */

The fix belongs to the important page, not to the user. The table lists the defenses. Each row says who sets the defense and what it does.

// Response headers, sent before the page is framed
X-Frame-Options: DENY
Content-Security-Policy: frame-ancestors 'none'

A response header is a line of information the server sends along with the page. Line 2 tells the browser that no page may show this page in a frame. Line 3 says the same thing in the newer Content-Security-Policy way. The browser reads these headers before it shows the page, so it can refuse the frame before anyone clicks.

This lesson page doesn't send these headers, because it has no important buttons to protect. An admin site, an account settings page, or a payment page should send them. On this site, the admin pages send X-Frame-Options: DENY.

Where you will use this

You will meet these tools in everyday web work:

• Signing in with another site. Open the sign-in site in a popup from a click. When sign-in ends, the last page in the popup sends one success message back to your page.
• Payment forms. Show the payment company's page in an iframe. Send it setup data with its exact targetOrigin. Accept only messages from its origin and its window.
• Content previews. Show a draft page in a sandboxed iframe, so it can't change the editor page. The preview sends messages for things like its height.
• Live code demos. Run demo code in sandboxed srcdoc frames. The frame sends results back as messages, and the page checks each one.

Common misconceptions

Your score counts first tries. Every choice has an explanation, so read them even when you get it right.

Key takeaways

• Open a popup only from a user click. Check for null, and use noopener so the new page can't reach back.
• Your page may read an iframe from its own origin. An iframe from another origin is closed, but you can still send it messages.
• postMessage sends a copy of the data. It arrives a little later as a message event.
• Before acting on a message, check event.origin, event.source, and the fields of event.data.
• A sandbox turns off a frame's powers, and tokens turn them back on one by one. Don't give a same-origin page both allow-scripts and allow-same-origin.
• Server headers stop clickjacking: X-Frame-Options and CSP frame-ancestors.

Up next: Messaging & structured cloning.