Policy: Create a File Redirect
Audience: System administrators
This guide explains how to configure a redirect so that when a user is allowed to elevate a specific application (e.g. PowerShell 7 pwsh.exe), the product launches a substitute executable (e.g. Windows PowerShell 5.1) instead. You will set up a Privilege Elevation policy, a SettingsUpdate policy to push redirect rules, and optionally an UpdateSettings policy to reload settings without restarting the service. Settings can be reloaded only via UpdateSettings policy, restarting the KEPM service, or restarting the machine—not from terminal or scripts, because KEPM admin endpoints require the calling process to be signed like KEPM.
What is a Redirect?
When a privilege elevation request is allowed by policy, the product normally launches the requested executable with elevation. A redirect lets you substitute a different executable so the user gets the intended experience (e.g. a supported PowerShell version) while policy stays in control.
Flow: User requests elevation for Application A → policy allows it → product runs the check-redirect logic → if a rule matches, the product does not launch A and instead launches Target B elevated (e.g. Windows PowerShell instead of PowerShell 7).
Redirect applies only to Privilege Elevation events (not File Access or other event types).
Redirect rules are stored in the RedirectEvaluator plugin configuration (
metadata.redirect).
Redirect Requirements
LaunchPrivilegeElevation job
Must be deployed and registered. It contains the check-redirect task that calls RedirectEvaluator.
RedirectEvaluator plugin
Plugin config must have metadata.redirect.enabled: true and at least one rule in metadata.redirect.rules.
Privilege Elevation policy
A policy that allows (or allows with controls) the source application (e.g. pwsh.exe). Without this, the request may be denied and the LaunchPrivilegeElevation job never runs.
SettingsUpdate policy
Pushes the full RedirectEvaluator JSON (including redirect rules) to endpoints so Plugins/RedirectEvaluator.json is updated.
Process Configuration Policies job
Runs the ConfigurationPolicyProcessor, which writes SettingsUpdate policy content to plugin files.
Reload of plugin settings
After the JSON file is updated, the service must use the new config. The only ways to reload are: UpdateSettings policy (triggers revert-all when policies are preprocessed), restart KEPM service, or restart the machine. KEPM admin endpoints cannot be called from terminal, PowerShell, or similar tools—the calling process must be signed with the same signature as KEPM.
UpdateSettings policy (optional)
When present and preprocessed, triggers revert-all so settings are reloaded without restarting the service.
Rule Formatting
Rules live under metadata.redirect.rules in the RedirectEvaluator plugin JSON.
sourceExePattern
Yes
Regex matched against the executable file name only (e.g. pwsh\.exe, rundll32\.exe). Case-insensitive. Use \\. for a literal dot.
commandLinePattern
Yes
Regex matched against the full command line. Case-insensitive. Cannot be empty—use .* to match any command line.
elevationOnly
Yes
Set true for redirects (rule applies only to Privilege Elevation).
nonAdminOnly
No
If true, rule applies only when the requesting user is not an administrator.
targetExe
Yes
Substitute executable: full path (e.g. C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe) or a product-known name (e.g. Keeper.NetworkConnections) resolved from Jobs/bin or Plugins/bin.
targetArguments
No
Arguments for the substitute (often "").
Important: Both sourceExePattern and commandLinePattern must be non-empty. To redirect regardless of command line, use ".*" for commandLinePattern.
Example rule: redirect pwsh.exe to Windows PowerShell 5.1
Order Matters: the first matching rule is used. Precise rules should precede general rules.
Privilege Elevation policy
You need a policy that allows the application you want to redirect (e.g. pwsh.exe). If the request is denied, the LaunchPrivilegeElevation job is not triggered and redirect never runs.
Create a Privilege Elevation policy in your management console or policy store.
Set PolicyType to
"PrivilegeElevation".Set Status to
"enabled".Configure ApplicationCheck (or equivalent) so it matches the source executable path or pattern (e.g. path containing
PowerShell\7\pwsh.exeor a pattern your product supports).Set Controls to allow elevation (e.g.
["ALLOW"]or include MFA/Justify/Approval as needed).Assign the policy to the right users and machines (collections).
Deploy/sync so the policy is on the endpoints.
Example (conceptual):
Adjust Filters and ApplicationCheck to match your product's schema (e.g. full paths, patterns, or collection-based application lists).
SettingsUpdate Policy (Redirect Rules)
This policy pushes the full RedirectEvaluator plugin JSON (including metadata.redirect) to Plugins/RedirectEvaluator.json on each endpoint.
Build the full RedirectEvaluator JSON you want:
Include all required plugin fields:
id,name,description,version,pluginType,executablePath,Subscription,metadata, etc. (copy from an existingPlugins/RedirectEvaluator.jsonif needed.)Set metadata.redirect.enabled to
true.Set metadata.redirect.rules to an array containing your rule(s) (e.g. the pwsh → Windows PowerShell rule above).
Create a SettingsUpdate policy with:
PolicyType:
"SettingsUpdate".Status:
"enabled"(or"enforce"per your console).Extension.PluginName:
"RedirectEvaluator".Extension.Action:
"Update"(optional; default).Extension.SettingsJson: The entire RedirectEvaluator plugin JSON. You can supply it either as a string (escape inner quotes and backslashes) or as an object (nested JSON). Using an object is supported and easier to read; the configuration processor accepts both.
Assign the policy to the same (or appropriate) machine/user collections and deploy/sync.
Example policy (management-console style with SettingsJson as object):
The following shows a real SettingsUpdate policy as created in the management console. Extension.SettingsJson is an object containing the full RedirectEvaluator plugin JSON (no need to serialize to a string). The policy may also include Actions, Rules, UserCheck, MachineCheck, ApplicationCheck, and other fields depending on your console.
Note: SettingsJson must be the full plugin JSON (all required fields such as id, name, executablePath, Subscription, metadata). Using an object keeps the policy readable and avoids escaping errors.
Run Process Configuration Policies
The Process Configuration Policies job (ConfigurationPolicyProcessor) reads policy templates, finds SettingsUpdate policies, and writes Extension.SettingsJson to the file indicated by PluginName (e.g. Plugins/RedirectEvaluator.json).
Schedule: If the job is scheduled, it will run automatically; after sync, the next run will apply your SettingsUpdate policy.
On demand: Use the KeeperClient "Refresh" option. This triggers policy sync and preprocessing; the Process Configuration Policies job runs when applicable. You cannot run this job by calling KEPM endpoints from terminal or PowerShell—the calling process must be signed with the same signature as KEPM.
After this step, Plugins/RedirectEvaluator.json on the endpoint contains your redirect rules. The running service may still be using the old in-memory config until you reload (Step 4).
Reload Plugin Settings
After the plugin JSON file is updated, the service must load the new settings. The only ways to reload are:
UpdateSettings policy — When policies are preprocessed (e.g. after KeeperClient Refresh or sync), an UpdateSettings policy triggers revert-all so plugin settings are re-imported from the current in-memory configuration into storage. See Step 5.
Restart KEPM service — Stops and starts the service; on startup, plugin config is read from disk. This always picks up the new file (and avoids config-protection/tampering issues that can block hot reload).
Restart the machine — Same effect as restarting KEPM for loading plugin config.
You cannot trigger a reload from terminal, PowerShell, curl, or other unsigned tools—KEPM admin endpoints require the calling process to be signed like KEPM.
Optional: UpdateSettings Policy for Reload without Restart
To trigger a reload of all plugin settings (same effect as POST /api/PluginSettings/revert-all) without restarting the service, use an UpdateSettings policy.
Create a policy with PolicyType
"UpdateSettings"and Status"enabled".Assign it to the same (or appropriate) machine/user collections and deploy/sync.
When KeeperPolicy preprocesses policies (e.g. after sync or GetPolicyData), it looks for UpdateSettings and calls the revert-all endpoint once. Plugin settings are then re-imported from the current in-memory configuration into storage.
Note: UpdateSettings does not re-read the plugin JSON files from disk; it re-imports from whatever is already in the configuration provider. So for the first time you push a new RedirectEvaluator.json via SettingsUpdate, a restart is the most reliable way to load it. Use UpdateSettings for subsequent reloads when the config is already loaded (e.g. after a previous restart or when the file watcher successfully reloaded the file).
Calling KEPM Endpoints from Terminal or Scripts
KEPM admin endpoints (including POST /api/PluginSettings/revert-all and POST /api/PluginSettings/{pluginName}/revert) use process authentication: the calling process must be signed with the same signature as KEPM and must pass validation (e.g. launched by or trusted like KeeperPrivilegeManager). Terminal, PowerShell, cmd, curl, and similar tools are not signed and will receive 403 when calling these endpoints. There is therefore no way to trigger a settings reload from a script or terminal—only UpdateSettings policy, restart KEPM service, or restart the machine.
Limitations
Privilege Elevation only
Redirect is evaluated only for Privilege Elevation events. File Access and other event types do not run the redirect logic.
Both patterns required
sourceExePattern and commandLinePattern must both be non-empty. To match any command line, use ".*".
Policy must allow first
The elevation request must be allowed by a Privilege Elevation policy. If the request is denied, LaunchPrivilegeElevation is not triggered and redirect is never evaluated.
Config file tampering protection
If the product detects that Plugins/RedirectEvaluator.json was modified after initial load (tampering protection), it may skip loading that file on hot reload. In that case, the only way to apply the new rules is to restart the KEPM service (so the file is read at startup with no previous hash). Pushing settings via the management console into Unified Storage (e.g. PUT /api/PluginSettings/RedirectEvaluator/metadata) can provide new rules without relying on the on-disk file.
Target executable
targetExe must be a path or a product-known name that resolves to a path under Jobs/bin or Plugins/bin. The substitute must exist and be launchable on the endpoint.
First matching rule
Only the first rule that matches (by exe name, command line, event type, and optionally nonAdminOnly) is used. Order rules from most specific to least specific.
Revert vs. disk
POST revert-all and POST …/revert re-import from the current in-memory plugin configuration into Unified Storage. They do not re-read the JSON files from disk. If the on-disk file was updated but not loaded (e.g. tampering), restart is required to use the new file.
UpdateSettings policy
The UpdateSettings policy type triggers revert-all when preprocessing runs; it does not re-read plugin JSON from disk. Use it to reload already-loaded config without restart, not to load a never-before-loaded file.
No API from terminal/scripts
Admin endpoints (revert-all, revert, job run, etc.) require the calling process to be signed like KEPM. Terminal, PowerShell, and curl cannot call them.
Related documentation
Reference: Redirect — Redirect capability and rule fields.
Example: Creating a Policy to set Settings — SettingsUpdate policy and Process Configuration Policies job.
Reference: Plugin & Task Settings — Plugin settings API, revert-all, and revert.
Last updated
Was this helpful?