3. Principles of the Same-Origin Policy

Many user agents undertake actions on behalf of remote parties. For example, HTTP user agents follow redirects, which are instructions from remote servers, and HTML user agents expose rich Document Object Model (DOM) interfaces to scripts retrieved from remote servers.

Without any security model, user agents might undertake actions detrimental to the user or to other parties. Over time, many web-related technologies have converged towards a common security model, known colloquially as the "same-origin policy". Although this security model evolved largely organically, the same-origin policy can be understood in terms of a handful of key concepts. This section presents those concepts and provides advice about how to use these concepts securely.

3.1 Trust

The same-origin policy specifies trust by URI. For example, HTML documents designate which script to run with a URI:

<script src="https://example.com/library.js"></script>

When a user agent processes this element, the user agent will fetch the script at the designated URI and execute the script with the privileges of the document. In this way, the document grants all the privileges it has to the resource designated by the URI. In essence, the document declares that it trusts the integrity of information retrieved from that URI.

In addition to importing libraries from URIs, user agents also send information to remote parties designated by URI. For example, consider the HTML form element:

<form method="POST" action="https://example.com/login">
 ... <input type="password"> ...
</form>

When the user enters his or her password and submits the form, the user agent sends the password to the network endpoint designated by the URI. In this way, the document exports its secret data to that URI, in essence declaring that it trusts the confidentiality of information sent to that URI.

3.1.1 Pitfalls

When designing new protocols that use the same-origin policy, make sure that important trust distinctions are visible in URIs. For example, if both Transport Layer Security (TLS) and non-TLS protected resources use the "http" URI scheme (as in [RFC2817]), a document would be unable to specify that it wishes to retrieve a script only over TLS. By using the "https" URI scheme, documents are able to indicate that they wish to interact with resources that are protected from active network attackers.

3.2 Origin

In principle, user agents could treat every URI as a separate protection domain and require explicit consent for content retrieved from one URI to interact with another URI. Unfortunately, this design is cumbersome for developers because web applications often consist of a number of resources acting in concert.

Instead, user agents group URIs together into protection domains called "origins". Roughly speaking, two URIs are part of the same origin (i.e., represent the same principal) if they have the same scheme, host, and port. (See Section 4 for full details.)

Q: Why not just use the host?

A: Including the scheme in the origin tuple is essential for security. If user agents did not include the scheme, there would be no isolation between http://example.com and https://example.com because the two have the same host. However, without this isolation, an active network attacker could corrupt content retrieved from http://example.com and have that content instruct the user agent to compromise the confidentiality and integrity of content retrieved from https://example.com, bypassing the protections afforded by TLS [RFC5246].

Q: Why use the fully qualified host name instead of just the "top-level" domain?

A: Although the DNS has hierarchical delegation, the trust relationships between host names vary by deployment. For example, at many educational institutions, students can host content at https://example.edu/~student/, but that does not mean a document authored by a student should be part of the same origin (i.e., inhabit the same protection domain) as a web application for managing grades hosted at https://grades.example.edu/.

The example.edu deployment illustrates that grouping resources by origin does not always align perfectly with every deployment scenario. In this deployment, every student's web site inhabits the same origin, which might not be desirable. In some sense, the origin granularity is a historical artifact of how the security model evolved.

3.2.1 Examples

All of the following resources have the same origin:

http://example.com/
http://example.com:80/
http://example.com/path/file

Each of the URIs has the same scheme, host, and port components.

Each of the following resources has a different origin from the others:

http://example.com/
http://example.com:8080/
http://www.example.com/
https://example.com:80/
https://example.com/
http://example.org/
http://ietf.org/

In each case, at least one of the scheme, host, and port component will differ from the others in the list.

3.3 Authority

Although user agents group URIs into origins, not every resource in an origin carries the same authority (in the security sense of the word "authority", not in the [RFC3986] sense). For example, an image is passive content and, therefore, carries no authority, meaning the image has no access to the objects and resources available to its origin. By contrast, an HTML document carries the full authority of its origin, and scripts within (or imported into) the document can access every resource in its origin.

