Enabling Cross-Origin Resource Sharing (CORS)

duration 15 minutes

Prerequisites:

Learn how to enable Cross-Origin Resource Sharing (CORS) in Open Liberty without writing Java code.

What you’ll learn

You will learn how to add two server configurations to enable CORS. Next, you will write and run tests to validate that the CORS configurations work. These tests send two different CORS requests to a REST service that has two different endpoints.

CORS and its purpose

Cross-Origin Resource Sharing (CORS) is a W3C specification and mechanism that you can use to request restricted resources from a domain outside the current domain. In other words, CORS is a technique for consuming an API served from an origin different than yours.

CORS is useful for requesting data such as images, videos, scripts, style sheets, iFrames, web fonts, and many other kinds of data from websites other than yours.

However, you cannot request resources from outside of your website domain without asking for permission from the other website domains. In JavaScript, cross-origin requests with an XMLHttpRequest API and Ajax cannot happen unless CORS is enabled in the server that is receiving the request. Otherwise, same-origin security policy prevents the requests.

A web page that is served from the http://aboutcors.com server sends a request to get data to the http://openliberty.io server. Because of security concerns, browsers block the server response unless the server adds HTTP response headers to allow the web page to consume the data.

Different ports and different protocols also trigger CORS. For example, the http://abc.xyz:1234 domain is considered to be different from the https://abc.xyz:4321 domain.

Open Liberty has built-in support for CORS that gives you an easy and powerful way to configure the runtime to handle CORS requests without the need to write Java code.

Types of CORS requests

Familiarize yourself with two kinds of CORS requests to understand the attributes that you will add in the two CORS configurations.

Simple CORS request

According to the CORS specification, an HTTP request is a simple CORS request if the request method is GET, HEAD, or POST. The header fields are any one of the Accept, Accept-Language, Content-Language, or Content-Type headers. The Content-Type header has a value of application/x-www-form-urlencoded, multipart/form-data, or text/plain.

When clients, such as browsers, send simple CORS requests to servers on different domains, the clients include an Origin header with the client host name as the value. If the server allows the origin, the server includes an Access-Control-Allow-Origin header with a list of allowed origins or an asterisk (*) in the response back to the client. The asterisk indicates that all origins are allowed to access the endpoint on the server.

Preflight CORS request

A CORS request is not a simple CORS request if a client first sends a preflight CORS request before it sends the actual request. For example, the client sends a preflight request before it sends a DELETE HTTP request. To determine whether the request is safe to send, the client sends a preflight request, which is an OPTIONS HTTP request, to gather more information about the server. This preflight request has the Origin header and other headers to indicate the HTTP method and headers of the actual request to be sent after the preflight request.

Once the server receives the preflight request, if the origin is allowed, the server responds with headers that indicate the HTTP methods and headers that are allowed in the actual requests. The response might include more CORS-related headers.

Next, the client sends the actual request, and the server responds.

Getting started

The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:

git clone https://github.com/openliberty/guide-cors.git
cd guide-cors

The start directory contains the starting project that you will build upon.

The finish directory contains the finished project that you will build.

Enabling CORS

Navigate to the start directory to begin.

You will use a REST service that is already provided for you to test your CORS configurations. Find the service in the src/main/java/io/openliberty/guides/cors/ directory.

Send the simple request to the /configurations/simple endpoint and the preflight request to the /configurations/preflight endpoint.

Enabling a simple CORS configuration

Configure the server to allow the /configurations/simple endpoint to accept a simple CORS request. Add a simple CORS configuration to the server.xml file:

Replace the server configuration file.
src/main/liberty/config/server.xml

server.xml

 1<server description="Sample Liberty server">
 2
 3<featureManager>
 4    <feature>jaxrs-2.1</feature>
 5</featureManager>
 6
 7<httpEndpoint host="*" httpPort="${default.http.port}" httpsPort="${default.https.port}"
 8    id="defaultHttpEndpoint"/>
 9
10<webApplication location="io.openliberty.guides.cors.war" contextRoot="/"/>
11
12<cors domain="/configurations/simple"
13    allowedOrigins="openliberty.io"
14    allowedMethods="GET"
15    allowCredentials="true"
16    exposeHeaders="MyHeader"/>
17
18
19</server>

