Skip to contents

Plugin for setting up CORS in a fiery server

Source: R/CORS.R
CORS.Rd

Cross-Origin Resource Sharing (CORS) is a mechanism for servers to indicate from where it may be accessed and allows browsers to block requests that are not permitted. For security reasons, browsers limits requests initiated from JavaScript to only those for the same site. To allow requests from other sites the server needs to send the right CORS headers with the response. Read more about CORS at MDN

Details

CORS is opt-in. The security measure is already in place in browsers to limit cross-origin requests, and CORS is a way to break out of this in a controlled manner where you can indicate exactly who can make a request and what requests can be made. In general it works like this:

  1. A request is being initiated from a website, either through JavaScript or another venue, to a site different than the one it originates from.

  2. The browser identifies that the request is cross-origin and sends an OPTIONS request to the server with information about the request it intends to send (this is called a pre-flight request).

  3. The server responds with a 204 response giving the allowed types of requests that can be made for the resource.

  4. If the original request conforms to the response the browser will then send the actual request.

  5. The server responds to the actual request.

  6. The client gets the response, but the browser will limit what information in the response it can access based on the information provided by the server in the pre-flight response.

As can be seen, a CORS request is slightly more complex than the standard request-response you normally think about. However, the pre-flight request can be cached by the browser and so, will not happen every time a ressource is accessed. While a site may employ a CORS policy the same way across all its endpoints it does not need to. It is fine to only turn on CORS for a subset of paths. In general it is a good rule of thumb to set up resource isolation for the paths that do not have CORS enabled.

Initialization

A new 'CORS'-object is initialized using the new() method on the generator and pass in any settings deviating from the defaults

Usage

cors <- CORS$new(...)

Fiery plugin

A CORS object is a fiery plugin and can be used by passing it to the attach() method of the fiery server object. Once attached all requests will be passed through the plugin and the policy applied to it

Active bindings

name

The name of the plugin

Methods

Public methods

Method new()

Initialize a CORS object

Usage

CORS$new(
  path = "/*",
  origin = "*",
  methods = c("get", "head", "put", "patch", "post", "delete"),
  allowed_headers = NULL,
  exposed_headers = NULL,
  allow_credentials = FALSE,
  max_age = NULL
)

Arguments

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 the Access-Control-Allow-Origin header reflect the origin of the request. If FALSE then all origins are denied

  • The string "*" which will allow all origins and set Access-Control-Allow-Origin to *. This is different than setting it to TRUE because * instructs browsers that any origin is allowed and it may use this information when searching the cache

  • A 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 request

  • A function taking the request and returning TRUE if the origin is permitted and FALSE if it is not. If permitted the Access-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 the Access-Control-Request-Headers header value from the request into the Access-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 is TRUE then origin cannot be * according to the spec

max_age

The duration browsers are allowed to keep the preflight response in the cache

Method add_path()

Add CORS settings to a path

Usage

CORS$add_path(
  path = "/*",
  origin = "*",
  methods = c("get", "head", "put", "patch", "post", "delete"),
  allowed_headers = NULL,
  exposed_headers = NULL,
  allow_credentials = FALSE,
  max_age = NULL
)

Arguments

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 the Access-Control-Allow-Origin header reflect the origin of the request. If FALSE then all origins are denied

  • The string "*" which will allow all origins and set Access-Control-Allow-Origin to *. This is different than setting it to TRUE because * instructs browsers that any origin is allowed and it may use this information when searching the cache

  • A 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 request

  • A function taking the request and returning TRUE if the origin is permitted and FALSE if it is not. If permitted the Access-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 the Access-Control-Request-Headers header value from the request into the Access-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 is TRUE then origin cannot be * according to the spec

max_age

The duration browsers are allowed to keep the preflight response in the cache

Method on_attach()

Method for use by fiery when attached as a plugin. Should not be called directly.

Usage

CORS$on_attach(app, ...)

Arguments

app

The fiery server object

...

Ignored

Method clone()

The objects of this class are cloneable with this method.

Usage

CORS$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# Setup CORS for a sub path allowing access from www.trustworthy.com
# Tell the browser to cache the preflight for a day
cors <- CORS$new(
  path = "/shared_assets/*",
  origin = "https://www.trustworthy.com",
  methods = c("get", "head", "post"),
  max_age = 86400
)

# Use it in a fiery server
app <- fiery::Fire$new()

app$attach(cors)