Configuring CORS for Cross-Domain Applications in digiRunner

Q: How do I configure CORS to allow my frontend application to call the digiRunner Gateway from a different domain?

(Keywords: CORS, Cross-Origin Resource Sharing, Frontend Integration, API Gateway, Access-Control-Allow-Origin, Preflight OPTIONS)

A: Integrating a frontend-backend separated architecture often requires handling Cross-Origin Resource Sharing (CORS) issues. digiRunner fully supports cross-domain requests. You can configure this by adjusting specific property files and ensuring your backend API sends the correct headers.

1. Modifying Allowed Headers

digiRunner includes a default set of allowed headers. To support custom headers from your frontend, you must edit the config/application.properties file.

• Locate the property: cors.allow.headers.

• Default Configuration: YYY,Content-Type,Authorization,SignCode,Language,XXX.

  • Note: The headers Content-Type, Authorization, SignCode, and Language are mandatory for digiRunner and must not be removed.

  • XXX and YYY are placeholders where you can inject your custom headers.

• Example: If your app uses X-Custom-Header, update the property to:

cors.allow.headers=X-Custom-Header,Content-Type,Authorization,SignCode,Language.

• Version Requirement: This configuration is supported in digiRunner v4.0.49 and above.

2. Handling Standard CORS Headers (Methods, Credentials, Origin)

digiRunner acts as a passthrough for CORS headers sent by your backend API. You do not need to configure these inside digiRunner's UI; instead, ensure your backend API returns them directly in its response. digiRunner will forward these headers to the browser, even for preflight OPTIONS requests.

• Access-Control-Allow-Methods: Set this in your backend API (e.g., GET, POST, PUT, DELETE).

• Access-Control-Allow-Credentials: If your frontend sends cookies (credentials: 'include'), your backend must return true.

• Access-Control-Allow-Origin: Your backend should specify the allowed origin.

  • Important: If Allow-Credentials is true, you cannot use the wildcard * for the Origin header.

3. Security Best Practices & System Parameters

For enhanced security against CSRF, XSS, and Host Injection attacks, you can fine-tune CORS behavior via the Admin Console under System Config > Setting:

• DGR_CORS_VAL: Sets the default Access-Control-Allow-Origin value. (Default: *) .

  • Recommendation: Set to your specific domain, e.g., https://dgRv4.io.

• DGR_CSP_VAL: Controls the Content-Security-Policy header. (Default: *) .

  • Recommendation: explicitly list trusted sources, separated by spaces (e.g., https://127.0.0.1:1920 https://27.0.0.1:2920).

• DGR_HOST_HEADER: Validates the Host header to prevent injection attacks. (Default: *) .

  • Recommendation: Define a comma-separated list of accepted hostnames (e.g., 127.0.0.1:1920,127.0.0.1:2920).