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

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

To add CORS behavior to endpoints, you need to make only minimal changes to how you set up the routing for those endpoints. Using the Helidon SE CORS API, you define the CORS behavior that you want and then include that behavior as you build the routing rules for the services in your application.

The Helidon SE CORS API provides two key classes that you use in your application:

• CorsSupport - Represents information about resource sharing for a single resource. Typically, you create one CorsSupport instance for each distinct resource in your application (such as the /greet resource in the QuickStart greeting application) that should participate in CORS.

• CrossOriginConfig - Represents the details for a particular type of sharing, such as which origins are allowed to have access using which HTTP methods, etc. Create one instance of CrossOriginConfig for each different type of sharing you need.

You associate one or more CrossOriginConfig objects with each CorsSupport object. You use the CorsSupport object when you construct the routing rules for the service. When your application is running and requests arrive, the Helidon CORS implementation enforces the CORS behavior represented by the CorsSupport object before routing the request to your endpoint code for the resource.

To add CORS support to your Helidon SE application:

1. Determine the type of cross origin sharing you want to allow for each endpoint in your application.
2. Add a dependency on the Helidon SE CORS artifact to your Maven pom.xml file.
3. Modify how your application constructs routing rules so they include CORS as described in the following sections.

Because Helidon SE does not use annotation processing to identify endpoints, you need to provide the CORS information for your application another way - by including CORS into the routing you construct for your application.

For each distinct resource or subresource your application exposes:

1. Create a CorsSupport instance corresponding to the resource.
2. For each different type of sharing you want to provide for that resource:
   1. Create a CrossOriginConfig instance.
      The CrossOriginConfig Java class represents the details for a particular type of sharing, such as which origins are allowed to share via which HTTP methods, etc.
   2. Add the CrossOriginConfig to the CorsSupport instance for this resource.
3. Use the resource’s CorsSupport object in setting up the routing rules for that resource.

Each of these classes has an associated builder that you use in constructing instances of the class.

The table below describes the methods on the CrossOriginConfig.Builder class that map to the headers defined in the CORS protocol.

If the cross-origin configuration is disabled (enabled = false), then the Helidon CORS implementation ignores the cross-origin configuration entry.

The Helidon SE Quickstart application lets you change the greeting by sending a PUT request to the /greet/greeting resource.

This example, based on the QuickStart greeting app, uses the low-level CrossOriginConfig API and the CorsSupport API to influence the routing, thereby determining how that resource is shared. (If desired, you can use configuration instead of the low-level API. Learn more.)

The following code shows how to prepare your application’s routing to support metrics and health support, as well as CORS.

    private static Routing createRouting(Config config) {

        MetricsSupport metrics = MetricsSupport.create();
        GreetService greetService = new GreetService(config);
        HealthSupport health = HealthSupport.builder()
                .addLiveness(HealthChecks.healthChecks())   // Adds a convenient set of checks
                .build();
        CorsSupport corsSupport = CorsSupport.builder()  
                .addCrossOriginConfig(CrossOriginConfig.builder() 
                            .allowOrigins("http://foo.com", "http://there.com") 
                            .allowMethods("PUT", "DELETE") 
                            .build()) 
                .addCrossOriginConfig(CrossOriginConfig.create()) 
                .build(); 

        // Note: Add the CORS routing *before* registering the GreetService routing.
        return Routing.builder()
                .register(JsonSupport.create())
                .register(health)                   // Health at "/health"
                .register(metrics)                 // Metrics at "/metrics"
                .register("/greet", corsSupport, greetService) 
                .build();
    }

• Create a CorsSupport.Builder instance.
• Add a CrossOriginSupport instance (using its builder) to constrain resource sharing.
• List the origins (sites) allowed to share resources from this app.
• List the HTTP methods the constraint applies to.
• Build the CrossOriginSupport instance.
• Add a CrossOriginSupport instance that permits all sharing (the default).
• Build the CorsSupport instance.
• Register the new CorsSupport instance with — but in front of — the service which implements the business logic.

The order of steps 2 and 6 above is important. When processing an incoming request, the Helidon CORS implementation scans the CrossOriginConfig instances in the order they were added to the CorsSupport object, stopping as soon as it finds a CrossOriginConfig instance for which allowMethods matches the HTTP method of the request.

The few additional lines described above allow the greeting application to participate in CORS.

• Use configuration in combination with the API to add CORS to your application. Learn more.

• See the Helidon CORS support in action by building and running the CORS example.