How to configure digiRunner to support CORS in a frontend-backend separated architecture?

[Eddie-Las]

Hi team,

I'm currently integrating digiRunner into a frontend-backend separated architecture. The frontend (e.g., running locally on localhost or 127.0.0.1) and the digiRunner API Gateway are deployed on different domains.

As expected, I'm running into CORS (Cross-Origin Resource Sharing) issues with the browser.

When inspecting the response headers from digiRunner running in Docker, I see the following:

Access-Control-Allow-Headers: YYY, Content-Type, Authorization, SignCode, Language, XXX

I have a few questions:

• What do XXX and YYY mean?

• How can I configure digiRunner to support cross-domain frontend applications properly?

• Is there any configuration file I can refer to?

My goal is to allow the frontend browser to call the digiRunner Gateway directly while handling CORS correctly. I appreciate any advice or guidance!

[joshtpi]

XXX and YYY are just placeholders that you can swap out. The four headers in the middle—Content‑Type, Authorization, SignCode, and Language—are mandatory and must not be changed, so we use clear placeholders to indicate the ones you’re free to adjust. You can modify XXX and YYY according to your needs.

[TPIsoftwareOSPO]

Hi @Eddie-Las ,
Great questions! This is a very common scenario when working with frontend-backend separated systems.
You're right — whether CORS is required depends on whether the frontend and API share the same domain. In your case, they don't, so CORS handling is necessary.
While using a reverse proxy to unify domains is ideal, we understand that this isn’t always possible due to real-world network or security constraints. So proper CORS setup is essential.
Here’s a quick SOP (standard operating procedure) to guide you:
✅ For “simple” requests:
If the frontend sends basic GET, POST, or HEAD requests, the backend should include this in the response:
Access-Control-Allow-Origin: <frontend_origin>
✅ For “non-simple” requests:
When requests involve custom headers or methods like PUT or DELETE, the browser sends a preflight OPTIONS request first. Your backend must respond to it with:
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, ...
Access-Control-Allow-Headers: <your_custom_headers>
You must still return Access-Control-Allow-Origin in the actual API response.
✅ For requests with cookies:
Frontend requests must include credentials: 'include', and the backend should respond with:
Access-Control-Allow-Credentials: true
In this case, Access-Control-Allow-Origin cannot use *.

[Eddie-Las]

Thanks team, this is very helpful!
To follow up:

• How do I configure digiRunner to apply these headers?
• Specifically, how do I set:
  • Access-Control-Allow-Methods
  • Access-Control-Allow-Credentials
  • And how do I modify the XXX and YYY values in the Access-Control-Allow-Headers?

It seems there’s no UI in digiRunner to manage advanced CORS settings — am I missing something?

[TPI-JohnChen]

Thank you for the feedback! You're absolutely right that digiRunner currently doesn't provide a UI interface for advanced CORS settings. We have already included this feature in our development roadmap and plan to provide a complete CORS management interface in future versions. You'll then be able to configure these advanced parameters directly through the UI.

[TPIsoftwareOSPO]

@Eddie-Las Great follow-up, and thanks again for raising this important question!
Although digiRunner does not currently provide a UI interface for configuring CORS, if you need to apply settings urgently, here’s how you can do it manually:

🔍 What are XXX and YYY?
They're placeholders — markers in the default CORS header config to indicate that you can insert your own custom headers.

The four headers in the middle —
Content-Type, Authorization, SignCode, and Language
— are required for digiRunner to function and should not be removed.

You can update the actual list of allowed headers in:

config/application.properties

Look for this property:
cors.allow.headers=YYY,Content-Type,Authorization,SignCode,Language,XXX

Let’s say your frontend uses a custom header like X-Custom-Header.
You would change the property to:
cors.allow.headers=X-Custom-Header,Content-Type,Authorization,SignCode,Languagee

⚙️ What about other CORS headers like Allow-Credentials?
digiRunner does not block CORS headers from the backend API responses. So you can configure headers like:
• Access-Control-Allow-Credentials : true
• Access-Control-Allow-Methods : GET, POST, PUT, DELETE
• Access-Control-Allow-Origin : <origin>
• Any other custom headers like X-App-Version, Test-Dgr, etc.
…directly in your backend API responses, and digiRunner will pass them through to the browser — even for preflight OPTIONS requests.

[Eddie-Las]

Thanks again, team— this was exactly what I needed!
To summarize for others:
• digiRunner fully supports cross-domain CORS setups.
• You can modify allowed headers in config/application.properties via the cors.allow.headers property. Be sure to retain the 4 required ones.
• Other headers like Access-Control-Allow-Credentials can be configured in the backend API. digiRunner will forward them correctly.
• Make sure you're using digiRunner v4.0.49 or newer.
Appreciate your help in resolving this!

[TPIsoftwareOSPO]

📌 Additional Note
Thanks to @Eddie-Las for the excellent summary above. I’d like to add a few practical reminders for configuring CORS in digiRunner:
After logging into the digiRunner Admin Console, navigate to System Config > Setting. There you’ll find three CORS-related system parameters. These can be customized to suit your environment:

🔹 DGR_CSP_VAL
Controls the Content-Security-Policy (CSP) header. Default value is *, but it’s highly recommended to specify trusted sources:
Example: https://127.0.0.1:1920 https://27.0.0.1:2920
Use spaces to separate multiple domains.

🔹 DGR_CORS_VAL
Controls the default value for CORS Access-Control-Allow-Origin. Default is *, but it can be updated:
Example: https://dgRv4.io

🔹 DGR_HOST_HEADER
Checks the Host header to prevent host header injection attacks. The default is *. You should define accepted hostnames:
Example: 127.0.0.1:1920,127.0.0.1:2920
Use commas to separate multiple values.

⚠️ Security Reminder: These settings play a critical role in defending against CSRF, host injection, and XSS attacks. For an in-depth explanation and best practices, refer to the following resources:
• https://hackmd.io/@PlxyJDuRSLKQ8WkiZzngmg/SJXUoVefeg
• https://hackmd.io/@PlxyJDuRSLKQ8WkiZzngmg/SyaNku41ex#