User agents determine how much authority to grant a resource by examining its media type. For example, resources with a media type of image/png are treated as images, and resources with a media type of text/html are treated as HTML documents.

When hosting untrusted content (such as user-generated content), web applications can limit that content's authority by restricting its media type. For example, serving user-generated content as image/png is less risky than serving user-generated content as text/html. Of course, many web applications incorporate untrusted content in their HTML documents. If not done carefully, these applications risk leaking their origin's authority to the untrusted content, a vulnerability commonly known as cross-site scripting.

3.3.1 Pitfalls

When designing new pieces of the web platform, be careful not to grant authority to resources irrespective of media type. Many web applications serve untrusted content with restricted media types. A new web platform feature that grants authority to these pieces of content risks introducing vulnerabilities into existing applications. Instead, prefer to grant authority to media types that already possess the origin's full authority or to new media types designed specifically to carry the new authority.

In order to remain compatible with servers that supply incorrect media types, some user agents employ "content sniffing" and treat content as if it had a different media type than the media type supplied by the server. If not done carefully, content sniffing can lead to security vulnerabilities because user agents might grant low-authority media types, such as images, the privileges of high-authority media types, such as HTML documents [SNIFF].

3.4 Policy

Generally speaking, user agents isolate different origins and permit controlled communication between origins. The details of how user agents provide isolation and communication vary depending on several factors.

3.4.1 Object Access

Most objects (also known as application programming interfaces or APIs) exposed by the user agent are available only to the same origin. Specifically, content retrieved from one URI can access objects associated with content retrieved from another URI if, and only if, the two URIs belong to the same origin, e.g., have the same scheme, host, and port.

There are some exceptions to this general rule. For example, some parts of HTML's Location interface are available across origins (e.g., to allow for navigating other browsing contexts). As another example, HTML's postMessage interface is visible across origins explicitly to facilitate cross-origin communication. Exposing objects to foreign origins is dangerous and should be done only with great care because doing so exposes these objects to potential attackers.

3.4.2 Network Access

Access to network resources varies depending on whether the resources are in the same origin as the content attempting to access them.

Generally, reading information from another origin is forbidden. However, an origin is permitted to use some kinds of resources retrieved from other origins. For example, an origin is permitted to execute script, render images, and apply style sheets from any origin. Likewise, an origin can display content from another origin, such as an HTML document in an HTML frame. Network resources can also opt into letting other origins read their information, for example, using Cross-Origin Resource Sharing [CORS]. In these cases, access is typically granted on a per-origin basis.

Sending information to another origin is permitted. However, sending information over the network in arbitrary formats is dangerous. For this reason, user agents restrict documents to sending information using particular protocols, such as in an HTTP request without custom headers. Expanding the set of allowed protocols, for example, by adding support for WebSockets, must be done carefully to avoid introducing vulnerabilities [RFC6455].

3.4.3 Pitfalls

Whenever user agents allow one origin to interact with resources from another origin, they invite security issues. For example, the ability to display images from another origin leaks their height and width. Similarly, the ability to send network requests to another origin gives rise to cross-site request forgery vulnerabilities [CSRF]. However, user agent implementors often balance these risks against the benefits of allowing the cross-origin interaction. For example, an HTML user agent that blocked cross-origin network requests would prevent its users from following hyperlinks, a core feature of the web.

When adding new functionality to the web platform, it can be tempting to grant a privilege to one resource but to withhold that privilege from another resource in the same origin. However, withholding privileges in this way is ineffective because the resource without the privilege can usually obtain the privilege anyway because user agents do not isolate resources within an origin. Instead, privileges should be granted or withheld from origins as a whole (rather than discriminating between individual resources within an origin) [BOFGO].

3.5 Conclusion

The same-origin policy uses URIs to designate trust relationships. URIs are grouped together into origins, which represent protection domains. Some resources in an origin (e.g., active content) are granted the origin's full authority, whereas other resources in the origin (e.g., passive content) are not granted the origin's authority. Content that carries its origin's authority is granted access to objects and network resources within its own origin. This content is also granted limited access to objects and network resources of other origins, but these cross-origin privileges must be designed carefully to avoid security vulnerabilities.