ContextQMD
Back to Chromium

Core Concepts

components/guest_contents/README.md

149.0.7827.212.5 KB
Original Source

GuestContents is an experimental component that allows you to embed an independent content::WebContents (a "guest") within an outer content::WebContents, which is typically a WebUI page. This is useful for displaying external web content inside your WebUI in a sandboxed way, similar to the functionality of the <webview> tag in Chrome Apps.

The core mechanism involves swapping an <iframe> in the outer WebUI's renderer process with the main frame of the guest WebContents from the browser process. This process is orchestrated via the GuestContentsHost Mojo interfaces.

GuestContents is NOT for production use due to privacy and security reasons. See Security Considerations.

Core Concepts

  • Guest WebContents: The WebContents instance that you want to embed.

  • Outer WebContents: The host WebContents, which is your WebUI page.

  • GuestContentsHandle: A browser-side handle for the guest WebContents. It assigns a unique GuestId to the guest and manages its attachment to an outer WebContents. Its lifetime is tied to the guest WebContents.

  • guest_contents::mojom::GuestContentsHost: A Mojo interface implemented in the browser process. The outer WebUI's renderer calls this interface to request the attachment of a guest. The WebUI's WebUIController handles the binding of this interface via a BindInterface() method.

  • guest_contents::renderer::SwapRenderFrame: A renderer-side C++ function that initiates the guest attachment process by calling the GuestContentsHost Mojo interface.

How-To Guide

Here is a step-by-step guide to embedding a guest WebContents in your WebUI. webui_examples uses this pattern and is a good example to follow.

1. Browser-Side Setup

In your WebUI's browser-side C++ code:

  • Register the GuestContentsHost interface in ContentBrowserClient for your WebUIController.

    c++
    // ui/webui/examples/browser/content_browser_client.cc
void ContentBrowserClient::RegisterBrowserInterfaceBindersForFrame(...) {
  // ...
  // `Browser` is a WebUIController.
  RegisterWebUIControllerInterfaceBinder<
      guest_contents::mojom::GuestContentsHost, Browser>(map);
}

  • Bind the GuestContentsHost Mojo Interface: Your WebUI controller must expose the GuestContentsHost interface to its renderer.

    c++
    // ui/webui/examples/browser/ui/web/browser.h
class Browser : public ui::MojoWebUIController, ... {
  // ...
  void BindInterface(
      mojo::PendingReceiver<guest_contents::mojom::GuestContentsHost> receiver);
  // ...
};

// ui/webui/examples/browser/ui/web/browser.cc
void Browser::BindInterface(
    mojo::PendingReceiver<guest_contents::mojom::GuestContentsHost> receiver) {
  guest_contents::GuestContentsHostImpl::Create(web_ui()->GetWebContents(),
                                                std::move(receiver));
}

  • Create and Own the Guest WebContents: For example, in your WebUIController's constructor, create the guest WebContents.

    c++
    // ui/webui/examples/browser/ui/web/browser.h
class Browser : public ui::MojoWebUIController, ... {
  // ...
  std::unique_ptr<content::WebContents> guest_contents_;
};

// ui/webui/examples/browser/ui/web/browser.cc
Browser::Browser(content::WebUI* web_ui)
    : ui::MojoWebUIController(web_ui, false) {
  content::BrowserContext* browser_context =
      web_ui->GetWebContents()->GetBrowserContext();
  // ...
  content::WebContents::CreateParams params(browser_context);
  guest_contents_ = content::WebContents::Create(params);
  // ...
}

  • Create a GuestContentsHandle and Pass its ID to the Frontend: The handle provides the unique ID needed to identify the guest. Pass this ID to your frontend JavaScript, for example, using loadTimeData or via a Mojo interface. The following example uses loadTimeData.

    c++
    // ui/webui/examples/browser/ui/web/browser.cc
Browser::Browser(content::WebUI* web_ui) : ... {
  // ... (create guest_contents_)
  guest_contents::GuestContentsHandle::CreateForWebContents(
      guest_contents_.get());
  auto* guest_handle = guest_contents::GuestContentsHandle::FromWebContents(
      guest_contents_.get());
  html_source->AddString("guest-contents-id",
                         guest_handle->id().ToString());
}

2. Renderer-Side Setup (C++)

To bridge the gap between your frontend JavaScript and the browser process, you need some C++ code in the renderer.

  • Expose C++ Bindings to JavaScript: Inject functions into the renderer's JavaScript context. The example uses a RenderFrameObserver to add a webshell object with C++-backed functions when the WebUI is ready.

    c++
    // ui/webui/examples/renderer/render_frame_observer.cc
void RenderFrameObserver::ReadyToCommitNavigation(...) {
  V8BinderContext binder_context(render_frame());
  binder_context.CreateWebshellObject();
  binder_context.AddCallbackToWebshellObject(
      "attachIframeGuest", base::BindRepeating(&AttachIframeGuest));
  // ...
}

  • Implement the Binding: The AttachIframeGuest function gets the content::RenderFrame* for the <iframe>, and calls the guest_contents helper function.

    c++
    // ui/webui/examples/renderer/render_frame_observer.cc
