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
Enable on a service
Enable on a route
Enable globally
The following examples provide some typical configurations for enabling
the cors
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
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.
- In Konnect Cloud, select the service on the ServiceHub page.
- Scroll down to Versions and select the version.
- Scroll down to Plugins and click New Plugin.
- Find and select the CORS plugin.
- Click Create.
- In Kong Manager, select the workspace.
- From the Dashboard, scroll down to Services and click View for the
service row.
- Scroll down to plugins and click Add Plugin.
-
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.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already prefilled.
- Click Create.
The following examples provide some typical configurations for enabling
the cors
plugin on a
route.
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
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.
- In Konnect Cloud, select the service from the ServiceHub page.
- Scroll down to Versions and select the version.
- Select the route.
- Scroll down to Plugins and click Add Plugin.
- Find and select the CORS plugin.
- Click Create.
- In Kong Manager, select the workspace.
- From the Dashboard, select Routes in the left navigation.
- Click View for the route row.
- Scroll down to plugins and click Add Plugin.
-
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.
- If the option is available, select Scoped.
- Add the Route ID if it is not already prefilled.
- 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.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
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
- In Kong Manager, select the workspace.
- From the Dashboard, select Plugins in the left navigation.
- Click New Plugin.
-
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.
- If the option is available, set the plugin scope to Global.
- 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.