INTRODUCTION
Command Line Tools
Working with CFWheels
Handling Requests with Controllers
Displaying Views to Users
Database Interaction Through Models
External Links
CORS Requests
Configure CFWheels to properly handle CORS requests
CFWheels can often act as the "backend" in a modern web application, serving data to multiple types of frontend clients. Typically this would be in the form of (but not limited to) JSON served as an API, with something like VueJS or React on the front end, possibly served under a different domain.
When we separate our systems in such a manner, we need to consider CORS (Cross Origin Resource Sharing) and how to properly serve requests which modern browsers will allow.
The "Quick and Dirty" approach
If you just need to satisfy your CORS requirement quickly, you can do so from CFWheels 2.0 onwards with a simple configuration switch in your
/config/settings.cfm file: set(allowCorsRequests=true);.By default, this will enable the following CORS headers:
1
Access-Control-Allow-Origin
2
*
3
​
4
Access-Control-Allow-Methods
5
GET, POST, PATCH, PUT, DELETE, OPTIONS
6
​
7
Access-Control-Allow-Headers
8
Origin, Content-Type, X-Auth-Token, X-Requested-By, X-Requested-With
Copied!
This will satisfy most requirements to get going quickly, but is more of a blanket "catch all" configuration which doesn't really restrict anything, or provide much information to the API consumer about your available resources.
Custom CORS Headers
From CFWheels 2.1
The options below were introduced in CFWheels 2.1
From CFWheels 2.1, we can be more specific. We still need to specify
set(allowCorsRequests=true); in our /config/settings.cfm to turn on the main CORS functionality, but we can now provide some additional configuration options to fine tune our responses.Access Control Allow Origin
The Access Control Allow Origin header tells the browser whether the domain they are connecting from can access the requested resource.
By default, this header is set to a wildcard allowing connection from any domain. But it might be your VueJS app lives at
app.domain.com and we only want to allow access from that domain to our API.1
// Wildcard
2
set(accessControlAllowOrigin="*")
3
​
4
// Specify a domain
5
set(accessControlAllowOrigin="https://app.domain.com");
6
​
7
// Specify multiple domains in a list
8
set(accessControlAllowOrigin="https://app.domain.com,https://staging-app.domain.com");
Copied!
You can also take advantage of the environment specific configurations, such as only allowing access to
localhost:8080 in /config/development/settings.cfm for example.CFWheels 2.2 allows for subdomain wildcard matching for CORS permitted origins:
1
// Match https://foo.domain.com or https://bar.domain.com or https://www.mydomain.com
2
set(accessControlAllowOrigin = [
3
"https://*.domain.com",
4
"https://www.mydomain.com"
5
]);
Copied!
The CORS spec specifies that you are only allowed either a * wildcard, or a specific URL , i.e https://www.foo.com:8080- it doesn't in itself allow for wildcard subdomains. However in this scenario CFWheels will attempt to match the wildcard and return the full matched domain.
Access Control Allow Methods
The Access Control Allow Methods tells the browser what HTTP Methods (Verbs) are allowed to be performed against the requested resource.
By default these are set to be all possible Methods,
GET, POST, PATCH, PUT, DELETE, OPTIONS. If our API only allows specific methods, we can specify them: note that this is application-wide and not dependent on route.cfscript
1
// Only ever allow GET requests to this API
2
set(accessControlAllowMethods="GET");
3
​
4
// Only ever allow GET, POST and OPTIONS
5
set(accessControlAllowMethods="GET,POST,OPTIONS");
Copied!
Access Control Allow Methods (By Route)
Whilst setting Access Control Allow Methods site-wide is fine, it doesn't actually fulfill the CORS requirement properly - the value returned by this header should indicate what methods are available at that url. For instance,
/cats might only allow GET,POST requests, and /cats/1/ might only allow GET,PUT,PATCH,DELETE requests.Thankfully, we can pull this information in from the routing system automatically! Note,
set(accessControlAllowMethodsByRoute=true) will override set(accessControlAllowMethods())1
// automatically look up the available routes in application.wheels.routes and return the valid methods for the requested route
2
set(accessControlAllowMethodsByRoute=true);
Copied!
Access Control Allow Credentials
If you're sending credentials such as a cookie from your front end application, you may need to turn this header on.
1
// if set to true, include the Access-Control-Allow-Credentials header
2
set(accessControlAllowCredentials=true);
Copied!
Access Control Allow Headers
If you need to specify a specific list of allowed headers, you can simply pass them into this configuration setting
1
// Set site wide allowed headers
2
set(accessControlAllowHeaders = "Origin, Content-Type, X-Auth-Token, X-Requested-By, X-Requested-With, X-MyHeader")
Copied!