The simple CORS configuration contains the following attributes:

Configuration Attribute

Value

domain

The endpoint to be configured for CORS requests. The value is set to /configurations/simple.

allowedOrigins

Origins that are allowed to access the endpoint. The value is set to openliberty.io.

allowedMethods

HTTP methods that a client is allowed to use when it makes requests to the endpoint. The value is set to GET.

allowCredentials

A boolean that indicates whether the user credentials can be included in the request. The value is set to true.

exposeHeaders

Headers that are safe to expose to clients. The value is set to MyHeader.

Save the changes to the server.xml file. The /configurations/simple endpoint is now ready to be tested with a simple CORS request.

Open the TestCors.java file in the src/test/java/it/io/openliberty/guides/cors/ directory.

Now we will test the simple CORS configuration that you added. Add the testSimpleCorsRequest method to the TestCors class.

Replace the TestCors class.
src/test/java/it/io/openliberty/guides/cors/TestCors.java

TestCors.java

 1package it.io.openliberty.guides.cors;
 2
 3import static org.junit.Assert.assertEquals;
 4
 5import java.io.IOException;
 6import java.net.HttpURLConnection;
 7import java.util.Map;
 8import java.util.Map.Entry;
 9
10import org.junit.Before;
11import org.junit.Test;
12
13public class TestCors {
14
15    String pathToHost = "http://localhost:9080/";
16
17    @Before
18    public void setUp() {
19        // JVM does not allow restricted headers by default
20        // Set to true for CORS testing
21        System.setProperty("sun.net.http.allowRestrictedHeaders", "true");
22    }
23
24    @Test
25    public void testSimpleCorsRequest() throws IOException  {
26        HttpURLConnection connection = HttpUtils.sendRequest(
27            pathToHost + "configurations/simple",
28            "GET",
29            TestData.simpleRequestHeaders);
30        checkCorsResponse(connection, TestData.simpleResponseHeaders);
31
32        printResponseHeaders(connection, "Simple CORS Request");
33    }
34
35
36    public void checkCorsResponse(HttpURLConnection connection,
37                                Map<String, String> expectedHeaders) throws IOException {
38        assertEquals("Invalid HTTP response code", 200, connection.getResponseCode());
39        expectedHeaders.forEach((responseHeader, value) -> {
40            assertEquals("Unexpected value for " + responseHeader + " header", value,
41                                            connection.getHeaderField(responseHeader));
42        });
43    }
44
45    public static void printResponseHeaders(HttpURLConnection connection, String label) {
46        System.out.println("--- " + label + " ---");
47        Map<String, java.util.List<String>> map = connection.getHeaderFields();
48        for (Entry<String, java.util.List<String>> entry : map.entrySet()) {
49            System.out.println("Header " + entry.getKey() + " = " + entry.getValue());
50        }
51        System.out.println();
52    }
53
54}

The testSimpleCorsRequest test simulates a client. It first sends a simple CORS request to the /configurations/simple endpoint, and then it checks for a valid response and expected headers. Lastly, it prints the response headers for you to inspect.

The request is a GET HTTP request with the following header:

Request Header

Request Value

Origin

The value is set to openliberty.io. Indicates that the request originates from openliberty.io.

Expect the following response headers and values if the simple CORS request is successful, and the server is correctly configured:

Response Header

Response Value

Access-Control-Allow-Origin

The expected value is openliberty.io. Indicates whether a resource can be shared based on the returning value of the Origin request header openliberty.io.

Access-Control-Allow-Credentials

The expected value is true. Indicates that the user credentials can be included in the request.

Access-Control-Expose-Headers

The expected value is MyHeader. Indicates that the header MyHeader is safe to expose.

Go to the start/ directory and run the following command:

mvn install

The testSimpleCorsRequest test passes and prints the response headers with their values from the endpoint. The /configurations/simple endpoint now accepts simple CORS requests.

Response headers with their values from the endpoint:

