CORS#

Vapor by default provides a middleware for implementing proper support for Cross-Origin Resource Sharing (CORS) named CORSMiddleware.

“Cross-Origin Resource Sharing (CORS) is a specification that enables truly open access across domain-boundaries. If you serve public content, please consider using CORS to open it up for universal JavaScript / browser access.” - http://enable-cors.org/

To learn more about middlewares, please visit the Middleware section of the documentation here.

Image Author: Wikipedia

Basic#

First of all, add the CORS middleware into your droplet middlewares array.

# Insert CORS before any other middlewares
drop.middleware.insert(CORSMiddleware(), at: 0)

Note: Make sure you insert CORS middleware before any other throwing middlewares, like the AbortMiddleware or similar. Otherwise the proper headers might not be added to the response.

CORSMiddleware has a default configuration which should suit most users, with values as follows:

• Allowed Origin

  • Value of origin header in the request.

• Allowed Methods

  • GET, POST, PUT, OPTIONS, DELETE, PATCH

• Allowed Headers

  • Accept, Authorization, Content-Type, Origin, X-Requested-With

Advanced#

All settings and presets can be customized by advanced users. There’s two ways of doing this, either you programatically create and configure a CORSConfiguration object or you can put your configuration into a Vapor’s JSON config file.

See below for how to set up both and what are the options.

Configuration#

The CORSConfiguration struct is used to configure the CORSMiddleware. You can instanitate one like this:

let configuration = CORSConfiguration(allowedOrigin: .custom("https://vapor.codes"),
						                  allowedMethods: [.get, .post, .options],
						                  allowedHeaders: ["Accept", "Authorization"],
						                  allowCredentials: false,
						                  cacheExpiration: 600,
						                  exposedHeaders: ["Cache-Control", "Content-Language"])

After creating a configuration you can add the CORS middleware.

drop.middleware.insert(CORSMiddleware(configuration: configuration), at: 0)

Note: Please consult the documentation in the source code of the CORSConfiguration for more information about available values for the settings.

JSON Config#

Optionally, CORSMiddleware can be configured using the Vapor’s Config which is created out of the json files contained in your Config folder. You will need to create a file called cors.json or CORS.json in your Config folder in your project and add the required keys.

Example of how such a file could look as follows:

{
    "allowedOrigin": "origin",
    "allowedMethods": "GET,POST,PUT,OPTIONS,DELETE,PATCH",
    "allowedHeaders": ["Accept", "Authorization", "Content-Type", "Origin", "X-Requested-With"]
}

Note: Following keys are required: allowedOrigin, allowedMethods, allowedHeaders. If they are not present an error will be thrown while instantiating the middleware.

Optionally you can also specify the keys allowCredentials (Bool), cacheExpiration (Int) and exposedHeaders ([String]).

Afterwards you can add the middleware using the a throwing overload of the initialiser that accepts Vapor’s Config.

let drop = Droplet()

do {
	drop.middleware.insert(try CORSMiddleware(configuration: drop.config), at: 0)
} catch {
	fatalError("Error creating CORSMiddleware, please check that you've setup cors.json correctly.")
}