Using the Helidon MP CORS API

To enable CORS behavior for a resource in your Helidon MP application, you simply add the Helidon MP @CrossOrigin annotation to a particular method in your resource class.

Maven Coordinates

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>
Copied

Understanding the @CrossOrigin Annotation

You set up CORS in Helidon MP using the @CrossOrigin annotation.

The following example of the @CrossOrigin annotation allows the resource associated with it to be shared with the origins http://foo.bar and http://bar.foo using DELETE or PUT, and permits requests to include the non-standard headers X-foo and X-bar.

@CrossOrigin(value = {"http://foo.bar", "http://bar.foo"},
             allowHeaders = {"X-foo", "X-bar"},
             allowMethods = {HttpMethod.DELETE, HttpMethod.PUT})
Copied

Getting Started

To add CORS support to your Helidon MP application:

  1. Determine the type of cross-origin resource sharing you want to allow for each endpoint in your application.
  2. Add a dependency on the Helidon MP CORS artifact to your Maven pom.xml file.
  3. Edit each JAX-RS resource class in your application to add the desired CORS behavior as described in the following sections.

Adding CORS Support to Your Helidon MP Application

Adding CORS behavior to your Helidon MP application involves three simple steps:

For reach resource class in your application:

  1. Identify the resources and subresources—​in other words, the paths—​supported in each.
  2. For each of those resources and subresources make sure you have a Java method annotated with @OPTIONS and with the correct @Path. Create these methods for each resource (for each path) if you do not already have them.
  3. To each of those @OPTIONS methods add a @CrossOrigin annotation that describes the cross-origin sharing you want for that resource.

Using @CrossOrigin Correctly

Use the @CrossOrigin annotation only on methods which also have the @OPTIONS annotation. Remember that the @CrossOrigin settings apply to a given path and therefore to all Java resource methods which share that path.

Helidon MP aborts the server start-up if a resource method other than an @OPTIONS method has the @CrossOrigin annotation.

The Helidon MP CORS implementation automatically uses the @CrossOrigin annotation you add to each @OPTIONS method to enforce cross-origin sharing behavior for the resource identified by that method’s @Path annotation.

For an informal look at the reasons for applying the @CrossOrigin annotation to the @OPTIONS method, instead of another method, see Why @OPTIONS?.

Sample Application Using the @CrossOrigin Annotation

In the Helidon MP Quickstart application you can change the greeting by sending a PUT request to the /greet/greeting resource. The example below extends the Helidon MP QuickStart application (the greeting app) to:

  • Permit unrestricted sharing of the resource that returns greetings, and

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

@OPTIONS
@CrossOrigin() 
public void options() {}

@OPTIONS
@Path("/greeting")
@CrossOrigin(allowMethods = {"PUT"}, allowOrigins = {"http://foo.com", "http://there.com"}) 
public void optionsForGreeting() {}
Copied
  • Uses the default cross-origin sharing, which permits sharing via all HTTP methods to all origins.
  • Specifies sharing only via the PUT HTTP method and only to the two listed origins.

Next steps

  • Use MicroProfile configuration to override the CORS behavior set in the application code. Learn more.

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