Skip to content
Kong Summit 2022: Where API Innovation Runs Wild  —Learn More →
|
search
Plugin Hub
header icon

CORS

You are browsing documentation for an outdated plugin version. See the latest documentation here.

Easily add Cross-origin resource sharing (CORS) to a Service, a Route (or the deprecated API entity) by enabling this plugin.

Note: The functionality of this plugin as bundled with versions of Kong prior to 0.10.3 differs from what is documented herein. Refer to the CHANGELOG for details.

Configuration Reference

Example plugin configuration

The following examples provide some typical configurations for enabling the cors plugin on a service.

Make the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=cors"  \
    --data "config.origins=http://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"

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <cors-example>
config: 
  origins: http://mockbin.com
  methods: GET, POST
  headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token
  exposed_headers: X-Auth-Token
  credentials: true
  max_age: 3600
plugin: cors

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <cors-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

{SERVICE} is the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

Add this section to your declarative configuration file:

plugins:
- name: cors
  service: {SERVICE}
  config: 
    origins: http://mockbin.com
    methods: GET, POST
    headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token
    exposed_headers: X-Auth-Token
    credentials: true
    max_age: 3600

SERVICE is the id or name of the service that this plugin configuration will target.

  1. In Konnect Cloud, select the service on the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Scroll down to Plugins and click New Plugin.
  4. Find and select the CORS plugin.
  5. Click Create.
  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Services and click View for the service row.
  3. Scroll down to plugins and click Add Plugin.

  4. Find and select the CORS plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already prefilled.
  7. Click Create.

The following examples provide some typical configurations for enabling the cors plugin on a route.

Make the following request:

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=cors"  \
    --data "config.origins=http://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"

ROUTE is the id or name of the route that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <cors-example>
config: 
  origins: http://mockbin.com
  methods: GET, POST
  headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token
  exposed_headers: X-Auth-Token
  credentials: true
  max_age: 3600
plugin: cors

Then, apply it to an ingress (Route or Routes) by annotating the ingress as follows:

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <cors-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

ROUTE is the id or name of the route that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

Add this section to your declarative configuration file:

plugins:
- name: cors
  route: <route>
  config: 
    origins: http://mockbin.com
    methods: GET, POST
    headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token
    exposed_headers: X-Auth-Token
    credentials: true
    max_age: 3600

ROUTE is the id or name of the route that this plugin configuration will target.

  1. In Konnect Cloud, select the service from the ServiceHub page.
  2. Scroll down to Versions and select the version.
  3. Select the route.
  4. Scroll down to Plugins and click Add Plugin.
  5. Find and select the CORS plugin.
  6. Click Create.
  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Routes in the left navigation.
  3. Click View for the route row.
  4. Scroll down to plugins and click Add Plugin.

  5. Find and select the CORS plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  6. If the option is available, select Scoped.
  7. Add the Route ID if it is not already prefilled.
  8. Click Create.

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

The following examples provide some typical configurations for enabling the cors plugin globally.

Make the following request:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=cors"  \
    --data "config.origins=http://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"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-cors>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  origins: http://mockbin.com
  methods: GET, POST
  headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token
  exposed_headers: X-Auth-Token
  credentials: true
  max_age: 3600
plugin: cors

Add a plugins entry in the declarative configuration file:

plugins:
- name: cors
  config: 
    origins: http://mockbin.com
    methods: GET, POST
    headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Auth-Token
    exposed_headers: X-Auth-Token
    credentials: true
    max_age: 3600
  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Plugins in the left navigation.
  3. Click New Plugin.

  4. Find and select the CORS plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
  5. If the option is available, set the plugin scope to Global.
  6. Click Create.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter Description
name
required

Type: string		 The name of the plugin, in this case cors.
service.id

Type: string		 The ID of the Service the plugin targets.
route.id

Type: string		 The ID of the Route the plugin targets.
enabled
required

Type: boolean

Default value: true		 Whether this plugin will be applied.
api_id

Type: string		 The ID of the API the plugin targets.

Note: The API Entity is deprecated in favor of Services since CE 0.13.0 and EE 0.32.
config.origins
optional

A comma-separated list of allowed domains for the Access-Control-Allow-Origin header. If you wish to allow all origins, add * as a single value to this configuration field. The accepted values can either be flat strings or PCRE regexes. NOTE: Prior to Kong 0.10.x, this parameter was config.origin (note the change in trailing s), and only accepted a single value, or the * special value.
config.methods
optional

Default value: GET, HEAD, PUT, PATCH, POST

Value for the Access-Control-Allow-Methods header, expects a comma delimited string (e.g. GET,POST).
config.headers
optional

Default value: 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

Default value: 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

Default value: false

A boolean value that instructs the plugin to proxy the OPTIONS preflight request to the upstream service.

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 uris setting, and it will not work for APIs that are being resolved using a custom DNS (the hosts property).

To learn how to configure uris for an API, please read the Proxy Reference.