Skip to content

Latest commit

 

History

History
211 lines (122 loc) · 8.5 KB

README.md

File metadata and controls

211 lines (122 loc) · 8.5 KB
Raw

Corser

Project Status: Active - The project has reached a stable, usable state and is being actively developed. Build Status

A highly configurable, middleware compatible implementation of CORS for Node.js.

Changelog

2.0.1 (August 16, 2016)

2.0.0 (March 22, 2014)

  • Preflight requests are automatically closed. If there is a need for handling OPTIONS requests, check the endPreflightRequests option.
  • The parameters of the callback function in dynamic origin checking are now (err, matches) instead of just (matches).

Examples

How to use Corser as a middleware in Express

See example/express/ for a working example.

var express, corser, app;

express = require("express");
corser = require("corser");

app = express();

app.use(corser.create());

app.get("/", function (req, res) {
    res.writeHead(200);
    res.end("Nice weather today, huh?");
});

app.listen(1337);

How to use Corser as a middleware in Connect

See example/connect/ for a working example.

var connect, corser, app;

connect = require("connect");
corser = require("corser");

app = connect();

app.use(corser.create());

app.use(function (req, res) {
    res.writeHead(200);
    res.end("Nice weather today, huh?");
});

app.listen(1337);

How to use Corser with plain http

var http, corser, corserRequestListener;

http = require("http");
corser = require("corser");

// Create Corser request listener.
corserRequestListener = corser.create();

http.createServer(function (req, res) {
    // Route req and res through the request listener.
    corserRequestListener(req, res, function () {
        res.writeHead(200);
        res.end("Nice weather today, huh?");
    });
}).listen(1337);

API

Creating a Corser request listener

Creating a Corser request listener that generates the appropriate response headers to enable CORS is as simple as:

corser.create()

This is the equivalent of setting a response header of Access-Control-Allow-Origin: *. If you want to restrict the origins, or allow more sophisticated request or response headers, you have to pass a configuration object to corser.create.

Corser will automatically end preflight requests for you. A preflight request is a special OPTIONS request that the browser sends under certain conditions to negotiate with the server what methods, request headers and response headers are allowed for a CORS request. If you need to use the OPTIONS method for other stuff, just set endPreflightRequests to false and terminate those requests yourself:

var corserRequestListener;

corserRequestListener = corser.create({
    endPreflightRequests: false
});

corserRequestListener(req, res, function () {
    if (req.method === "OPTIONS") {
        // End CORS preflight request.
        res.writeHead(204);
        res.end();
    } else {
        // Implement other HTTP methods.
    }
});

Configuration Object

A configuration object with the following properties can be passed to corser.create.

origins

A case-sensitive whitelist of origins. If the request comes from an origin that is not in this list, it will not be handled by CORS. To accept all origins (the Access-Control-Allow-Origin: * behavior), omit the property or set it to an empty array ([]).

To allow for dynamic origin checking, a function (origin, callback) can be passed instead of an array. origin is the Origin header, callback is a function (err, matches), where matches is a boolean flag that indicates whether the given Origin header matches or not.

Default: all origins are accepted.

methods

An uppercase whitelist of methods. If the request uses a method that is not in this list, it will not be handled by CORS.

Setting a value here will overwrite the list of default simple methods. To not lose them, concat the methods you want to add with corser.simpleMethods: corser.simpleMethods.concat(["PUT", "DELETE"]).

Default: simple methods (GET, HEAD, POST).

requestHeaders

A case-insensitive whitelist of request headers. If the request uses a request header that is not in this list, it will not be handled by CORS.

Setting a value here will overwrite the list of default simple request headers. To not lose them, concat the request headers you want to add with corser.simpleRequestHeaders: corser.simpleRequestHeaders.concat(["Authorization"]).

Default: simple request headers (Accept, Accept-Language, Content-Language, Content-Type, Last-Event-ID).

responseHeaders

A case-insensitive whitelist of response headers. Any response header that is not in this list will be filtered out by the user-agent (the browser).

Setting a value here will overwrite the list of default simple response headers. To not lose them, concat the response headers you want to add with corser.simpleResponseHeaders: corser.simpleResponseHeaders.concat(["ETag"]).

Default: simple response headers (Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma).

supportsCredentials

A boolean that indicates if cookie credentials can be transferred as part of a CORS request. Currently, only a few HTML5 elements can benefit from this setting.

Default: false.

maxAge

An integer that indicates the maximum amount of time in seconds that a preflight request is kept in the client-side preflight result cache.

Default: not set.

endPreflightRequests

A boolean that indicates if CORS preflight requests should be automatically closed.

Default: true.

FAQ

Request returns Origin X is not allowed by Access-Control-Allow-Origin

Check if the Origin header of your request matches one of the origins provided in the origins property of the configuration object. If you didn't set any origins property, jump to the next question.

If that does not help, your request might use a non-simple method or one or more non-simple headers (see next question). According to the specification, the set of simple methods is GET, HEAD, and POST, and the set of simple request headers is Accept, Accept-Language, Content-Language, Content-Type, and Last-Event-ID. If your request uses any other method or header, you have to explicitly list them in the methods or requestHeaders property of the configuration object.

Example

You want to allow requests that use an X-Requested-With header. Pass the following configuration object to corser.create:

corser.create({
    requestHeaders: corser.simpleRequestHeaders.concat(["X-Requested-With"])
});

Request returns Request header field Content-Type is not allowed by Access-Control-Allow-Headers

A default configuration will only work if the client sends a "simple" request, i.e., GET, HEAD, POST as method, and some headers such as Accept, Accept-Language, Content-Language, and Content-Type, etc. Content-Type has an important restriction: only application/x-www-form-urlencoded, multipart/form-data, and text/plain are allowed.

Typically the Content-Type of an API will be application/json, and this is not allowed by default. Content-Type needs to be explicitly specified in the configuration object under the requestHeaders key:

Example

corser.create({
    requestHeaders: corser.simpleRequestHeaders.concat(["Content-Type"])
});

Getting a response header returns Refused to get unsafe header "X"

Your browser blocks every non-simple response headers that was not explicitly allowed in the preflight request. The set of simple response headers is Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma. If you want to access any other response header, you have to explicitly list them in the responseHeaders property of the configuration object.

Example

You want to allow clients to read the ETag header of a response. Pass the following configuration object to corser.create:

corser.create({
    responseHeaders: corser.simpleResponseHeaders.concat(["ETag"])
});