--- Simple CORS Request ---
Header null = [HTTP/1.1 200 OK]
Header Access-Control-Expose-Headers = [MyHeader]
Header Access-Control-Allow-Origin = [openliberty.io]
Header Access-Control-Allow-Credentials = [true]
Header Content-Length = [22]
Header Content-Language = [en-CA]
Header Date = [Thu, 21 Mar 2019 17:50:09 GMT]
Header Content-Type = [text/plain]
Header X-Powered-By = [Servlet/4.0]

Enabling a preflight CORS configuration

server.xml

 1<server description="Sample Liberty server">
 2
 3<featureManager>
 4    <feature>jaxrs-2.1</feature>
 5</featureManager>
 6
 7<httpEndpoint host="*" httpPort="${default.http.port}" httpsPort="${default.https.port}"
 8    id="defaultHttpEndpoint"/>
 9
10<webApplication location="io.openliberty.guides.cors.war" contextRoot="/"/>
11
12<cors domain="/configurations/simple"
13    allowedOrigins="openliberty.io"
14    allowedMethods="GET"
15    allowCredentials="true"
16    exposeHeaders="MyHeader"/>
17
18<cors domain="/configurations/preflight"
19    allowedOrigins="*"
20    allowedMethods="OPTIONS, DELETE"
21    allowCredentials="true"
22    allowedHeaders="MyOwnHeader1, MyOwnHeader2"
23    maxAge="10"/>
24
25</server>

TestCors.java

 1package it.io.openliberty.guides.cors;
 2
 3import static org.junit.Assert.assertEquals;
 4
 5import java.io.IOException;
 6import java.net.HttpURLConnection;
 7import java.util.Map;
 8import java.util.Map.Entry;
 9
10import org.junit.Before;
11import org.junit.Test;
12
13public class TestCors {
14
15    String pathToHost = "http://localhost:9080/";
16
17    @Before
18    public void setUp() {
19        // JVM does not allow restricted headers by default
20        // Set to true for CORS testing
21        System.setProperty("sun.net.http.allowRestrictedHeaders", "true");
22    }
23
24    @Test
25    public void testSimpleCorsRequest() throws IOException  {
26        HttpURLConnection connection = HttpUtils.sendRequest(
27            pathToHost + "configurations/simple",
28            "GET",
29            TestData.simpleRequestHeaders);
30        checkCorsResponse(connection, TestData.simpleResponseHeaders);
31
32        printResponseHeaders(connection, "Simple CORS Request");
33    }
34
35    @Test
36    public void testPreflightCorsRequest() throws IOException {
37        HttpURLConnection connection = HttpUtils.sendRequest(
38            pathToHost + "configurations/preflight",
39            "OPTIONS",
40            TestData.preflightRequestHeaders);
41        checkCorsResponse(connection, TestData.preflightResponseHeaders);
42
43        printResponseHeaders(connection, "Preflight CORS Request");
44    }
45
46    public void checkCorsResponse(HttpURLConnection connection,
47                                Map<String, String> expectedHeaders) throws IOException {
48        assertEquals("Invalid HTTP response code", 200, connection.getResponseCode());
49        expectedHeaders.forEach((responseHeader, value) -> {
50            assertEquals("Unexpected value for " + responseHeader + " header", value,
51                                            connection.getHeaderField(responseHeader));
52        });
53    }
54
55    public static void printResponseHeaders(HttpURLConnection connection, String label) {
56        System.out.println("--- " + label + " ---");
57        Map<String, java.util.List<String>> map = connection.getHeaderFields();
58        for (Entry<String, java.util.List<String>> entry : map.entrySet()) {
59            System.out.println("Header " + entry.getKey() + " = " + entry.getValue());
60        }
61        System.out.println();
62    }
63
64}

Configure the server to allow the /configurations/preflight endpoint to accept a preflight CORS request. Add another CORS configuration in the server.xml file:

Replace the server configuration file.
src/main/liberty/config/server.xml

The preflight CORS configuration has different values than the simple CORS configuration.

Configuration Attribute

Value

domain

The value is set to /configurations/preflight because the domain is a different endpoint.

allowedOrigins

Origins that are allowed to access the endpoint. The value is set to an asterisk (*) to allow requests from all origins.