void AttachIframeGuest(const std::string& guest_contents_id,
                       v8::Local<v8::Object> content_window) {

  content::RenderFrame* render_frame = GetRenderFrame(args[1]);
  // ...
  auto parsed_guest_contents_id =
      base::UnguessableToken::DeserializeFromString(guest_contents_id);
  if (parsed_guest_contents_id.has_value()) {
      guest_contents::renderer::SwapRenderFrame(
              render_frame, parsed_guest_contents_id);
  }
}

This SwapRenderFrame function handles the final step of calling the GuestContentsHost.Attach Mojo method, which completes the attachment in the browser process.

3. Renderer-Side Setup (TypeScript/HTML)

In your WebUI's frontend code, add a placeholder element that will be swapped with the guest. An <iframe> is a good choice, although other frame-like element might also work. In the following example, <webview> is a custom web component that has a <iframe> child element.

html
<!-- ui/webui/examples/resources/browser/index.html -->
<webview id="webview"></webview>

In your TypeScript/JavaScript, get the guest-contents-id from loadTimeData. Then, call a C++ binding to trigger the attachment. The example uses a webshell object injected into the renderer for this communication.

typescript
// ui/webui/examples/resources/browser/index.ts
class WebviewElement extends HTMLElement {
  public iframeElement: HTMLIFrameElement;
  private guestContentsId: string;

  constructor() {
    super();
    this.iframeElement = document.createElement('iframe');
    this.appendChild(this.iframeElement);

    this.guestContentsId = loadTimeData.getString('guest-contents-id');
    const iframeContentWindow = this.iframeElement.contentWindow;

    // This is the key call that triggers the C++ logic.
    webshell.attachIframeGuest(this.guestContentsId,
                               iframeContentWindow);
  }
  // ...
}

4. Controlling the Guest

GuestContents provides only basic embedding functionalities, including sizing, painting and event routing. The WebUI needs to provide their own implementation for additional controls over the guest.

Navigation is a common and concrete example of additional control. To add support for navigation, you can:

  • Define a Mojo Interface: Add methods like Navigate, GoBack, and GoForward to your WebUI's page handler Mojo interface.

  • Implement in the Browser: Implement these methods in your PageHandler class. They should retrieve the guest WebContents from your WebUI controller and use its NavigationController.

  • Call from the Frontend: Call these Mojo methods from your TypeScript code to control the guest's navigation, for example, from back/forward button events.

GuestContents vs GuestView

While both GuestContents and GuestView are used for embedding web content, they are designed for different use cases and have significant architectural differences, primarily due to the ongoing migration of GuestView to MPArch.

Core Distinction: Inner WebContents vs. MPArch

The fundamental difference lies in how the guest content is hosted:

  • GuestContents was created to explicitly retain the use of inner WebContents. This allows the embedder to have direct access to the guest's WebContents instance and its full API. This is critical for use cases that need to attach TabHelpers (e.g., for autofill, permissions, downloads) and interact deeply with the guest's state and navigation, such as when embedding a full-featured browser tab.

  • GuestView is migrating to MPArch (Multiple Page Architecture) and will no longer use inner WebContents. Instead, the guest is hosted in a GuestPageHolder. This abstracts the guest's WebContents away from the embedder, providing stronger isolation but preventing the direct API access that GuestContents allows.

Lifetime Management

The ownership model for the guest WebContents is another key differentiator:

  • In GuestContents, the lifetimes of the inner (guest) and outer WebContents are decoupled. The client that creates the inner WebContents is responsible for its lifetime. The outer WebContents does not own the guest, which allows for flexible scenarios like detaching a guest and re-attaching it elsewhere (e.g., dragging a tab out of a window).

  • In GuestView, the outer WebContents typically owns the guest WebContents after it is attached.

API and Complexity

  • GuestContents offers a simpler, more direct API focused purely on embedding.

  • GuestView can be more complex, especially when used via extension's <webview> tag, which brings in extension-specific concepts and dependencies that may be unnecessary for non-extension use cases.

Security Considerations

GuestContents inherits the security posture of the underlying primitives in //content and Blink. It is not inherently more or less secure than the pre-MPArch GuestView model, as both rely on the same complex mechanisms. This complexity can make security analysis difficult and may be a source of vulnerabilities.

Under the hood,

  • At the WebContents level: The guest and outer WebContents are connected via WebContentsTreeNode after a call to WebContents::Attach(Unowned)InnerWebContents(). This creates a relationship (e.g., WebContents::GetOuterWebContents()) that adds complexity where greater isolation would be ideal. This is used by GuestContents and pre-MPArch GuestView.

  • At the frame level: The outer <iframe> element and the guest's main frame are connected by a RenderFrameProxyHost. In Blink, this is represented as a blink::RemoteFrame. This used by all embedding techniques, including GuestContents, standard <iframe>, and both pre- and post-MPArch GuestView.

Reusing the general-purpose <iframe>-related primitives is considered a primary security risk. This IPC channel provides a much larger API surface than is strictly necessary for embedding a guest, including features like window.opener and window.postMessage(). Future changes to <iframe> implementation could unintentionally introduce vulnerabilities or break the security isolation between a guest and its embedder.

The long-term goal (https://crbug.com/416609971) is to develop more minimal, purpose-built primitives for embedding that expose only the essential IPCs for painting, sizing, and event routing, thereby reducing the potential attack surface.