Easily add Cross-origin resource sharing (CORS) to your API by enabling this plugin.


Configuration

Configuring the plugin is as simple as a single API call, you can configure and enable it for your API by executing the following request on your Kong server:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=cors" \
    --data "config.origin=mockbin.com" \
    --data "config.methods=GET, POST" \
    --data "config.headers=Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token" \
    --data "config.exposed_headers=X-Auth-Token" \
    --data "config.credentials=true" \
    --data "config.max_age=3600"

api: The id or name of the API that this plugin configuration will target

You can also apply it for every API using the http://kong:8001/plugins/ endpoint. Read the Plugin Reference for more information.

form parameter default description
name Name of the plugin to use, in this case: cors
config.origin
optional
* Value for the Access-Control-Allow-Origin header, expects a String.
config.methods
optional
GET,HEAD,PUT,PATCH,POST,DELETE Value for the Access-Control-Allow-Methods header, expects a comma delimited string (e.g. GET,POST).
config.headers
optional
Value of the Access-Control-Request-Headers
request header
Value for the Access-Control-Allow-Headers header, expects a comma delimited string (e.g. Origin, Authorization).
config.exposed_headers
optional
Value for the Access-Control-Expose-Headers header, expects a comma delimited string (e.g. Origin, Authorization). If not specified, no custom headers are exposed.
config.credentials
optional
false Flag to determine whether the Access-Control-Allow-Credentials header should be sent with true as the value.
config.max_age
optional
Indicated how long the results of the preflight request can be cached, in seconds.
config.preflight_continue
optional
false A boolean value that instructs the plugin to proxy the OPTIONS preflight request to the upstream API.

Known issues

Below is a list of known issues or limitations for this plugin.

CORS Limitations

If the client is a browser, there is a known issue with this plugin caused by a limitation of the CORS specification that doesn't allow to specify a custom Host header in a preflight OPTIONS request.

Because of this limitation, this plugin will only work for APIs that have been configured with a request_path setting, and it will not work for APIs that are being resolved using a custom DNS (the request_host property).

To learn how to add request_path to an API, please read the Proxy Reference.