CORS settings

The EdgeX microservices provide REST APIs and those services might be called from a GUI through a browser. Browsers prevent service calls from a different origin, making it impossible to host a management GUI on one domain that manages an EdgeX device on a different domain. Thus, EdgeX supports Cross-Origin Resource Sharing (CORS) since Jakarta release (v2.1), and this feature can be controlled by the configurations. The default behavior of CORS is disabled. Here is a good reference to understand CORS.

Enabling CORS

There are two different ways to enable CORS depending on whether EdgeX is deployed in the security-enabled configuration. In the non-security configuration, EdgeX microservices are directly exposed on host ports. EdgeX microservices receive client requests directly in this configuration, and thus, the EdgeX microservices themselves must respond to CORS requests. In the security-enabled configuration, EdgeX microservices are exposed behind an API gateway that will receive CORS requests first. Only authenticated calls will be forwarded to the EdgeX microservice, but CORS pre-flight requests are always unauthenticated.

CORS can be enabled at the API gateway in a security-enabled configuration, and at the individual microservice level in the non-security configuration. However, implementers should choose one or the other, not both.

Enabling CORS for Microservices

There are two different options to enable CORS.

• Enable CORS for all services by environment variables override under core-common-config-bootstrapper service section on docker-compose.file. They can be set via SERVICE_CORSCONFIGURATION_* environment variables. Please refer to the following example:

core-common-config-bootstrapper:
  environment: 
    SERVICE_CORSCONFIGURATION_ENABLECORS: "true"

• Enable CORS for individual microservices
  1. Add Service.CORSConfiguration.EnableCORS via Consul for the targeted service and restart the service.
  2. Add Service.CORSConfiguration.EnableCORS to each services private configuration file.

Please refer to the Common Configuration page to learn the details.

Enabling CORS for API Gateway

The default CORS settings for the API gateway come from the following section in cat cmd/core-common-config-bootstrapper/res/configuration.yaml in the edgex-go repository

all-services:
  Service:
    CORSConfiguration:
      EnableCORS: false
      CORSAllowCredentials: false
      CORSAllowedOrigin: "https://localhost"
      CORSAllowedMethods: "GET, POST, PUT, PATCH, DELETE"
      CORSAllowedHeaders: "Authorization, Accept, Accept-Language, Content-Language, Content-Type, X-Correlation-ID"
      CORSExposeHeaders: "Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, Pragma, X-Correlation-ID"
      CORSMaxAge: 3600

In the Docker configuration if the EDGEX_SERVICE_CORSCONFIGURATION_* environment variables are set on the security-proxy-setup microservice, the CORS configuration will be applied to all microservices (EDGEX_SERVICE_CORSCONFIGURATION_ENABLECORS=true). There is not a way, when using the API gateway, to turn CORS on for one microservice but not another without writing a custom security-proxy-setup microservice.