declarativeNetRequest API, which allows you to modify request headers based on precise domain rules while maintaining the stability required for kiosk environments.
Understanding the Technical Constraints
Chromium-based browsers, including Edge and Chrome, lack native command-line switches like--header or --additional-headers that allow users to inject custom HTTP headers dynamically based on the target URL. While older versions of Chrome supported experimental flags, these were removed due to security concerns and instability. Consequently, attempting to use generic CLI arguments will fail silently or cause the browser to ignore the settings entirely.
Furthermore, Manifest V2 permissions such as webRequest with blocking are deprecated and restricted in modern kiosk modes. Attempting to use Mv2 approaches often results in extensions being disabled by the system policy or failing to load during startup. Therefore, the solution must rely on the current standard: Manifest V3 and the declarative networking APIs. This approach ensures compatibility with both Edge and Chrome updates and adheres to the strict security policies enforced on authenticated enterprise devices.
Creating the Extension Manifest
To implement this solution, you need to create a simple browser extension. Start by creating a new folder for your project, such askiosk-headers. Inside this folder, create a file named manifest.json. This file defines the extension's behavior and permissions. You must specify version 3 of the manifest format to ensure it works with modern Chromium engines.
The following JSON structure outlines the necessary configuration. Note the use of declarative_net_request instead of legacy web request handlers. This permission set is minimal and sufficient for modifying headers without requiring broad access to all website data.
{
"manifest_version": 3,
"name": "Kiosk Domain Headers",
"version": "1.0",
"description": "Adds custom headers for specific domains in Kiosk Mode",
"permissions": [
"declarativeNetRequest"
],
"host_permissions": [
"https://example.com/*"
],
"declarative_net_request": {
"rule_resources": [
{
"id": "ruleset_1",
"enabled": true,
"path": "rules.json"
}
]
}
}host_permissions array, replace https://example.com/* with the actual domain you need to target. This ensures the extension only activates when the user navigates to the specified site, preserving performance and privacy for other pages.
Defining the Header Rules
Next, create a file namedrules.json in the same directory. This file contains the logic for modifying requests. The declarativeNetRequest API uses a rule-based system where each rule specifies conditions and actions. To add a header, you define an action type of MODIFY_HEADERS and include the header name and value in the requestHeaders array.
Here is an example rule that adds an authentication token header for the target domain:
[
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [
{
"header": "X-Custom-Auth-Token",
"operation": "set",
"value": "secret-token-value-123"
}
]
},
"condition": {
"urlFilter": "https://example.com/",
"resourceTypes": ["main_frame"]
}
}
]urlFilter property matches the domain. You can use wildcards if needed, but exact matching is safer for kiosk applications. The resourceTypes field limits the rule to main page loads, preventing unnecessary processing of images or scripts. If you need to add multiple headers, simply add more objects to the requestHeaders array within the same action object.
Loading the Extension in Kiosk Mode
Once the files are prepared, you must load the extension into the browser. For development, you can navigate tochrome://extensions (or edge://extensions) in the browser, enable Developer Mode, and click "Load unpacked." Select your folder to verify that the headers are being added correctly using the Network tab in DevTools.
For production deployment on authenticated machines, you should package the extension or use the command line to load it directly. When launching Edge or Chrome in Kiosk mode, append the path to your extension folder using the --disable-features flag if necessary, but primarily use the --load-extension argument.
msedge.exe --kiosk https://your-target-url.com --load-extension="C:\path\to\kiosk-headers"Maintaining and Debugging
If headers are not appearing, first check the extension status in the extensions page. Ensure there are no error messages indicating permission conflicts. Verify that theurlFilter in rules.json exactly matches the protocol and domain of the target page. A common mistake is forgetting to include https:// in the filter or mismatching subdomains.
You can also test the extension by navigating to about:blank and opening the console to inspect network requests, although direct inspection of modified headers is best done via the browser's developer tools network log. Since Kiosk mode often restricts access to DevTools, consider deploying a temporary non-kiosk instance for debugging purposes.
For more information on managing multiple displays and profiles in Kiosk mode, see Using Multiple Secondary Displays with Chrome/Edge Kiosk Mode and Separate Profiles. Additionally, understanding how default browser behaviors affect OAuth flows can help troubleshoot authentication issues that may arise alongside custom headers, as detailed in Changing Default Browser Used by SourceTree for OAuth.
Frequently Asked Questions
Can I use command-line flags to add headers?
No, Chromium-based browsers do not support command-line flags for adding custom HTTP headers. Any attempt to use flags like --header will be ignored. You must use an extension.
Does this work with Manifest V2?
Manifest V2 is deprecated and blocked in many enterprise environments. Use Manifest V3 with declarativeNetRequest to ensure your extension loads correctly in modern Edge and Chrome versions.
How do I handle dynamic tokens?
The declarativeNetRequest API does not support dynamic values generated at runtime. If you need dynamic tokens, you must use a background service worker with the fetch API or proxy the request through a local server.
Will this extension slow down the browser?
No, declarative rules are processed efficiently by the browser engine. They have negligible impact on performance compared to older webRequest listeners, making them suitable for always-on kiosk devices.
Can I add headers to all domains?
You can configure a rule with a wildcard urlFilter like *://*/*, but this is discouraged for security reasons. It is better to target specific domains to avoid interfering with third-party scripts or sensitive data.