Using Configuration with CORS in Helidon MP

Using Configuration with CORS in Helidon MP: Your application code establishes the CORS behavior of your endpoints using the @CrossOrigin annotation. You and your users can override that behavior, as well as the CORS behavior of the built-in services, using MicroProfile configuration.

Understanding the CORS Configuration Formats

Support in Helidon for CORS configuration uses two closely-related cross-origin configuration formats: basic and mapped. Each format corresponds to a class in the Helidon CORS library. The basic format corresponds to the CrossOriginConfig class, and the mapped format corresponds to the MappedCrossOriginConfig class.

Basic Cross-Origin Configuration

In configuration, Helidon represents basic CORS information as a section that contains one or more key/value pairs. Each key-value pair assigns one characteristic of CORS behavior.

The table below lists the parameters for the @CrossOriginConfig annotation and the configuration keys that identify the CORS characteristics.

Annotation Parameter	Configuration Key	Default	CORS Header Name
`allowCredentials`	`allow-credentials`	`false`	`Access-Control-Allow-Credentials`
`allowHeaders`	`allow-headers`	`["*"]`	`Access-Control-Allow-Headers`
`allowMethods`	`allow-methods`	`["*"]`	`Access-Control-Allow-Methods`
`allowOrigins`	`allow-origins`	`["*"]`	`Access-Control-Allow-Origins`
`exposeHeaders`	`expose-headers`	`none`	`Access-Control-Expose-Headers`
`maxAgeSeconds`	`max-age`	`3600`	`Access-Control-Max-Age`
`enabled`	`enabled`	`true`	n/a

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

The following example of basic cross-origin configuration limits cross-origin resource sharing for PUT and DELETE operations to only foo.com and there.com:

...
  allow-origins: ["http://foo.com", "http://there.com"]
  allow-methods: ["PUT", "DELETE"]
...

Copied

Understanding the Mapped Cross-Origin Configuration Format

In Helidon MP, you use the mapped cross-origin configuration format.

Helidon represents mapped CORS information as a section, identified by a configuration key of your choosing, that contains:

An optional enabled setting which defaults to true and applies to the whole mapped CORS config section, and
An optional paths subsection containing zero or more entries, each of which contains:
- a basic CORS config section, and
- a path-pattern path pattern that maps that basic CORS config section to the resource(s) it affects.

You can use mapped configuration to your advantage if you want to allow your users to override the CORS behavior set up in the application code.

The following example illustrates the mapped cross-origin configuration format.

...
cors: 
  paths: 
    - path-pattern: /greeting 
      allow-origins: ["http://foo.com", "http://there.com", "http://other.com"] 
      allow-methods: ["PUT", "DELETE"]
    - path-pattern: / 
      allow-methods: ["GET", "HEAD", "OPTIONS", "POST"] 
...

Copied

The unique identifier for this mapped CORS config section must be cors.
Collects the sequence of entries, each of which maps a basic CORS config to a path pattern.
Marks the beginning of an entry (the - character) and maps the associated basic CORS config to the /greeting subresource (the path-pattern key and value).
Begins the basic CORS config section for /greeting; it restricts sharing via PUT and DELETE to the listed origins.
Marks the beginning of the next entry (the - character) and maps the associated basic CORS config to the top-level resource in the app (the path-pattern key and value).
Begins the basic CORS config section for /; it permits sharing of resources at the top-level path with all origins for the indicated HTTP methods.

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

Be sure to arrange the entries in the order that you want Helidon to check them. Helidon CORS support searches the cross-origin entries in the order you define them until it finds an entry that matches an incoming request’s path pattern and HTTP method.

Specifying Override Values in Configuration

In configuration, you can specify the same CORS-related attributes that you specify using the @CrossOrigin annotation.

The following example shows how you can express configuration similar to that shown previously using the mapped cross-origin configuration format. Here, the example uses properties-file syntax in your applications’s META-INF/microprofile-config.properties file. Note that the top-level config key must be cors.

cors.paths.0.path-pattern = /greeting
cors.paths.0.allow-origins = http://foo.com, http://there.com, http://other.com
cors.paths.0.allow-methods = PUT, DELETE
cors.paths.1.path-pattern = /
cors.paths.1.allow-methods = GET, HEAD, OPTIONS, POST

Copied

Remember that if you set configuration in a file that you include as part of your application JAR file, then you need to rebuild and restart your application for any changes to take effect.

Next Steps

Use these same configuration techniques to control the behavior of the CORS-enabled built-in services. Learn more.
See the Helidon CORS support in action by building and running the CORS example.