edit

Warning

This section may contain outdated information.

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.")
}