Configuration¶
Flask-CORS can be configured at four different locations. Configuration values are determined in the following order:
- Resource level settings (e.g when passed as a dictionary)
- Keyword argument settings
- App level configuration settings (e.g. CORS_*)
- Default settings
See below for more information.
Configuration options¶
Configuration options are consistently named across the various locations where they can be set. A configuration option called example can be set with the resource dictionary key example, as the keyword argument example or as the Flask app configuration key CORS_EXAMPLE.
The configuration options recognised by Flask-CORS are:
- CORS_ALLOW_HEADERS (
List
orstr
) - Headers to accept from the client. Headers in the Access-Control-Request-Headers request header (usually part of the preflight OPTIONS request) matching headers in this list will be included in the Access-Control-Allow-Headers response header.
- CORS_ALWAYS_SEND (
bool
) Usually, if a request doesn’t include an Origin header, the client did not request CORS. This means we can ignore this request.
However, if this is true, a most-likely-to-be-correct value is still set.
- CORS_AUTOMATIC_OPTIONS (
bool
) - Only applies to the
flask_cors.cross_origin()
decorator. If True, Flask-CORS will override Flask’s default OPTIONS handling to return CORS headers for OPTIONS requests. - CORS_EXPOSE_HEADERS (
List
orstr
) - The CORS spec requires the server to give explicit permissions for the client to read headers in CORS responses (via the Access-Control-Expose-Headers header). This specifies the headers to include in this header.
- CORS_INTERCEPT_EXCEPTIONS (
bool
) - Whether to deal with Flask exception handlers or leave them alone (with respect to CORS headers).
- CORS_MAX_AGE (
timedelta
,int
orstr
) - The maximum time for which this CORS request may be cached. This value is set as the Access-Control-Max-Age header.
- CORS_METHODS (
List
orstr
) - The method(s) which the allowed origins are allowed to access. These are included in the Access-Control-Allow-Methods response headers to the preflight OPTIONS requests.
- CORS_ORIGINS (
List
,str
orre.Pattern
) - The origin(s) to allow requests from. An origin configured here that matches the value of the Origin header in a preflight OPTIONS request is returned as the value of the Access-Control-Allow-Origin response header.
- CORS_RESOURCES (
Dict
,List
orstr
) The series of regular expression and (optionally) associated CORS options to be applied to the given resource path.
If the value is a dictionary, it’s keys must be regular expressions matching resources, and the values must be another dictionary of configuration options, as described in this section.
If the argument is a list, it is expected to be a list of regular expressions matching resources for which the app-wide configured options are applied.
If the argument is a string, it is expected to be a regular expression matching resources for which the app-wide configured options are applied.
- CORS_SEND_WILDCARD (
bool
) - If CORS_ORIGINS is
"*"
and this is true, then the Access-Control-Allow-Origin response header’s value with be"*"
as well, instead of the value of the Origin request header. - CORS_SUPPORTS_CREDENTIALS (
bool
) Allows users to make authenticated requests. If true, injects the Access-Control-Allow-Credentials header in responses. This allows cookies and credentials to be submitted across domains.
note: This option cannot be used in conjunction with a “*” origin - CORS_VARY_HEADER: (
bool
) - Enables or disables the injection of the Vary response header is set to
Origin
. This informs clients that our CORS headers are dynamic and cannot be cached.
Default values¶
- CORS_ALLOW_HEADERS: “*”
- CORS_ALWAYS_SEND: True
- CORS_AUTOMATIC_OPTIONS: True
- CORS_EXPOSE_HEADERS: None
- CORS_INTERCEPT_EXCEPTIONS: True
- CORS_MAX_AGE: None
- CORS_METHODS: [”GET”, “HEAD”, “POST”, “OPTIONS”, “PUT”, “PATCH”, “DELETE”]
- CORS_ORIGINS: “*”
- CORS_RESOURCES: r”/*”
- CORS_SEND_WILDCARD: False
- CORS_SUPPORTS_CREDENTIALS: False
- CORS_VARY_HEADER: True
Locations¶
Resource level settings¶
You can specify CORS options on a resource level of granularity by passing a dictionary as the resources keyword argument when instantiating the flask_cors.CORS
object (or when calling init_app
on it), mapping paths to a set of options.
Keyword argument settings¶
For options matching all resources, it’s also possible to simply set the configuration options using keyword arguments when instantiating the flask_cors.CORS
object (or when calling init_app
on it).
App level configuration settings¶
It’s good practice to keep your application configuration settings in one place. This is also possible with Flask-CORS using the same configuration options in the Flas application’s config object.
Default settings¶
Finally, every setting has a default value as well.