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 the API is running on different domain than the asset domain. 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
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
HTTP request header. If it matches one of the configured origins, it is reflected back to the client in the Access-Control-Allowed-Origin
header.
If you only want to configure one origin, you can set allowed-origins
as a string:
x-flat-cors:
allowed-origins: "https://example.com"
The special origin *
allows all Websites to access the API.
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).
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 pre-flight 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
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
They look similar, but in the second request the Access-Control-Allow-Origin
header is missing.