Merge pull request #9959 from Robinfr/feature/enhance-csp-documentation

Enhance CSP documentation

Author: OlufunkeMoronfolu

content/en/docs/deployment/mendix-cloud-deploy/environments-details.md

@@ -321,7 +321,11 @@ document.cookie = "originURI=/login.html" + (window.location.protocol === "https
 
 #### Content Security Policy {#csp}
 
-A Content Security Policy informs the client (browser) where your page loads resources from. Setting this can make your app more secure by declaring trusted sources for your resources. For more information, see the W3C recommendation [Content Security Policy Level 2](https://www.w3.org/TR/CSP2/).
+A Content Security Policy (CSP) informs the client (browser) where your page loads resources from. Setting this can make your app more secure by declaring trusted sources for your resources. For more information, see the W3C recommendation [Content Security Policy Level 2](https://www.w3.org/TR/CSP2/).
+
+{{% alert color="info" %}}
+For complete CSP support, including nonce-based CSP, use the [Headers](/refguide/configuration/#headers) custom runtime setting instead of the HTTP Headers UI. For detailed implementation instructions, see [Content Security Policy](/howto/security/csp/).
+{{% /alert %}}
 
 The process for setting a full content security policy depends on what your app does. However, a starting point that declares the content security policy that works with a basic Mendix app is given below:
 

content/en/docs/howto/security/csp.md

@@ -174,6 +174,168 @@ After redeploying your app locally, it should function as normal. If your app do
 
 After you finish testing locally, remember to remove the line of code in the `head` tag.
 
-### Enabling the Header in the Cloud
+## CSP Support in Java Request Handlers
 
-To enable the header in the cloud, follow the instructions in the [HTTP Headers](/developerportal/deploy/environments-details/#http-headers) section of *Environment Details*.
+When developing Marketplace modules or custom Java actions that include request handlers, you may need to implement CSP support to ensure compatibility with strict CSP policies. This includes support for CSP Level 2+ features such as nonces for inline scripts and styles. 
+
+{{% alert color="info" %}}
+CSP support is only relevant for request handlers that serve static content such as HTML pages, not for API endpoints that return JSON or other data formats.
+{{% /alert %}}
+
+This section describes how to properly handle CSP headers in Java request handlers when serving HTML content.
+
+### Available CSP APIs
+
+Mendix provides two APIs to support CSP in Java request handlers:
+
+#### IMxRuntimeResponse Methods
+
+The `IMxRuntimeResponse` interface provides these basic CSP methods:
+
+* `addContentSecurityPolicyHeader()` – Adds the Content-Security-Policy header as configured in the application
+* `getNonce()` – Returns a secure, uniquely generated nonce for the response that you can use in CSP directives
+* `addHeader(String key, String value)` – Adds a custom header to the response
+
+#### CspHelper Interface (Recommended)
+
+The `CspHelper` interface provides additional utility methods for more advanced CSP handling:
+
+* `getTemplate()` – Gets the template used for the Content-Security-Policy header value
+* `getNonce(IMxRuntimeResponse response)` – Gets the generated nonce of the current HTTP response
+* `hasNonce(IMxRuntimeResponse response)` – Returns true if the configured CSP template contains the `{{ NONCE }}` placeholder. For example: `Content-Security-Policy: script-src 'nonce-{{ NONCE }}'`
+* `addHeader(IMxRuntimeResponse response)` – Adds Content-Security-Policy header to the response using the configured template
+
+### Example Implementation
+
+Here's how to implement CSP support in a Java request handler using the `CspHelper` interface:
+
+```java
+package your.module.requesthandlers;
+
+import com.mendix.externalinterface.connector.RequestHandler;
+import com.mendix.m2ee.api.IMxRuntimeRequest;
+import com.mendix.m2ee.api.IMxRuntimeResponse;
+import com.mendix.http.CspHelper;
+import com.mendix.core.Core;
+
+public class YourRequestHandler extends RequestHandler {
+    
+    @Override
+    protected void processRequest(IMxRuntimeRequest request, IMxRuntimeResponse response, String path) throws Exception {
+        try {
+            // Add the configured CSP header from the application
+            Core.csp().addHeader(response);
+            
+            // Set response content type
+            response.setContentType("text/html");
+            
+            // Generate your response content with conditional nonce support
+            String htmlContent = generateHtmlWithCSP(response);
+            
+            // Write the response
+            response.getWriter().write(htmlContent);
+            
+        } catch (Exception e) {
+            logger.error("Error processing request: " + e.getMessage(), e);
+            response.setStatus(IMxRuntimeResponse.INTERNAL_SERVER_ERROR);
+            response.sendError("Internal server error");
+        }
+    }
+    
+    private String generateHtmlWithCSP(IMxRuntimeResponse response) {
+        StringBuilder html = new StringBuilder();
+        html.append("<!DOCTYPE html>\n");
+        html.append("<html>\n");
+        html.append("<head>\n");
+        html.append("<title>Your Module</title>\n");
+        
+        // Only use nonce if it's configured in the CSP template
+        if (Core.csp().hasNonce(response)) {
+            String nonce = Core.csp().getNonce(response);
+            html.append("<script nonce=\"").append(nonce).append("\">\n");
+            html.append("// Your inline JavaScript here\n");
+            html.append("console.log('This script is CSP-compliant with nonce');\n");
+            html.append("</script>\n");
+        } else {
+            // Alternative approach when nonce is not configured
+            html.append("<script src=\"/path/to/external/script.js\"></script>\n");
+        }
+        
+        html.append("</head>\n");
+        html.append("<body>\n");
+        html.append("<h1>Your Module Content</h1>\n");
+        html.append("<!-- Your content here -->\n");
+        html.append("</body>\n");
+        html.append("</html>\n");
+        
+        return html.toString();
+    }
+}
+```
+
+### Best Practices for CSP in Request Handlers
+
+When implementing CSP support in your request handlers, follow these best practices:
+
+* **Use `CspHelper` for conditional nonce support** – Always check if nonce is configured before using it:
+
+   ```java
+   if (Core.csp().hasNonce(response)) {
+    String nonce = Core.csp().getNonce(response);
+    // Use nonce for inline content
+   } else {
+    // Use external resources or alternative approach
+   }
+   ```
+
+* **Always add CSP headers** – Use `Core.csp().addHeader(response)` to ensure your module respects the application's CSP configuration when serving HTML content.
+
+* **CSP is only needed for HTML content** – Only implement CSP support in request handlers that serve HTML pages. API endpoints returning JSON, XML, or other data formats do not need CSP headers.
+
+* **Avoid inline scripts and styles when possible** – Use external files that can be loaded via `'self'` directive.
+
+* **Test with strict CSP** – Test your request handlers with `default-src: 'self'` to ensure they work with the strictest CSP settings.
+
+### Common CSP Issues in Request Handlers
+
+When working with CSP in request handlers, you may encounter these common issues:
+
+#### Base64 Images
+
+Strict CSP blocks inline Base64 images that your request handler generates. Consider these alternatives:
+
+* Serve images as separate endpoints
+* Use external image hosting
+* Add `data:` to `img-src` directive (less secure)
+
+#### Dynamic Script Generation
+
+Avoid generating `<script>` tags dynamically without nonces. Instead:
+
+* Use the provided nonce for any inline scripts
+* Move logic to external JavaScript files
+* Use data attributes and external scripts to handle dynamic behavior
+
+#### Third-party Resources
+
+If your module loads external resources, make sure they are allowed by the CSP or provide configuration options for developers to whitelist them.
+
+#### Error Handling
+
+When CSP violations occur, implement proper error handling:
+
+```java
+// Log CSP-related errors for debugging
+if (Core.csp().hasNonce(response)) {
+    logger.debug("Using CSP with nonce: " + Core.csp().getNonce(response));
+} else {
+    logger.debug("CSP configured without nonce support");
+}
+```
+
+## Enabling the Header in the Cloud
+
+There are two ways to enable the header in the cloud:
+
+1. **[Headers](/refguide/configuration/#headers) custom runtime setting (Recommended)**: Use this if you need nonce-based CSP support. Configure this in the Developer Portal under [Custom Runtime Settings](/developerportal/deploy/environments-details/#custom-runtime-settings).
+2. **HTTP Headers UI:** This method works for basic CSP support. For more details, refer to the [HTTP Headers](/developerportal/deploy/environments-details/#http-headers) section of *Environment Details*.

content/en/docs/refguide/runtime/custom-settings/_index.md

@@ -72,6 +72,7 @@ The following custom settings can be configured:
 | <a id="ScheduledEventExecution" href="#ScheduledEventExecution">ScheduledEventExecution</a> | Specify which scheduled events should be executed. Choices are `ALL`, `NONE`, or `SPECIFIED`. In the case of `SPECIFIED`, enumerate the scheduled events using the `MyScheduledEvents` configuration option described below. {{% alert color="warning" %}}This setting cannot be configured when running locally. To enable and disable scheduled events when running locally, please use the 'Enabled' setting on the [Scheduled Events execution properties](/refguide/scheduled-events/) in Studio Pro.{{% /alert %}} | NONE |
 | <a id="SessionKeepAliveUpdatesInterval" href="#SessionKeepAliveUpdatesInterval">SessionKeepAliveUpdatesInterval</a> | Defines how often a runtime writes session LastActive dates in its memory back to the database. | one sixth of the value configured for the `SessionTimeout` setting; if the `SessionTimeout` is not set, this value defaults to 100000 (100 seconds) |
 | <a id="SessionTimeout" href="#SessionTimeout">SessionTimeout</a> | Defines after how much time a session becomes invalid (in milliseconds). After that timeout,  a session becomes eligible for removal. The session will not be destroyed until the next time a scheduled task runs to clean up the active sessions. <br> {{% alert color="warning" %}} Logging out can also be triggered by a query to the runtime after the session becomes eligible for removal. Navigating between pages is not enough to trigger a query to the runtime. To force a query to the runtime, use microflows. For example, create a microflow that shows the Home page, then configure your app's navigation to call this microflow rather than relying on the navigation to directly show the page itself. This will ensure the runtime is queried and the user is logged out of their session. {{% /alert %}} | 600000 (10 minutes) |
+| <a id="Headers" href="#Headers">Headers</a> | A JSON object containing custom headers as key/value pairs, and can be used to define a `Content-Security-Policy`. For example, `{ "Content-Security-Policy": "script-src 'nonce-{{ NONCE }}'" }`. | `{}` |
 | <a id="TaskQueueShutdownGracePeriod" href="#TaskQueueShutdownGracePeriod">TaskQueue.<wbr>ShutdownGracePeriod</a> | Time in ms to wait for task in a task queue to finish when shutting down. | 10000 (10 seconds) |
 | <a id="TempPath" href="#TempPath">TempPath</a> | The location of the temporary files. | [deployment folder]\data\tmp |
 | <a id="TrackWebServiceUserLastLogin" href="#TrackWebServiceUserLastLogin">TrackWebServiceUserLastLogin</a> | Defines whether to update a user's `LastLogin` field on each login when logging in to a published REST, OData, or web service. When this happens a database update query has to be sent and this can have performance consequences on heavy load systems. When this setting is set to false, no database interaction is necessary. | true |