Many MuleSoft developers struggle with configuring cross-origin resource sharing (CORS) when deploying their mule application or API to API Manager. It’s important to remember that a CORS policy doesn’t protect your API, it helps protect your browser and web application. When a web page makes an HTTP request to your API to load an asset such as a font, image, or JSON file, that request can come from many different places across the internet. If these HTTP requests go unchecked, the security of your browser may be at risk. For example, your browser may be subject to hijacking, or your browser could potentially blindly download malicious code. As a result, many modern browsers follow security policies to mitigate such risks. If you have ever seen this error in your console, you are more than familiar with a CORS error.
|Website Domain||API Domain||Blocked?|
Most servers will allow GET requests but may block requests to modify resources on the server. Servers don’t just blindly block requests though; they have a process in place that first checks and then communicates to the client (your web browser) to determine which requests are allowed. The pre-flight call is also a mechanism that the browser uses to "check first" if there is any restriction on the API side. When a request is made using any of the following HTTP request methods, a standard preflight request will be made before the original request.
Preflight requests use the OPTIONS method. The preflight request is sent before the original request, hence the term “preflight.” The purpose of the preflight request is to determine whether or not the original request is safe (for example, a DELETE request). The server will respond to the preflight request and indicate whether or not the original request is safe. If the server specifies that the original request is safe, it will allow the original request. Otherwise, it will block the original request. The request methods above aren’t the only thing that will trigger a preflight request. If any of the headers that are automatically set by your browser (i.e., user agent) are modified, that will also trigger a preflight request.
Preflight requests are not mandatory in case of Simple requests (if all of the following conditions are met)
If the method is
If we manually set headers like:
- Content-Type (refer below for more conditions)
If we set only the following Content-Type:
The CORS Testing Tool was created by Ahmed Heidar, and is a deployable Mule application that you can deploy to CloudHub. The application has a very simple UI that will allow you to execute CORS policy tests before handing off your application to front end developers who will call your API’s from the client side application.
First, click the link above to download the CORS Testing Tool Mule application. Download the ZIP folder to your local machine then open up Anypoint Studio. Go to File -> Import then select Anypoint Studio project from File System.
Select your unzipped project folder, and click the Finish button.
Now that you have created your project, make sure that you are running the newest version of the Mule runtime engine, and Run the project. Once your application is deployed, navigate to your localhost URL on 0.0.0.0/8081 to open up the CORS Testing Tool web application.
In this example, we’ve created an API that we have deployed to CloudHub and is currently being managed by API Manager. If you want to learn how to setup API Autodiscovery so your mule application can be discovered by API Manager, read this tutorial. In this example, we want to execute a GET request to our example-api which is hosted on CloudHub.
When you attempt to make a GET request to the API endpoint, the GET request will be blocked by the CORS policy and you will see the following error in the console:
"Access to XMLHttpRequest at 'http://xxxxxxxx.us-s1.cloudhub.io' from origin 'http://www.example.com ' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.."
To avoid this error, you need to enable your CORS policy in API Manager.
First, navigate to API Manager and select your preferred environment. Then go to the Policies menu option and click Add New Policy. Select Cross-Origin resource sharing and select the version that is applicable with your runtime version.
When you click on Configure Policy, there are two options to select from. Public resource and Support credentials. Selecting Public resource is preferred since it allows the API to be accessed by any website domain and allows the origin to be a wildcard *. However, if you want to restrict specific origins and have more granular control, unchecking Public resource will help.
When you Uncheck Public resource, you will see options to define your allowed origins, access control max age, and other settings for your CORS policy.
- Origins allow you to add multiple origins with a comma to separate the values.
- Methods allow you to define what type of request can be sent to the API, and all unchecked methods will be blocked by the CORS policy.
- Headers allow you to define which ones are marked as safe.
- Exposed headers allow you to define which headers you want to expose in the response so it can be used for subsequent calls.
Once you have finished entering in your CORS options, apply the changes and wait a couple of seconds for your API policy to propagate. You can test your API using the CORS Testing Tool to verify that the errors have disappeared and the two calls have been triggered by the preflight options request.
Thank you so much for reading this tutorial and thank you Ahmed Heidar for your contribution. To read more MuleSoft developer tutorials, please visit the developer tutorials homepage by clicking here. If this tutorial helped you, please consider leaving a rating below.