allowedMethods

HTTP methods that a client is allowed to use when it makes requests to the endpoint. The value is set to OPTIONS, DELETE.

allowCredentials

A boolean that indicates whether the user credentials can be included in the request. The value is set to true.

The follow attributes were added:

  • maxAge: The number of seconds that a client can cache a response to a preflight request. Set the value to 10.

  • allowedHeaders: Headers that a client can use in requests. Set the value to MyOwnHeader1, MyOwnHeader2.

Save the changes to the server.xml file. The /configurations/preflight endpoint is now ready to be tested with a preflight CORS request.

Add another test to the TestCors.java file to test the preflight CORS configuration that you just added:

Replace the TestCors class.
src/test/java/it/io/openliberty/guides/cors/TestCors.java

The testPreflightCorsRequest test simulates a client sending a preflight CORS request. It first sends the request to the /configurations/preflight endpoint, and then it checks for a valid response and expected headers. Lastly, it prints the response headers for you to inspect.

The request is an OPTIONS HTTP request with the following headers:

Request Header

Request Value

Origin

The value is set to anywebsiteyoulike.com. Indicates that the request originates from anywebsiteyoulike.com.

Access-Control-Request-Method

The value is set to DELETE. Indicates that the HTTP DELETE method will be used in the actual request.

Access-Control-Request-Headers

The value is set to MyOwnHeader2. Indicates the header MyOwnHeader2 will be used in the actual request.

Expect the following response headers and values if the preflight CORS request is successful, and the server is correctly configured:

Response Header

Response Value

Access-Control-Allow-Max-Age

The expected value is 10. Indicates that the preflight request can be cached within 10 seconds.

Access-Control-Allow-Origin

The expected value is anywebsiteyoulike.com. Indicates whether a resource can be shared based on the returning value of the Origin request header anywebsiteyoulike.com.

Access-Control-Allow-Methods

The expected value is OPTIONS, DELETE. Indicates that HTTP OPTIONS and DELETE methods can be used in the actual request.

Access-Control-Allow-Credentials

The expected value is true. Indicates that the user credentials can be included in the request.

Access-Control-Allow-Headers

The expected value is MyOwnHeader1, MyOwnHeader2. Indicates that the header MyOwnHeader1 and MyOwnHeader2 are safe to expose.

The Access-Control-Allow-Origin header has a value of anywebsiteyoulike.com because the server is configured to allow all origins, and the request came with an origin of anywebsiteyoulike.com.

Go to the start/ directory and run the following command:

mvn install

The testPreflightCorsRequest test passes and prints the response headers with their values from the endpoint. The /configurations/preflight endpoint now allows preflight CORS requests.

Response headers with their values from the endpoint:

--- Preflight CORS Request ---
Header null = [HTTP/1.1 200 OK]
Header Access-Control-Allow-Max-Age = [10]
Header Access-Control-Allow-Origin = [anywebsiteyoulike.com]
Header Access-Control-Allow-Methods = [OPTIONS, DELETE]
Header Access-Control-Allow-Credentials = [true]
Header Content-Length = [0]
Header Date = [Thu, 21 Mar 2019 18:21:13 GMT]
Header Content-Language = [en-CA]
Header Access-Control-Allow-Headers = [MyOwnHeader1, MyOwnHeader2]
Header X-Powered-By = [Servlet/4.0]

If you want, modify the server configuration and the test code to experiment with the various CORS configuration attributes.

Great work! You’re done!

You enabled CORS support in Open Liberty. You added two different CORS configurations to allow two kinds of CORS requests in the server.xml file.

Guide Attribution

Enabling Cross-Origin Resource Sharing (CORS) by Open Liberty is licensed under CC BY-ND 4.0

Copied to clipboard
Copy code block
Copy file contents

Prerequisites:

Nice work! Where to next?

What did you think of this guide?

Extreme Dislike Dislike Like Extreme Like

What could make this guide better?

Raise an issue to share feedback

Create a pull request to contribute to this guide

Need help?

Ask a question on Stack Overflow

Like Open Liberty? Star our repo on GitHub.

Star