• Overview

• Maven Coordinates

• Usage

• API

• Configuration

• Examples

• Additional Information

The cross-origin resource sharing (CORS) protocol helps developers control if and how REST resources served by their applications can be shared across origins. Helidon MP includes an implementation of CORS that you can use to add CORS behavior to the services you develop. You can define your application’s CORS behavior programmatically using the Helidon CORS API alone or together with configuration.

Before you revise your application to add CORS support, you need to decide what type of cross-origin sharing you want to allow for each resource your application exposes. For example, suppose for a given resource you want to allow unrestricted sharing for GET, HEAD, and POST requests (what CORS refers to as "simple" requests), but permit other types of requests only from the two origins foo.com and there.com. Your application would implement two types of CORS sharing: more relaxed for the simple requests and stricter for others.

Once you know the type of sharing you want to allow for each of your resources—​including any from built-in services—​you can change your application accordingly.

To enable CORS, add the following dependency to your project’s pom.xml (see Managing Dependencies).

<dependency>
    <groupId>io.helidon.microprofile</groupId>
    <artifactId>helidon-microprofile-cors</artifactId>
</dependency>

Once you have planned how each of your resources should support CORS, you specify the CORS behavior in one of two ways:

• add @Cors.* annotations to the Java code for the resources, or

• add configuration.

You can do both. CORS configuration for a resource overrides any CORS settings declared using @Cors.* in the Java class for the resource.

The @Cors.* Annotations

You can define CORS behavior—​and you or your users can override behavior declared in your code—​using configuration.

For each resource you want to configure, add a section to META-INF/microprofile-config.properties file:

cors.enabled=  
cors.paths.i.path-pattern= 
cors.paths.i.allow-headers=
cors.paths.i.max-age= 
cors.paths.i.allow-credentials=
cors.paths.i.allow-origins=
cors.paths.i.expose-headers=
cors.paths.i.allow-methods=
cors.paths.i.enabled= 

• You can disable CORS processing for all resources by setting cors.enabled to false. Defaults to true.
• Add a block for each resource you want to configure. The index i is an integer (0, 1, 2, etc).
• Specify the settings as needed to define the CORS behavior you want for that resource.
• The max-age option is a Duration string, such as PT1H for 1 hour
• The enabled setting lets you control whether the system uses that set of CORS configuration. Defaults to true.

The system uses the index i, not the position in the config file, to identify the settings for a particular resource.

Path patterns can be any expression accepted by the PathMatcher class.

Each annotation in Cors class (except for Defaults) is mapped to one of the configuration options, see details below:

Configuration options

The Helidon MP Quickstart application allows users to:

• obtain greetings by sending GET requests to the /greet resource, and

• change the greeting message by sending a PUT request to the /greet/greeting resource.

The Helidon MP CORS Example shows the basic quickstart example enhanced for CORS.

The discussion below describes the changes in the application which:

• permit unrestricted sharing of the resource /greet, and

• restrict sharing of the resource /greet/greeting so that only the origins http://foo.com and http://there.com can change the greeting.

Adding Annotations

@Path("/greet")
public class GreetResource { 

    @GET
    public JsonObject getDefaultMessage() { 
        return Json.createObjectBuilder()
                .add("message", "Hello")
                .build();
    }

    @Path("/greeting")
    @PUT
    public Response updateGreeting(JsonObject jsonObject) { 
        return Response.ok().build();
    }

    @OPTIONS
    @Cors.Defaults
    public void optionsForRetrievingUnnamedGreeting() { 
    }

    @OPTIONS
    @Path("/greeting")
    @Cors.AllowOrigins({"http://foo.com", "http://there.com"})
    @Cors.AllowMethods(HttpMethod.PUT)
    public void optionsForUpdatingGreeting() { 
    }
}

Adding Configuration

cors.paths.0.path-pattern=/greet 

cors.paths.1.path-pattern=/greet/greeting 
cors.paths.1.allow-origins=https://foo.com,https://there.com
cors.paths.1.allow-methods=PUT

cors.paths.0.path-pattern=/greet 
cors.paths.0.allow-methods=GET
cors.paths.0.allow-origins=https://here.com,https://foo.com,https://there.com

cors.paths.1.path-pattern=/greet/greeting 
cors.paths.1.allow-methods=PUT
cors.paths.1.allow-origins=https://foo.com

The decisions the Helidon CORS feature makes depend on accurate information about each incoming request, particularly the host to which the request is sent. Conveyed as headers in the request, this information can be changed or overwritten by intermediate nodes—​such as load balancers—​between the origin of the request and your service.

Well-behaved intermediate nodes preserve this important data in other headers, such as Forwarded. You can configure how the Helidon server handles these headers as described in the documentation for requested URI discovery.

The CORS support in Helidon uses the requested URI feature to discover the correct information about each request, according to your configuration, so it can make accurate decisions about whether to permit cross-origin accesses.

Use configuration to control whether and how each of the built-in services works with CORS.

In the cors configuration section add a block for each built-in service using its path as described in the CORS configuration section.

The following example restricts sharing of

• the /health resource, provided by the health built-in service, to only the origin https://there.com, and

• the /metrics resource, provided by the metrics built-in service, to only the origin https://foo.com.

cors.paths.0.path-pattern=/health
cors.paths.0.allow-origins=https://there.com
cors.paths.1.path-pattern=/metrics
cors.paths.1.allow-origins=https://foo.com

Accessing the Shared Resources

mvn package
java -jar target/helidon-quickstart-mp.jar

 ...
 2020.05.12 05:44:08 INFO io.helidon.microprofile.server.ServerCdiExtension Thread[main,5,main]: Server started on http://localhost:8080 (and all other host addresses) in 5280 milliseconds (since JVM startup).
 ...

Retrieve Metrics

curl -i -H "Origin: https://other.com" http://localhost:8080/metrics

HTTP/1.1 403 Forbidden
Date: Mon, 11 May 2020 11:08:09 -0500
transfer-encoding: chunked
connection: keep-alive

curl -i -H "Origin: https://foo.com" http://localhost:8080/metrics

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://foo.com
Content-Type: text/plain
Date: Mon, 11 May 2020 11:08:16 -0500
Vary: Origin
connection: keep-alive
content-length: 6065

# TYPE base_classloader_loadedClasses_count gauge
# HELP base_classloader_loadedClasses_count Displays the number of classes that are currently loaded in the Java virtual machine.
base_classloader_loadedClasses_count 3568

curl -i -H "Origin: https://foo.com" http://localhost:8080/health

HTTP/1.1 403 Forbidden
Date: Mon, 11 May 2020 12:06:55 -0500
transfer-encoding: chunked
connection: keep-alive

curl -i -H "Origin: https://there.com" http://localhost:8080/health

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://there.com
Content-Type: application/json
Date: Mon, 11 May 2020 12:07:32 -0500
Vary: Origin
connection: keep-alive
content-length: 461

{"outcome":"UP",...}