Skip to content

# Decorator

This function is the decorator which is used to wrap a Flask route with. In the simplest case, simply use the default parameters to allow all origins in what is the most permissive configuration. If this method modifies state or performs authentication which may be brute-forced, you should add some degree of protection, such as Cross Site Request Forgery protection.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`origins` | `(list, string | regex)` | The origin, or list of origins to allow requests from. The origin(s) may be regular expressions, case-sensitive strings, or else an asterisk Default : '*' | required
`methods` | `list | string` | The method or list of methods which the allowed origins are allowed to access for non-simple requests. Default : [GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE] | required
`expose_headers` | `list | string` | The header or list which are safe to expose to the API of a CORS API specification. Default : None | required
`allow_headers` | `(list, string | regex)` | The header or list of header field names which can be used when this resource is accessed by allowed origins. The header(s) may be regular expressions, case-sensitive strings, or else an asterisk. Default : '*', allow all headers | required
`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 Default : False | required
`max_age` | `(timedelta, integer, string | None)` | The maximum time for which this CORS request maybe cached. This value is set as the `Access-Control-Max-Age` header. Default : None | required
`send_wildcard` | `bool` | If True, and the origins parameter is `*`, a wildcard `Access-Control-Allow-Origin` header is sent, rather than the request's `Origin` header. Default : False | required

`vary_header`

`bool`

If True, the header Vary: Origin will be returned as per the W3 implementation guidelines.

Setting this header when the `Access-Control-Allow-Origin` is dynamically generated (e.g. when there is more than one allowed origin, and an Origin than '*' is returned) informs CDNs and other caches that the CORS headers are dynamic, and cannot be cached.

If False, the Vary header will never be injected or altered.

Default : True

required

`automatic_options` | `bool` | Only applies to the `cross_origin` decorator. If True, Flask-CORS will override Flask's default OPTIONS handling to return CORS headers for OPTIONS requests. Default : True | required

Source code in `flask_cors/decorator.py`

     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
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143

    def cross_origin(*args: Any, **kwargs: Unpack[CrossOriginOptionsInput]) -> Callable[[F], F]:
        """
        This function is the decorator which is used to wrap a Flask route with.
        In the simplest case, simply use the default parameters to allow all
        origins in what is the most permissive configuration. If this method
        modifies state or performs authentication which may be brute-forced, you
        should add some degree of protection, such as Cross Site Request Forgery
        protection.

        :param origins:
            The origin, or list of origins to allow requests from.
            The origin(s) may be regular expressions, case-sensitive strings,
            or else an asterisk

            Default : '*'
        :type origins: list, string or regex

        :param methods:
            The method or list of methods which the allowed origins are allowed to
            access for non-simple requests.

            Default : [GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE]
        :type methods: list or string

        :param expose_headers:
            The header or list which are safe to expose to the API of a CORS API
            specification.

            Default : None
        :type expose_headers: list or string

        :param allow_headers:
            The header or list of header field names which can be used when this
            resource is accessed by allowed origins. The header(s) may be regular
            expressions, case-sensitive strings, or else an asterisk.

            Default : '*', allow all headers
        :type allow_headers: list, string or regex

        :param supports_credentials:
            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

            Default : False
        :type supports_credentials: bool

        :param max_age:
            The maximum time for which this CORS request maybe cached. This value
            is set as the `Access-Control-Max-Age` header.

            Default : None
        :type max_age: timedelta, integer, string or None

        :param send_wildcard: If True, and the origins parameter is `*`, a wildcard
            `Access-Control-Allow-Origin` header is sent, rather than the
            request's `Origin` header.

            Default : False
        :type send_wildcard: bool

        :param vary_header:
            If True, the header Vary: Origin will be returned as per the W3
            implementation guidelines.

            Setting this header when the `Access-Control-Allow-Origin` is
            dynamically generated (e.g. when there is more than one allowed
            origin, and an Origin than '*' is returned) informs CDNs and other
            caches that the CORS headers are dynamic, and cannot be cached.

            If False, the Vary header will never be injected or altered.

            Default : True
        :type vary_header: bool

        :param automatic_options:
            Only applies to the `cross_origin` decorator. If True, Flask-CORS will
            override Flask's default OPTIONS handling to return CORS headers for
            OPTIONS requests.

            Default : True
        :type automatic_options: bool

        """
        _options = kwargs

        def decorator(f: F) -> F:
            LOG.debug("Enabling %s for cross_origin using options:%s", f, _options)

            # If True, intercept OPTIONS requests by modifying the view function,
            # replicating Flask's default behavior, and wrapping the response with
            # CORS headers.
            #
            # If f.provide_automatic_options is unset or True, Flask's route
            # decorator (which is actually wraps the function object we return)
            # intercepts OPTIONS handling, and requests will not have CORS headers
            if _options.get("automatic_options", True):
                # ``f`` is a plain view function; these attributes are read by
                # Flask's routing. Use an ``Any`` alias so the dynamic attribute
                # assignment type-checks.
                view_func: Any = f
                required_methods = set(getattr(f, "required_methods", set()))
                required_methods.add("OPTIONS")
                view_func.required_methods = required_methods
                view_func.provide_automatic_options = False

            def wrapped_function(*args: Any, **kwargs: Any) -> Response:
                # Handle setting of Flask-Cors parameters
                options = get_cors_options(current_app, _options)

                if options.automatic_options and request.method == "OPTIONS":
                    resp = current_app.make_default_options_response()
                else:
                    resp = make_response(f(*args, **kwargs))

                set_cors_headers(resp, options)
                setattr(resp, FLASK_CORS_EVALUATED, True)
                return resp

            return cast(F, update_wrapper(wrapped_function, f))

        return decorator