CORS is a browser security mechanism to allow Web sites to access data at (i.e. perform HTTP requests to) another origin (proto + domain + port).
In Single Page Applications this is often needed if API and asset domains are different, for example, if users open https://example.com and the web app fetches from https://api.example.com.
It may also be needed in development setups, for example, if the SPA is served by a hot-reloading asset server (such as WebPack or NextJS) on localhost:3000 and FLAT is running on localhost:8080.
CORS handling can be configured in the top-level section of swagger.yaml with the extension object x-flat-cors:
swagger: "2.0"
info:
description: "…"
version: "1.0.0"
title: "My API"
basePath: "/v1"
x-flat-cors:
allowed-origins:
- "https://example.com"
- "http://localhost:3000"
allow-credentials: true
max-age: 300
allowed-origins is a mandatory property that lists the origins that are allowed to use this API as an array of strings. Clients send their origin in the Origin request header. If it matches one of the configured origins, it is reflected back to the client in the Access-Control-Allowed-Origin header.
Origin URLs may contain a * wildcard to match an arbitrary number of subdomains. The following
snippet allows cross-origin requests from example.com and any of its subdomains:
x-flat-cors:
allowed-origins:
- "https://example.com"
- "https://*.example.com"
If you only want to configure one single origin, you may set allowed-origins as a string:
x-flat-cors:
allowed-origins: "https://example.com"
The special origin * allows any web site to access the API:
x-flat-cors:
allowed-origins: "*"
The optional property allow-credentials controls whether the browser is allowed to send Cookies or Authorization headers to the API. This is often necessary if the API wants to read access tokens from request headers. (Also see Working with JWT).
max-age is an optional property that defines how many seconds the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers response headers may be cached by clients. If not set, it defaults to a value of 7200 seconds (2 hours).
Note that different browsers and different versions thereof may have distinct maximum caching durations that may be shorter than the one set by you.
FLAT uses the OpenAPI definition to determine which HTTP methods (“operations”) are allowed on which paths. This information is sent in response to the OPTIONS pre-flight check in the Access-Control-Allow-Methods: GET header.
Requests for URLs outside of the API basePath are answered with 405 Method Not Allowed.
You can test the example x-flat-cors configuration above with curl to simulate preflight checks from different origins:
$ curl -i -X OPTIONS -H "Origin: http://localhost:3000" localhost:8080/v1/users
HTTP/1.1 200 OK
Date: Tue, 06 Aug 2019 09:33:19 GMT
Server: FLAT
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET
Access-Control-Max-Age: 300
Content-Length: 0
This location is not allowed:
$ curl -i -X OPTIONS -H "Origin: http://example.com:80" localhost:8080/v1/users
HTTP/1.1 200 OK
Date: Tue, 06 Aug 2019 09:33:19 GMT
Server: FLAT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET
Content-Length: 0
Note the missing Access-Control-Allow-Origin header in the second response.
Setting max-age to 300 limits the time the headers are cached to 5 minutes overriding the default of 2 hours.
$ curl -i -X OPTIONS -H "Origin: http://localhost:3000" localhost:8080/v1/users
HTTP/1.1 200 OK
Date: Tue, 06 Aug 2019 09:33:19 GMT
Server: FLAT
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET
Access-Control-Max-Age: 300
Content-Length: 0