Browsers send specific HTTP headers for cross-site requests initiated from within XMLHttpRequest or the Fetch API. It also expects to see specific HTTP headers sent back with cross-site responses. An overview of these headers, including sample JavaScript code that initiates requests and processes responses from the server, as well as a discussion of each header, can be found in the HTTP Access Control (CORS) article and should be read as a companion article to this one. This article covers processing Access Control Requests and formulating Access Control Responses in PHP. The target audience for this article are server programmers or administrators. Although the code samples shown here are in PHP, similar concepts apply for ASP.net, Perl, Python, Java, etc.; in general, these concepts can be applied to any server-side programming environment that processes HTTP requests and dynamically formulates HTTP responses.

Discussion of HTTP headers

The article covering the HTTP headers used by both clients and servers is here, and should be considered prerequisite reading.

Working code samples

The PHP snippets (and the JavaScript invocations to the server) in subsequent sections are taken from the working code samples posted here. These will work in browsers that implement cross-site XMLHttpRequest.

Simple cross-site requests

Simple Access Control Requests are initiated when:

  • An HTTP/1.1 GET or a POST is used as request method. In the case of a POST, the Content-Type of the request body is one of application/x-www-form-urlencoded, multipart/form-data, or text/plain.
  • No custom headers are sent with the HTTP request (such as X-Modified, etc.)

