1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
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_*)
#. :ref:`Default settings <cors_default_values>`
See :ref:`below <locations>` for more information.
Configuration options
~~~~~~~~~~~~~~~~~~~~~
Configuration options are consistently named across the various :ref:`locations <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 (:py:class:`~typing.List` or :py:class:`str`)
Headers to accept from the client.
Headers in the :http:header:`Access-Control-Request-Headers` request header (usually part of the preflight OPTIONS request) matching headers in this list will be included in the :http:header:`Access-Control-Allow-Headers` response header.
CORS_ALWAYS_SEND (:py:class:`bool`)
Usually, if a request doesn't include an :http:header:`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 (:py:class:`bool`)
Only applies to the :py:meth:`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 (:py:class:`~typing.List` or :py:class:`str`)
The CORS spec requires the server to give explicit permissions for the client to read headers in CORS responses (via the :http:header:`Access-Control-Expose-Headers` header).
This specifies the headers to include in this header.
CORS_INTERCEPT_EXCEPTIONS (:py:class:`bool`)
Whether to deal with Flask exception handlers or leave them alone (with respect to CORS headers).
CORS_MAX_AGE (:py:class:`~datetime.timedelta`, :py:class:`int` or :py:class:`str`)
The maximum time for which this CORS request may be cached.
This value is set as the :http:header:`Access-Control-Max-Age` header.
CORS_METHODS (:py:class:`~typing.List` or :py:class:`str`)
The method(s) which the allowed origins are allowed to access.
These are included in the :http:header:`Access-Control-Allow-Methods` response headers to the preflight OPTIONS requests.
.. _cors_origins_setting:
CORS_ORIGINS (:py:class:`~typing.List`, :py:class:`str` or :py:class:`re.Pattern`)
The origin(s) to allow requests from.
An origin configured here that matches the value of the :http:header:`Origin` header in a preflight OPTIONS request is returned as the value of the :http:header:`Access-Control-Allow-Origin` response header.
CORS_RESOURCES (:py:class:`~typing.Dict`, :py:class:`~typing.List` or :py:class:`str`)
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 (:py:class:`bool`)
If :ref:`CORS_ORIGINS <cors_origins_setting>` is ``"*"`` and this is true, then the :http:header:`Access-Control-Allow-Origin` response header's value with be ``"*"`` as well, instead of the value of the :http:header:`Origin` request header.
CORS_SUPPORTS_CREDENTIALS (:py:class:`bool`)
Allows users to make authenticated requests.
If true, injects the :http:header:`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: (:py:class:`bool`)
Enables or disables the injection of the :http:header:`Vary` response header is set to ``Origin``.
This informs clients that our CORS headers are dynamic and cannot be cached.
.. _cors_default_values:
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: [":http:method:`get`", ":http:method:`head`", ":http:method:`post`", ":http:method:`options`", ":http:method:`put`", ":http:method:`patch`", ":http:method:`delete`"]
* CORS_ORIGINS: "*"
* CORS_RESOURCES: r"/\*"
* CORS_SEND_WILDCARD: False
* CORS_SUPPORTS_CREDENTIALS: False
* CORS_VARY_HEADER: True
.. _locations:
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 :py:class:`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 :py:class:`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 :ref:`default value <cors_default_values>` as well.
|
