Document updated on Jun 27, 2023
Cross-Origin Resource Sharing (CORS) Configuration
When KrakenD endpoints are consumed from a browser, you should enable the Cross-Origin Resource Sharing (CORS) module, as browsers restrict cross-origin HTTP requests initiated from scripts.
When the Cross-Origin Resource Sharing (CORS) configuration is enabled, KrakenD uses additional HTTP headers to tell browsers that they can use resources from a different origin (domain, protocol, or port). For instance, you will need this configuration if your web page is hosted at https://www.domain.com and the Javascript references the KrakenD API at https://api.domain.com.
Configuration
CORS configuration lives in the root of the file, as it’s a service component. Add the namespace security/cors under the global extra_config as follows:
{
"version": 3,
"extra_config": {
"security/cors": {
"allow_origins": [
"*"
],
"allow_methods": [
"GET",
"HEAD",
"POST"
],
"expose_headers": [
"Content-Length",
"Content-Type"
],
"allow_headers": [
"Accept-Language"
],
"max_age": "12h",
"allow_credentials": false,
"debug": false
}
}
The configuration options of this component are as follows:
Fields of HTTP Security
allow_credentialsboolean- When requests can include user credentials like cookies, HTTP authentication or client side SSL certificates.Defaults to
false allow_headersarray- An array with the headers allowed, but
Originis always appended to the list. Requests with headers not in this list are rejected.Defaults to[] allow_methodsarray- An array with all the HTTP methods allowed, in uppercase. Possible values are
GET,HEAD,POST,PUT,PATCH,DELETE, orOPTIONSDefaults to["GET","HEAD","POST"] allow_originsarray- An array with all the origins allowed, examples of values are
https://example.com, or*(any origin).Defaults to["*"] debugboolean- Show debugging information in the logger, use it only during development.Defaults to
false expose_headersarray- List of headers that are safe to expose to the API of a CORS API specification.Defaults to
["Content-Length","Content-Type"] max_agestring- For how long the response can be cached. For zero values the
Access-Control-Max-Ageheader is not set.Specify units usingns(nanoseconds),usorµs(microseconds),ms(milliseconds),s(seconds),m(minutes), orh(hours).Defaults to"0h"
Debugging configuration
The following configuration might help you debug your CORS configuration. Check the inline @comments:
{
"endpoints":[
{
"@comment": "this will fail due to double CORS validation",
"endpoint":"/cors/no-op",
"input_headers":["*"],
"output_encoding": "no-op",
"backend":[
{
"url_pattern": "/__debug/cors",
"host": ["http://localhost:8080"],
"encoding": "no-op"
}
]
},
{
"@comment": "this won't fail because CORS preflight headers are removed from the request to the backend",
"endpoint":"/cors/no-op/martian",
"input_headers":["*"],
"output_encoding": "no-op",
"backend":[
{
"url_pattern": "/__debug/cors/martian",
"host": ["http://localhost:8080"],
"encoding": "no-op",
"extra_config":{
"modifier/martian": {
"fifo.Group": {
"scope": ["request", "response"],
"aggregateErrors": true,
"modifiers": [
{
"header.Blacklist": {
"scope": ["request"],
"names": [
"Access-Control-Request-Method",
"Sec-Fetch-Dest",
"Sec-Fetch-Mode",
"Sec-Fetch-Site",
"Origin"
]
}
}
]
}
}
}
}
]
},
{
"@comment": "this won't fail because no headers are added to the request to the backend",
"endpoint":"/cors/no-op/no-headers",
"output_encoding": "no-op",
"backend":[
{
"url_pattern": "/__debug/cors/no-headers",
"host": ["http://localhost:8080"],
"encoding": "no-op"
}
]
}
]}
Adding the OPTIONS method
When working in a SPA, you will usually receive OPTIONS calls to KrakenD; although this configuration is not related to CORS, it usually goes in hand.
To support OPTIONS in your endpoints, you only need to add the flag auto_options as follows:
{
"version": 3,
"extra_config": {
"router": {
"auto_options": true
},
"security/cors": {
"@comment": "...CORS configuration inside this block..."
}
}
Fields of "router"
auto_optionsboolean- When true, enables the autogenerated OPTIONS endpoint for all the registered paths