In this case, responses can be sent back based on some considerations.

  • If the resource in question is meant to be widely accessed (just like any HTTP resource accessed by GET), than sending back the Access-Control-Allow-Origin: * header will be sufficient, unless the resource needs credentials such as Cookies and HTTP Authentication information.
  • If the resource should be kept restricted based on requester domain, OR if the resource needs to be accessed with credentials (or sets credentials), then filtering by the request's Origin header may be necessary, or at least echoing back the requester's Origin (e.g. Access-Control-Allow-Origin: http://arunranga.com).  Additionally, the Access-Control-Allow-Credentials: true header will have to be sent. This is discussed in a subsequent section.

The section on Simple Access Control Requests shows you the header exchanges between client and server. Here is a PHP code segment that handles a Simple Request:

<?php

// We'll be granting access to only the arunranga.com domain 
// which we think is safe to access this resource as application/xml

if($_SERVER['HTTP_ORIGIN'] == "http://arunranga.com") {
    header('Access-Control-Allow-Origin: http://arunranga.com');
    header('Content-type: application/xml');
    readfile('arunerDotNetResource.xml');
} else {    
  header('Content-Type: text/html');
  echo "<html>";
  echo "<head>";
  echo "   <title>Another Resource</title>";
  echo "</head>";
  echo "<body>",
       "<p>This resource behaves two-fold:";
  echo "<ul>",
         "<li>If accessed from <code>http://arunranga.com</code> it returns an XML document</li>";
  echo   "<li>If accessed from any other origin including from simply typing in the URL into the browser's address bar,";
  echo   "you get this HTML document</li>", 
       "</ul>",
     "</body>",
   "</html>";
}
?>

The above checks to see if the Origin header sent by the browser (obtained through $_SERVER['HTTP_ORIGIN']) matches 'http://arunranga.com'. If yes, it returns Access-Control-Allow-Origin: http://arunranga.com. This example can be seen running here.

Preflighted requests

Preflighted Access Control Requests occur when:

  • A method other than GET or POST is used, or if POST is used with a Content-Type other than one of application/x-www-form-urlencoded, multipart/form-data, or text/plain. For instance, if the Content-Type of the POST body is application/xml, a request is preflighted.
  • A custom header (such as X-PINGARUNER) is sent with the request.

The section on Preflighted Access Control Requests shows a header exchange between client and server. A server resource responding to a preflight requests needs to be able to make the following determinations:

Here is an example in PHP of handling a preflighted request:

<?php 

if($_SERVER['REQUEST_METHOD'] == "GET") {

  header('Content-Type: text/plain');
  echo "This HTTP resource is designed to handle POSTed XML input";
  echo "from arunranga.com and not be retrieved with GET"; 

} elseif($_SERVER['REQUEST_METHOD'] == "OPTIONS") {
  // Tell the Client we support invocations from arunranga.com and 
  // that this preflight holds good for only 20 days

  if($_SERVER['HTTP_ORIGIN'] == "http://arunranga.com") {
    header('Access-Control-Allow-Origin: http://arunranga.com');
    header('Access-Control-Allow-Methods: POST, GET, OPTIONS');
    header('Access-Control-Allow-Headers: X-PINGARUNER');
    header('Access-Control-Max-Age: 1728000');
    header("Content-Length: 0");
    header("Content-Type: text/plain");
    //exit(0);
  } else {
    header("HTTP/1.1 403 Access Forbidden");
    header("Content-Type: text/plain");
    echo "You cannot repeat this request";
  }

} elseif($_SERVER['REQUEST_METHOD'] == "POST") {
  // Handle POST by first getting the XML POST blob, 
  // and then doing something to it, and then sending results to the client
 
  if($_SERVER['HTTP_ORIGIN'] == "http://arunranga.com") {
    $postData = file_get_contents('php://input');
    $document = simplexml_load_string($postData);
    
    // do something with POST data

    $ping = $_SERVER['HTTP_X_PINGARUNER'];
         
    header('Access-Control-Allow-Origin: http://arunranga.com');
    header('Content-Type: text/plain');
    echo // some string response after processing
  } else {
    die("POSTing Only Allowed from arunranga.com");
  }
} else {
    die("No Other Methods Allowed");
}
?>

Note the appropriate headers being sent back in response to the OPTIONS preflight as well as to the POST data. One resource thus handles the preflight as well as the actual request. In the response to the OPTIONS request, the server notifies the client that the actual request can indeed be made with the POST method, and header fields such as X-PINGARUNER can be sent with the actual request. This example can be seen running here.

Credentialed requests

Credentialed Access Control Requests – that is, requests that are accompanied by Cookies or HTTP Authentication information (and which expect Cookies to be sent with responses) – can be either Simple or Preflighted, depending on the request methods used.

In a Simple Request scenario, the request will be sent with Cookies (e.g. if the withCredentials flag is set on XMLHttpRequest). If the server responds with Access-Control-Allow-Credentials: true attached to the credentialed response, then the response is accepted by the client and exposed to web content. In a Preflighted Request, the server can respond with Access-Control-Allow-Credentials: true to the OPTIONS request.

Here is some PHP that handles credentialed requests:

<?php

if($_SERVER['REQUEST_METHOD'] == "GET") {
  header('Access-Control-Allow-Origin: http://arunranga.com');
  header('Access-Control-Allow-Credentials: true');
  header('Cache-Control: no-cache');
  header('Pragma: no-cache');
  header('Content-Type: text/plain');

  // First See if There Is a Cookie   
  if (!isset($_COOKIE["pageAccess"])) {
    setcookie("pageAccess", 1, time()+2592000);
    echo 'I do not know you or anyone like you so I am going to';
    echo 'mark you with a Cookie :-)';    
  } else {
    $accesses = $_COOKIE['pageAccess'];
    setcookie('pageAccess', ++$accesses, time()+2592000);
    echo 'Hello -- I know you or something a lot like you!';
    echo 'You have been to ', $_SERVER['SERVER_NAME'], ';
    echo 'at least ', $accesses-1, ' time(s) before!';
  }  
} elseif($_SERVER['REQUEST_METHOD'] == "OPTIONS") {
  // Tell the Client this preflight holds good for only 20 days
  if($_SERVER['HTTP_ORIGIN'] == "http://arunranga.com") {
    header('Access-Control-Allow-Origin: http://arunranga.com');
    header('Access-Control-Allow-Methods: GET, OPTIONS');
    header('Access-Control-Allow-Credentials: true');
    header('Access-Control-Max-Age: 1728000');
    header("Content-Length: 0");
    header("Content-Type: text/plain");
  } else {
    header("HTTP/1.1 403 Access Forbidden");
    header("Content-Type: text/plain");
    echo "You cannot repeat this request";
  }
} else {
  die("This HTTP Resource can ONLY be accessed with GET or OPTIONS");
}
?>

Note that in the case of credentialed requests, the Access-Control-Allow-Origin: header must not have a wildcard value of "*".  It must mention a valid origin domain. The example above can be seen running here.

Apache examples

Restrict access to certain URIs

One helpful trick is to use an Apache rewrite, environment variable, and headers to apply Access-Control-Allow-* to certain URIs. This is useful, for example, to constrain cross-origin requests to GET /api(.*).json requests without credentials:

RewriteRule ^/api(.*)\.json$ /api$1.json [CORS=True]
Header set Access-Control-Allow-Origin "*" env=CORS
Header set Access-Control-Allow-Methods "GET" env=CORS
Header set Access-Control-Allow-Credentials "false" env=CORS

See also

Document Tags and Contributors

Tags: 
 Contributors to this page: fscholz, twoi, jonas.ninja, teoli, Sheppy, groovecoder, Gerv, Brettz9, Jürgen Jeka, aruner
 Last updated by: fscholz,