Community Documentation
Enabling Cross Origin Resource Sharing (CORS)
Document updated on Jul 10, 2020
About this feature
| Since | v0.6 |
|---|---|
| Namespace | security/cors |
| Log prefix | [SERVICE: Gin][CORS] |
| Scope | service |
| Source | krakend/krakend-cors |
When KrakenD endpoints are consumed from a browser, you might need to 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
| When requests can include user credentials like cookies, HTTP authentication or client side SSL certificates. Defaults to false |
| An array with the headers allowed, but Originis always appended to the list. Requests with headers not in this list are rejected.Defaults to [] |
| An array with all the HTTP methods allowed, in uppercase. Possible values are GET, HEAD,POST,PUT,PATCH,DELETE, or OPTIONSDefaults to ["GET","HEAD","POST"] |
| An array with all the origins allowed, examples of values are https://example.com, or * (any origin).Defaults to ["*"] |
| Show debugging information in the logger, use it only during development. Defaults to false |
| List of headers that are safe to expose to the API of a CORS API specification. Defaults to ["Content-Length","Content-Type"] |
| For how long the response can be cached. For zero values the Access-Control-Max-Age header is not set.Specify units using ns (nanoseconds), us or µs (microseconds), ms (milliseconds), s (seconds), m (minutes), or h (hours).Defaults to "0h" |
Debugging configuration
The following configuration might help you debugging 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"
}
]
}
]}
