This function adds Cross-Origin Resource Sharing (CORS) to a path in your API. The function can be called multiple times to set up CORS for multiple paths, potentially with different settings for each path. CORS is a complex specification and more can be read about it at the CORS plugin documentation.
Usage
api_security_cors(
api,
path = "/*",
origin = "*",
methods = c("get", "head", "put", "patch", "post", "delete"),
allowed_headers = NULL,
exposed_headers = NULL,
allow_credentials = FALSE,
max_age = NULL
)
Arguments
- api
A plumber2 api object to add the plugin to
- path
The path that the policy should apply to. routr path syntax applies, meaning that wilcards and path parameters are allowed.
- origin
The origin allowed for the path. Can be one of:
A boolean. If
TRUE
then all origins are permitted and the preflight response will have theAccess-Control-Allow-Origin
header reflect the origin of the request. IfFALSE
then all origins are deniedThe string
"*"
which will allow all origins and setAccess-Control-Allow-Origin
to*
. This is different than setting it toTRUE
because*
instructs browsers that any origin is allowed and it may use this information when searching the cacheA character vector giving allowed origins. If the request origin matches any of these then the
Access-Control-Allow-Origin
header in the response will reflect the origin of the requestA function taking the request and returning
TRUE
if the origin is permitted andFALSE
if it is not. If permitted theAccess-Control-Allow-Origin
header will reflect the request origin
- methods
The HTTP methods allowed for the
path
- allowed_headers
A character vector of request headers allowed when making the request. If the request contains headers not permitted, then the response will be blocked by the browser.
NULL
will allow any header by reflecting theAccess-Control-Request-Headers
header value from the request into theAccess-Control-Allow-Headers
header in the response.- exposed_headers
A character vector of response headers that should be made available to the client upon a succesful request
- allow_credentials
A boolean indicating whether credentials are allowed in the request. Credentials are cookies or HTTP authentication headers, which are normally stripped from
fetch()
requests by the browser. If this isTRUE
thenorigin
cannot be*
according to the spec- max_age
The duration browsers are allowed to keep the preflight response in the cache
Using annotation
To add CORS to a path you can add @cors <origin>
to a
handler annotation. <origin>
must be one or more URLs or *
, separated by
comma (meaning it is not possible to provide a function using the annotation).
This will add CORS to all endpoints described in the block. The annotation
doesn't allow setting allowed_headers
, exposed_headers
,
allow_credentials
or max_age
and the default values will be used.
#* A handler for /user/<username>
#*
#* @param username:string The name of the user to provide information on
#*
#* @get /user/<username>
#*
#* @response 200:{name:string, age:integer, hobbies:[string]} Important
#* information about the user such as their name, age, and hobbies
#*
#* @cors https://example.com, https://another-site.com
#*
function(username) {
find_user_in_db(username)
}
See also
Other security features:
api_security_headers()
,
api_security_resource_isolation()
Examples
# Set up cors for your asset/ path for the https://examples.com origin
api() |>
api_security_cors(
path = "asset/*",
origin = "https://examples.com"
)
#> ── A plumber server ────────────────────────────────────────────────────────────
#> Serving on http://127.0.0.1:8080
#> Currently not running