CORS SPI

[dteleguin]

Description

Introduce a new SPI for CORS and create a default implementation based on org.keycloak.services.resources.Cors.

Discussion

(discussed at 6th OAuth SIG)

Motivation

Currently, we have Cors class that belongs to services and is not visible from other modules. The behavior is mostly hardcoded with limited configurability. The introduction of CORS SPI will help solve the following issues:

• Expose the Cors class to the provider infrastructure. Currently, one can only pass Cors to a provider as java.lang.Object and then cast it back in the implementation (1, 2). This will also be required by the upcoming OAuth 2.0 Grant SPI;
• The default implementation will have its configuration namespace (kc.spi-cors-default) which will allow to customize the behavior (example: [CORS] Allow Access-Control-Allow-Headers customization #12682)
• The SPI will allow to replace the built-in CORS implementation with a custom one if needed.

Details

As long as CORS implementation is going to be a provider, using it will require a KeycloakSession. At the OAuth SIG, we have agreed that we can have a new session-based API whilst (temporarily) keeping the old one:

// old API
Cors cors = Cors.add(request);
Cors cors = Cors.add(request, response);

// new API
Cors cors = session.getProvider(Cors.class); // request object will be obtained from KeycloakContext, should cover the absolute majority of cases
Cors cors = session.getProvider(Cors.class).request(request); // override request object
Cors cors = session.getProvider(Cors.class).builder(builder); // set builder
Cors cors = session.getProvider(Cors.class).request(request).builder(builder); // override both, should be rare

This will result in the following changes/decisions:

• The org.keycloak.common.util.Resteasy class will need to be moved to the common module, otherwise it won't be accessible from the Cors::add methods (which will need to resolve KeycloakSession via a Resteasy context).