Connection Allowlist Design

References:

• Explainer
• Spec
• Chrome Status Entry
• Design Document

Summary

Connection Allowlist restricts network connections in Chromium using a URLPattern allowlist returned by the server. The high-level flow is:

• The allowlist is returned in the HTTP response when loading a given context (document or worker)
• A network_restrictions_id is assigned to that context, which is used to identify requests that originate from it
• Enforcement then focuses on blocking requests containing that ID based on the mapped allowlist.

This document outlines the architectural design and the checks performed across different Chromium layers (network service, browser, renderer).

All security and resource restrictions (CSP, Connection Allowlists, etc.) are applied restrictively and additively. A request must satisfy all applicable security policies to proceed; if any policy blocks the request, the request is blocked.

Design

Network service integration

The network service is the primary layer where network requests are handled and dispatched. The majority of Connection Allowlist enforcement occurs here.

• Responsibilities:
  • Intercept and filter outgoing network requests.
  • Apply allowlist rules at the URLLoader level (including document-initiated prefetches which are associated with the document's network_restrictions_id).
  • Enforce allowlists for other networking APIs like WebSockets, DNS Prefetch, and WebTransport.
• Benefits:
  • Defense-in-Depth: Since enforcement occurs in the Network Service process, compromised renderer processes cannot bypass these checks.
  • Centralized Enforcement: The Network Service handles HTTP/HTTPS requests, WebSockets, and WebTransport. Enforcing allowlists at this level provides a single, uniform point of control across different network protocols.
  • Semantic Consistency: Once registered, allowlist matching happens within the Network Service process. This ensures that the same set of rules is applied to all requests regardless of where they originated (e.g. fetch, fetch redirects, prefetch, worker, etc.).
  • Extensibility: The token-based mapping (network_restrictions_id) is highly extensible. Other future security features or JS-based network restriction APIs (similar to the dynamic window.fence.disableUntrustedNetwork() design previously used for Fenced Frames, see CL 7709872) can leverage this same plumbing to dynamically register and enforce rules in the Network Service.

Network restrictions ID (network_restrictions_id)

To map network requests back to the corresponding context (document or worker) and its connection allowlists, each context is associated with a unique token, the network_restrictions_id (a base::UnguessableToken).

• Creation & Propagation:
  • During cross-document navigation, a new network_restrictions_id is created on the NavigationRequest in NetworkRestrictionsNavigationThrottle.
  • Upon navigation commit, this ID is wrapped in a ref-counted handle (base::RefCountedData<base::UnguessableToken>) and stored in the document's DocumentAssociatedData (or worker hosts like DedicatedWorkerHost and SharedWorkerHost).
  • Ref-counting is used because there are edge cases where multiple documents can share the same network_restrictions_id (e.g., initial empty documents inheriting their creator's ID).
• Updating the Network Service:
  • If a document has active connection allowlists (enforced or report-only) determined from policy container policies, the browser process registers them via StoragePartitionImpl::RestrictNetworkForIdsInNetworkContext.
  • This sends the ID and allowlisted patterns to the NetworkContext in the Network Service using RestrictNetworkForIds().
  • The navigation is deferred during the throttle check (WillProcessResponse / WillCommitWithoutUrlLoader) until the Network Service confirms the restrictions have been registered, ensuring restrictions are applied before resource loading begins.
• Backup & Recovery:
  • StoragePartitionImpl stores a copy of the restrictions in network_restrictions_ids_. In case of a Network Service crash, this map is used to restore the network restrictions on the new NetworkContext.
• Lifetime & Cleanup:
  • When a document's DocumentAssociatedData or worker is destroyed, if it holds the last reference to the ref-counted network_restrictions_id, it schedules a cleanup of the restriction mapping from the Network Service and StoragePartitionImpl using StoragePartitionImpl::ClearNetworkRestrictionsAfterDelay.
  • Selecting the ID at Calling Sites: When a calling site initiates a request or creates a connection (e.g. WebSocket, WebTransport) that expects a network_restrictions_id, it should use:
    • The context's ID: If the request/connection is associated with a specific context (document, dedicated worker, shared worker, or service worker), use that context's network_restrictions_id.
    • network::GetNoOpNetworkRestrictionsId(): When no network restrictions should be applied, bypassing restrictions entirely. This should be used carefully as it bypasses the Connection Allowlist (e.g., for browser-initiated requests that do not have an associated frame/context).
    • network::GetTestNetworkRestrictionsId(): In tests that require a valid network restrictions ID but do not test Connection Allowlist behavior.

Browser process checks (content/browser)

The browser process coordinates navigation checks and handles security policies.

• Responsibilities:
  • Store and manage Connection Allowlists as part of the PolicyContainerHost associated with each document.
  • Intercept and validate navigations in the browser process before they are sent to the network service using the NavigationRequest::IsAllowedByConnectionAllowlist function. This function enforces allowlist policies during key phases of navigation (such as initial request start and handling redirects).

Blink checks

Blink is the rendering engine running in the renderer process.

• Responsibilities:
  • Enforce Connection Allowlists in the renderer process for:
    1. WebRTC connections. These checks are also validated in the network service to handle compromised renderers.
    2. Requests initiated via fetch() when they will be intercepted by a Service Worker. This is done in blink because the renderer directly talks to the Service Worker URLLoaderFactory in these cases, not giving the document's URLLoaderFactory checks a chance to run, unless the SW decides to fallback on the original fetch. This applies when the initiating context is either a document, dedicated worker or shared worker.

Integration with service workers

Service Workers act as network proxies in the renderer process, intercepting requests before they reach the network.

• Responsibilities:
  • Main Script Fetches & Update Checks: Subject Service Worker main script fetches and update checks to the Connection Allowlists of the creator/initiator context(the registering document).
    • Initial Install: The browser process creates the loader factory via GetLoaderFactoryForMainScriptFetch passing the creator_network_restrictions_id_.
    • Update Checks: During soft update checks (in ServiceWorkerRegisterJob::UpdateAndContinue), the loader factory is created via GetLoaderFactoryForUpdateCheck passing the creator_network_restrictions_id_.
  • Intercepted Document Fetches: Ensure requests initiated by a document that are intercepted by a Service Worker are validated in Blink against the document's Connection Allowlists before they are forwarded to the Service Worker. This prevents documents from bypassing their own restrictions, including when the Service Worker attempts to serve responses from Cache Storage.
  • Service Worker Outgoing Fetches: Apply the Service Worker's own Connection Allowlists (persisted and restored via the database) to its own fetches.
    • Requests initiated directly by the Service Worker context (ServiceWorkerGlobalScope) itself (via fetch()) are governed by the policies stored in its own PolicyContainerHost. Those are mapped to the Service Worker's own network_restrictions_id in the Network Service via the NetworkRestrictionsWorkerThrottle. This throttle also does the same for dedicated and shared worker contexts.
    • Once a request is inside the Service Worker, any outgoing network fetches (e.g., via event.respondWith(fetch(request))) are initiated using the Service Worker's URLLoaderFactory and subjected to the Service Worker's Connection Allowlists (associated with the Service Worker's own network_restrictions_id), regardless of the client document's policies. Consequently, redirects of these fetches are checked against the Service Worker's connection allowlist's redirect flag, not the document's.
  • Navigation Preload: Navigation preload requests are subject to the Service Worker's Connection-Allowlist. If the navigation itself is allowed by the document's Connection-Allowlist, the associated navigation preload request will be executed using the Service Worker's URLLoaderFactory (which is associated with the Service Worker's network_restrictions_id), thereby enforcing the Service Worker's policies.
  • clients.navigate() in Service Workers: Navigation initiated via clients.navigate() is subject to both the Service Worker's and the document's Connection Allowlists. Since the navigation is initiated from the Service Worker context, the Service Worker's Connection Allowlists apply to the navigation before it is initiated from the Service Worker. In addition, since the navigation is on a window client (which has an associated Document), the Document's Connection Allowlists also apply, and if there is a server redirect, the document's Connection Allowlists' redirect bit will be checked.
  • clients.openWindow() in Service Workers: Navigation initiated via clients.openWindow() is subject to the Service Worker's Connection Allowlists before it is initiated. There is no check on redirect since there is no CA to be checked once the navigation has started.