This site in other countries/regions:1. Introduction
Web application technologies commonly apply same origin restrictions to
network requests. These restrictions prevent a Web application running
from one origin from obtaining data retrieved from another origin, and
also limit the amount of unsafe HTTP requests that can be automatically
launched toward destinations that differ from the running application's
In Web application technologies that follow this pattern, network
requests typically use ambient authentication and session management
information, including HTTP authentication and cookie information.
This specification extends this model in several ways:
Web applications are enabled to annotate the data that is returned in
response to an HTTP request with a set of origins that should be
permitted to read that information by way of the user's Web browser.
The policy expressed through this set of origins is enforced on the
Web browsers are enabled to discover whether a target resource is
prepared to accept cross-site HTTP requests using non-GET
methods from a set of origins.
The policy expressed through this set of origins is enforced on the
Server side applications are enabled to discover that an HTTP request
was deemed a cross-site request by the client Web browser, through the
HTTP header.
This extension enables server side applications to enforce limitations
on the cross-site requests that they are willing to service.
This specification is a building block for other specifications,
so-called hosting specifications, which will define the precise model by
which this specification is used. Among others, such specifications are
likely to include XMLHttpRequest Level 2, XBL 2.0, and HTML&5 (for
its server-sent events feature).
The design of this specification introduces is based on requirements and , both included as appendix. A FAQ describing the design decisions is also available.
If a server author has a simple text resource residing at
/hello which contains the string "Hello
World!" and would like http://hello-world.example to be able
to access it, the resource combined with an HTTP header introduced by
this specification could look as follows:
Access-Control-Allow-Origin: http://hello-world.example
Hello World!
Using XMLHttpRequest
http://hello-world.example resources can access this
document as follows:
new client = new XMLHttpRequest();
client.open("GET", "/hello")
client.onreadystatechange = function() { /* do something */ }
client.send()
It gets slightly more complicated if the server author wants to be able
to handle cross-site requests using HTTP methods other than
GET and POST. In that case the author needs to
reply to a preflight request that uses the OPTIONS method
and then needs to handle the actual request that uses the desired HTTP
method (e.g., DELETE) and give an appropriate response. The
response to the preflight request could have the following HTTP headers
specified:
Access-Control-Allow-Origin: http://hello-world.example
Access-Control-Max-Age: 3628800
The Access-Control-Max-Age
header indicates how long the response can be cached, so that for
subsequent requests, within the specified time, no preflight request has
to be made. The response to the actual request can simply contain this
Access-Control-Allow-Origin: http://hello-world.example
The complexity of invoking the additional preflight request is the task
of the user agent. Using XMLHttpRequest again and assuming
the application were hosted at http://calendar.example/app
the author could use the following ECMAScript snippet:
function deleteItem(itemId, updateUI) {
var client = new XMLHttpRequest()
client.open("DELETE", "http://calendar.example/app")
client.onload = updateUI
client.onerror = updateUI
client.onabort = updateUI
client.send("id=" + itemId)
XMLHttpRequest Level 2 includes support for cross-site access requests.
2. Conformance Criteria
This specification is applicable to both user agents and
hosting specifications. Hosting specifications are expected to indicate
when the rules set forth by this specification are to be followed.
(Typically this would involve using the cross-site access request algorithm
for non same origin requests.
As well as sections marked as non-normative, all diagrams, examples, and
notes in this specification are non-normative. Everything else in this
specification is normative.
In this specification, The words must, must not, should, should
not and may are to be interpreted as described in
RFC 2119. []
A conformant hosting specification is one that implements all the
requirements listed in this specification that are applicable to hosting
specifications. For instance, such a specification needs to define what
the source for the
A conformant user agent is one that implements all the requirements
listed in this specification that are applicable to user agents, while
also being consistent with the requirements listed in the hosting
specification.
User agents may employ any algorithm to implement this
specification, so long as the end result is indistinguishable from the
result that would be obtained by the specification's algorithms.
2.1 Terminology
Terminology is generally defined throughout the specification. However,
the few definitions that did not really fit anywhere else are defined here
There is a case-insensitive match
of strings s1 and s2 if after mapping the ASCII
character range A-Z to the range a-z both strings are identical.
The terms URL, origin, ASCII serialization of an origin, and same origin are defined by HTML&5. [HTML5]
3. Security Considerations
algorithm defined in this specification is an extension of the same origin
policy in contexts where the same origin policy currently applies. This
impacts hosting specifications referencing the algorithm, user agents
implementing it, and authors using it. Below we discuss the security
considerations for these groups.
Hosting specifications
Hosting specifications should limit the request
headers an author can set and get, and forbidding setting and getting
user credentials through any API defined in the hosting specification.
For instance, access to document.cookie of the
requested resource is to be prohibited.
Hosting specifications using the cross-site access request should properly deal with redirects. In particular, if a
same origin request is redirected to a non same origin URL the
specification should abort the request and either
terminate completely (as it did until now) or use the cross-site access request
algorithm on the non same origin URL.
These requirements are further detailed in the processing model section.
User agents
When making a , user agents should ensure to:
Not reveal whether the requested resource exists, until access has
been granted. This prevents port scanning and finding out about
intranet servers the user might be connected with.
Not inappropriately expose any trusted data of the response, such as
cookies and HTTP header data.
Not allow the author to set cookies or authentication credentials
for the request, as this would allow for a distributed cookie or
credentials search. Either through letting them set HTTP headers or
providing the userinfo production in redirects. (This
last concern is mitigated by the algorithms in present in this
specification.)
Application authors should be aware that content
retrieved from another site is not itself trustable. Authors should protect themselves against cross-site scripting
attacks by not rendering or executing the retrieved content directly
without validating that content.
Authors are to ensure that GET requests on their
applications have no side effects. If by some means an attacker finds
out what applications a user is associated with, it might "attack" these
applications with GET requests that can effect the user's
data (if the user is already authenticated with any of these
applications by means of cookies or HTTP authentication).
Authors are strongly encouraged to check the
HTTP header,
especially for non-GET requests, to ensure that in case of
policy change they do not inadvertently allow access due to race
conditions (when such access is to be denied).
Authors should also check the Host HTTP
header and make sure the host name provided by that header matches the
host name of their server. This will provide protection against DNS
rebinding attacks.
For different authors sharing one host name
(people.example.org/~author-name/) it is not
possible to allow access only from a certain author as the other authors
could trivially work around this through DOM scripting. Sharing access
with an author who shares the host name with someone else is therefore
discouraged.
Integrity protection of the access control policy statements may be
required. This could be achieved by use of SSL/TLS, for example.
This section defines the various syntactic constructs this specification
introduces. A number of these constructs are defined using ABNF as defined
in RFC 2616. [].
RFC 2616 is used as ABNF basis to ensure that the new headers have
equivalent constructs to those introduced in that specification.
4.1 Access-Control-Allow-Origin HTTP Response Header
A resource can have one
header defined. The header must match the following
Access-Control-Allow-Origin = "Access-Control-Allow-Origin" ":" ascii-origin | "*"
ascii-origin
Access-Control-Allow-Origin: http://example.org
The above example indicates that http://example.org can
access the resource.
For requests without credentials, a server can specify that a resource
can be accessed by any origin using a wildcard:
Access-Control-Allow-Origin: *
4.2 Access-Control-Max-Age HTTP Response Header
HTTP response header indicates how long the results of a preflight request can be cached in a preflight result cache. The Access-Control-Max-Age
HTTP header must match the following ABNF:
Access-Control-Max-Age = "Access-Control-Max-Age" ":" delta-seconds
The delta-seconds production is defined in RFC 2616.
4.3 Access-Control-Allow-Credentials HTTP Response Header
HTTP response header indicates whether the response to request can be
exposed when the credentials flag is true. When part
of the response to an
it indicates that the
can be made
with credentials. The Access-Control-Allow-Credentials
HTTP header must match the following ABNF:
Access-Control-Allow-Credentials: "Access-Control-Allow-Credentials" ":" "true"
4.4 Access-Control-Allow-Methods HTTP Response Header
HTTP response header indicates, as part of the response to a preflight request, which HTTP methods can be
used during the . The Access-Control-Allow-Methods
HTTP header must match the following ANBF:
Access-Control-Allow-Methods: "Access-Control-Allow-Methods" ":" #Method
The Method production is defined in RFC 2616.
HTTP response header indicates, as part of the response to a preflight request, which HTTP headers can be
used during the . The Access-Control-Allow-Methods
HTTP header must match the following ANBF:
Access-Control-Allow-Headers: "Access-Control-Allow-Headers" ":" #field-name
The field-name production is defined in RFC
4.6 Origin
HTTP Request Header
HTTP request header indicates where the cross-site access request or preflight request originates from. The
HTTP header must match the following ABNF:
Origin = "Origin" ":"
can be the
empty string. When the source originates from a data: URL for
In contrast with the Referer header,
reveal confidential path information and does therefore not need to be
This header has a generic name as it is likely that other
APIs will start using it too.
4.7 Access-Control-Request-Method HTTP Request Header
HTTP request header indicates what HTTP method will be used in the actual request as part of the preflight request. The Access-Control-Request-Method
HTTP header must match the following ABNF:
Access-Control-Request-Method: "Access-Control-Request-Method" ":" Method
HTTP request header indicates what HTTP headers will be used in the actual request as part of the preflight request. The Access-Control-Request-Method
HTTP header must match the following ABNF:
Access-Control-Request-Headers: "Access-Control-Request-Headers" ":" #field-name
5. Processing Model
This section (including subsections) describes the processing models
that user agents and hosting specifications have to implement. A hosting
specification "implements" an algorithm by referencing it and carefully
defining how the return values are handled.
5.1 Cross-Site Access Request
The cross-site access request
algorithm takes the following parameters:
A request URL.
is modified in face
of redirects.
A request method.
A collection of additional request headers.
A request entity body.
A source for the .
A credentials flag.
The return values are described further down. The cross-site access
request algorithm can be used by hosting specifications who wish to
provide cross-site requests for the APIs they define.
Hosting specifications are free to limit the abilities of a
the credentials flag could always be false.
When the cross-site access request algorithm is used, these steps must be followed:
is equal to GET
or POST, the collection of
contains no other headers than those of the simple request header
whitelist, and if the Content-Type header, when part of
while the request method is POST, contains no
values other than
application/x-www-form-urlencoded,
multipart/form-data, or text/plain, then
follow the
algorithm.
Otherwise, follow the cross-site access
request with preflight algorithm.
Cross-Site requests using the GET or
POST method with
other than those in the
will have a preflight request to ensure that the server
is can handle those headers. (Similarly to requests using methods other
than GET or POST.)
User agents must filter out all response headers other
than those listed in the
before exposing response headers to the APIs defined
in the hosting specification.
The getResponseHeader() method defined by
XMLHttpRequest for instance will therefore not get access to
the Cookie2 header and other headers not part of the
whitelist.
The aforementioned algorithms have shared return values that hosting
specifications can use to instruct user agents what to do. The status return flag
indicates the status of the cross-site access request. It takes the value
"success" when cross-site access to the resource is allowed, "same-origin"
if the cross-site request turned into a same origin request due to
redirects, "network" if a network error of some sort occurred, and "abort"
if the user aborted the request. The url return flag is used when the status return flag is
"same-origin", to indicate the URL which the specification can use for a
subsequent same origin request.
When used by hosting specifications, those specifications must handle all values of the
and handle the url return flag.
5.1.1 Cross-Site Access source
The source origin is the ASCII
serialization of the
of the source of the
Hosting specifications using
must define the source of the request for the source origin. Due to the way
the origin for APIs is retrieved in different ways, it is not possible to
define this in a generic way.
While following the requirements for cross-site access requests, user
agents must ensure that for each request (including
redirects, et cetera) the Origin HTTP request header is set, with
the value set to access control origin.
5.1.2 Cross-Site Access Request
Header Lists
consists of all headers of which the header name case-insensitively matches one of the following:
Accept-Language
Content-Type
consists of all headers of which the header name case-insensitively matches one of the following:
Cache-Control
Content-Language
Content-Type
Last-Modified
5.1.3 Simple Cross-Site Access
The steps below describe what user agents must do for
a simple cross-site access
and observe the
request rules below while making the request.
If the response is an HTTP redirect
Apply the .
If the user cancels the request
Apply the .
If there is a network error
Apply the .
Perform an .
If it returns "fail", apply the . Otherwise, if it returns "pass", terminate this
algorithm and return with the
set to "success". Do not actually terminate the request.
5.1.4 Cross-Site Access Request
with Preflight
To protect servers against cross-site access with methods that have side
effects an
is made to
ensure that the server is ok with the request. The result of this request
is stored in an .
Consider the following scenario:
The user agent gets the request from an API, such as
XMLHttpRequest to perform a cross-site request using the
custom XMODIFY method from
http://example.org to
http://blog.example/entries/hello-world.
The user agent performs an OPTIONS request to
http://blog.example/entries/hello-world to which the
response includes the following HTTP metadata:
Access-Control: allow &example.org>
Access-Control-Max-Age: 151200
The user agent then performs the desired XMODIFY request
to http://blog.example/entries/hello-world as this was
allowed by the resource. In addition, for the coming 151200 seconds, or
forty-two hours, no OPTIONS request will be needed.
As mentioned, cross-site access request with preflights use an preflight result cache. This cache
consists of a set of entries. Each entry consists of the following fields:
Holds the .
Holds the .
expiry time
Holds the Access-Control-Max-Age
header value.
credentials
Holds the value of the .
Holds the list of values from the Access-Control-Allow-Methods
Holds the list of values from the Access-Control-Allow-Headers
Entries must be removed when the time specified in the
expiry time field has passed since storing the entry. Entries can
also be added and removed per the algorithms below. They are added and
removed in such a way that there can never be duplicate items in the
The steps below describe what user agents must do for
cross-site access request with preflights.
These are requests to a non same origin URL with an HTTP request method
other than GET that first need to be authorized using either
a preflight result cache entry or a preflight request.
If there is an entry in the preflight result cache that matches
the conditions described in the list below proceed to the next step:
The origin field value is identical to the source origin.
The url field value is identical to the request URL.
is true, the credentials field value is identical to the credentials flag.
One of the values of the method field is identical
to the , or the request method is GET or
HTTP methods are case-sensitive.
Every header name of
case-insensitively matches a header of the headers field or is in the simple request header
whitelist.
Otherwise, , if any, and then make a preflight
request. This is a request using the HTTP OPTIONS
method to the . In addition to normal
request headers and the Origin header, user agents are also to
include an Access-Control-Request-Method
header with as value the , and an
Access-Control-Request-Headers
header with as value a comma-separated list of header names from request headers. (No credentials, entity body, et
cetera, are to be included.) Observe the following request rules
while making this request:
If the response is an HTTP redirect
Apply the .
If the user cancels the download
Apply the .
If there is a network error
Apply the .
returns "fail", apply the .
Let methods be the result of parsing the
Access-Control-Allow-Methods
header values. If parsing fails (e.g., value with a space), apply
Let headers be the result of parsing the
Access-Control-Allow-Headers
header values. If parsing fails, apply the network error steps.
is not identical to any
method in methods, or is not identical to
GET or POST, apply the network error steps.
If every single header name of
header name in headers or is not in the simple request header
whitelist, apply the .
false, the cache entry will not have the credentials
field value set to true, regardless of whether a Access-Control-Allow-Credentials
header was present in the response.
This is the actual request. Apply the make a request steps and observe the request
rules below while making the request.
If the response is an HTTP redirect
and then apply the .
If the user cancels the download
Apply the .
If there is a network error
Apply the .
Perform an .
If it returns "fail", , then apply the network error steps. Otherwise, if it
returns "pass", terminate this algorithm and return with the status flag set to "success". Do not
actually terminate the request.
5.1.5 Generic Cross-Site Access
Request Algorithms
The variables used in the generic set of steps are part of the
algorithms that invoke these set of steps.
Whenever the make a request steps are applied, make
a request to , using HTTP method request method, entity body request entity body, including the additional request headers, and include credentials if the credentials flag is true (e.g. HTTP authentication
data and cookies).
The redirect steps are as follows:
If the new URL scheme is not supported, infinite loop precautions are
violated, or something else went wrong, apply the network error steps. Otherwise, let request URL be the new URL and then follow this set of
contains the
userinfo production, as defined in section 3.2.1 of RFC
3986, apply the .
and source origin are , terminate the algorithm that invoked this set of steps and
return with the
set to the request URL and the status flag set to "same-origin".
the current resource returns "fail", apply the generic network
Otherwise, transparently follow the redirect while observing the set
of request rules.
Whenever the abort steps are applied,
terminate the algorithm that invoked this set of steps and return with the
set to "abort".
Whenever the network error steps are
applied, terminate the algorithm that invoked this set of steps and return
set to "network".
Remove the cache entry means
removing the entry in the
identical to the origin field value and request URL is identical to the url
field value.
To append a cache entry
means to follow this set of steps:
If for some reason the user agent is unable to provide a cache
terminate this set of steps.
Create a new entry in the
with the various fields set as follows:
expiry time
If there is a single Access-Control-Max-Age
response header with a correct value, the value of the Access-Control-Max-Age
response header. Otherwise, a value at the discretion of the user agent
(which can be zero).
credentials
methods (see preflight request).
headers (see preflight request).
5.2 Access Control Check
The access control check algorithm
for a given resource is as follows:
If the resource includes zero or more than one Access-Control-Allow-Origin
headers return "fail" and terminate this algorithm.
If the Access-Control-Allow-Origin
header value is the literal "*" character and the credentials flag is false return "pass" and
terminate this algorithm.
If the value of Access-Control-Allow-Origin
is not identical to the
return "fail" and terminate this algorithm.
is true and the
resource includes zero or more than one Access-Control-Allow-Credentials
headers return "fail" and terminate this algorithm.
is true and the
Access-Control-Allow-Credentials
header value is not the literal string "true" return "fail"
and terminate this algorithm.
Return "pass".
Requirements
While the requirements use "normative" terminology this appendix does
not affect conformance and is therefore non-normative.
The requirements that influenced the design of the Access Control for
Cross-Site Requests specification are as follows:
Must not introduce new attack vectors, such as:
Must not introduce attack vectors to servers that are only protected
only by a firewall.
The solution should not introduce additional attack vectors against
services that are protected only by way of firewalls. This requirement
addresses "intranet" style services authorize any requests that can be
sent to the service.
Note that this requirement does not preclude HEAD,
OPTIONS, or GET requests (even with ambient
authentication and session information).
It should not be possible to perform cross-site non-safe operations,
i.e., HTTP operations except for GET, HEAD,
and OPTIONS, without an authorization check being
performed.
Should try to prevent dictionary-based, distributed, brute-force
attacks that try to get login accounts to 3rd party
servers, to the extent possible.
Should properly enforce security policy in the face of commonly
deployed proxy servers sitting between the user agent and any of
servers with whom the user agent is communicating.
Should not allow loading and exposing of resources from
3rd party servers without explicit consent of these servers
as such resources can contain sensitive information.
Must not require content authors or site maintainers to implement new
or additional security protections to preserve their existing level of
security protection.
Must be deployable to IIS and Apache without requiring actions by the
server administrator in a configuration where the user can upload static
files, run serverside scripts (such as PHP, ASP, and CGI), control HTTP
headers, and control authorization, but only do this for URLs under a
given set of subdirectories on the server.
Must able to deploy support for cross-site GET requests
without having to use server-side scripting (such as PHP, ASP, or CGI)
on IIS and Apache.
The solution must be applicable to arbitrary media types. It must be
deployable without requiring special packaging of resources, or changes
to resources' content.
It should be possible to configure distinct cross-site authorization
policies for different target resources that reside within the same
It should be possible to distribute content of any type. Likewise, it
should be possible to transmit content of any type to the server if the
API in use allows such functionality.
It should be possible to allow only specific servers, or sets of
servers to fetch the resource.
Must not require that the server filters the entity body of the
resource in order to deny cross-site access to all resources on the
Cross-site requests should not require API changes other than allowing
cross-site requests. This means that the following examples should work
for resources residing on http://test.example (modulo
changes to the respective specifications to allow cross-site requests):
&?xml-stylesheet type="application/xslt+xml" href="http://example.org/annotate.xslt"?>
&?xbl href="http://example.org/globe.xml"?>
xhr = new XMLHttpRequest();
xhr.open("GET", "http://example.org/data.text");
xhr.send();
It should be possible to issue methods other than GET to
the server, such as POST and DELETE.
Should be compatible with commonly used HTTP authentication and
session management mechanisms. I.e. on an IIS server where
authentication and session management is generally done by the server
before ASP pages execute this should be doable also for requests coming
from cross-site requests. Same thing applies to PHP on Apache.
Should reduce the risk of inadvertently allowing access when it is not
intended. This is, it should be clear to the content provider when
access is granted and when it is not.
The use cases appendix documents several potential use cases that guided
development of the Access Control work. This appendix does not affect
conformance and is therefore non-normative.
If the contacts part of an e-mail application allows a social
networking site to add contacts this could be done through a cross-site
PUT requests.
If a server foo.example.org implements a simple REST API
to create, delete and modify resources Access Control could be used to
let a nice editing application on server editing.example
store the results of the editing actions on
foo.example.org.
An XBL binding allows full access to the document it is bound to and
therefore cross-site XBL usage is prevented. Access Control enables
cross-site XBL bindings. If the user is authenticated with the server
that hosts the XBL widget it is possible to have a user-specific
cross-site bindings.
To prevent data theft, from e.g. intranets, cross-site XSLT usage is
not possible. With Access Control several domains are able to share XSLT
resources in a cross-site fashion.
If you have a Web application that fetches resources (e.g. RDF) from
around the Web to extract data out of them Access Control could be used
to fetch them using a single request if the resource enables cross-site
Design Decision FAQ
This appendix documents several frequently asked questions and their
corresponding response. As it does not affect conformance it is
non-normative.
Why is there a ?
For most type of requests two
are performed.
Initially a "permission to make the request" check is done on the
response to the . And
then a "permission to read" check is done on the response to the actual request. Both of these checks need to succeed
in order for success to be relayed to the API (e.g.
XMLHttpRequest).
The "permission to make the request" check is performed because
deployed servers do not expect such cross-site requests. E.g., a request
using the HTTP DELETE method. If they reply positively to
the client knows
it can go ahead and perform the actual desired request.
Why is POST treated identically to GET?
Cross-site POST requests have long been possible using
the HTML form element. Cross-site POST
requests with arbitrary an Content-Type header set have
been possible for a long time in Flash.
Why are cookies and authentication information sent in the request?
Sending cookies and authentication information enables user-specific
cross-site widgets (external XBL file). It also allows for a user
authenticated data storage API that services can use to store data in.
Cookies and authentication information is already sent cross-site for
various HTML elements, such as img, script,
Why can cookies and authentication information not be
provided by the script author for the request?
This would allow dictionary based, distributed, cookies / user
credentials search.
Why is the client the policy enforcement point?
The client already is the policy enforcement point for these requests.
The mechanism allows the server to opt-in to let the client expose the
data. Something clients currently not do and which servers rely upon.
Note however that the server is in full control. Based on the value of
header in cross-site requests it can decide to return no data at all or
not provide the necessary handshake (the Access-Control-Allow-Origin
What about the JSONRequest proposal?
JSONRequest has been considered by the Web Applications
Working Group and the group has concluded that it does not meet the
documented . E.g., requests
originating from the JSRONRequest API cannot include
credentials and JSONRequest is format specific.
References
HTML&5 (work in
progress), I. Hickson, D. Hyatt, editors. W3C, 2008.
(work in progress), I. Hickson, editor. WHATWG, 2008.
, S. Bradner. IETF, March 1997.
, R. Fielding, J. Gettys, J. Mogul, H.
Frystyk, L. Masinter, P. Leach, T. Berners-Lee, editors. IETF, June 1999
, T. Berners-Lee, R. Fielding,
L. Masinter, editors. IETF, January 2005.
Acknowledgments
The editor would like to thank Adam Barth, Arthur Barstow, Benjamin
Hawkes-Lewis, Bj&rn H&hrmann, Cameron McCormack, Collin Jackson,
David H&s&ther, David Orchard, Dean Jackson, Eric Lawrence,
Frank Ellerman, Frederick Hirsch, Graham Klyne, Hal Lockhart, Henri
Sivonen, Ian Hickson, Jonas Sicking, Lachlan Hunt, Maciej Stachowiak, Marc
Silbey, Marcos Caceres, Mark Nottingham, Martin D&rst, Matt Womer,
Michael Smith, Mohamed Zergaoui, Sharath Udupa, Sunava Dutta, Surya
Ismail, Thomas Roessler, Tyler Close, and Zhenbin Xu for their
contributions to this specification.
Special thanks to Brad Porter, Matt Oshry and R. Auburn, who all helped
editing earlier versions of this document.