Configurator

The Configurator (Epona.Configurator.exe) is a Windows desktop tool for creating and editing service configuration files. It reads and writes .json files from the Config\ subdirectory of the service installation folder.

Launch it by double-clicking Epona.Configurator.exe, or from the command line with the parameters below.

Command-line parameters

-c, --cfg     Configuration file to load: a full path, or a bare filename resolved
              against Config\ next to the executable (e.g. epona.json). The .json
              extension is optional.
-t, --test    Test the SharePoint connection and exit. Requires -c.
-d, --decrypt Export a portable copy of the configuration specified via -c, with secrets
              converted to portable AES form, and exit. Requires -c. See "Moving a
              configuration to another server or account" below.
--target      Where to write the portable copy when using -d: 'clipboard' (default) or a
              file path.
--help        Display help and exit.
--version     Display version information and exit.

When -c is omitted the Configurator opens with an empty window and lets you select a configuration file from the UI.

Examples

Open the Configurator with a specific configuration file pre-loaded:

Epona.Configurator.exe -c config.json

Test the SharePoint connection non-interactively (useful in deployment scripts):

Epona.Configurator.exe -c config.json -t

The -c flag accepts a bare name (without extension) or a relative/absolute path:

Epona.Configurator.exe -c ClientA
Epona.Configurator.exe -c "C:\Service\Config\ClientA.json"

Export a portable copy of a configuration to the clipboard, or to a file:

Epona.Configurator.exe -c ClientA -d
Epona.Configurator.exe -c ClientA -d --target "C:\temp\ClientA-portable.json"

Exit codes

Code	Meaning	Applies to
0	SharePoint connection test succeeded, or portable copy exported successfully	-t, -d
-1	SharePoint connection test failed	-t
-2	Configuration file not found	all
-3	Current Windows user does not match the configured service account	interactive mode only
-4	Exporting the portable copy failed	-d
-5	Configuration filename was not specified	-t, -d

The Configurator verifies that the user starting it matches the account under which the provisioning Windows service is configured to run. In interactive mode (no -t/-d), a mismatch shows a confirmation dialog before any other logic runs; declining it exits with code -3. With -t/--test or -d/--decrypt, this check never blocks: a mismatch is written as a warning to the output instead, and the requested action proceeds normally.

Configuration file location

Configuration files are stored as Config\<name>.json in the service directory. The Configurator reads and writes files in that folder. Pass just the filename (without path) for -c or --target and it resolves against Config\ next to the executable, regardless of the current directory. A relative or absolute path with a directory component is used as-is.

Secrets and encryption

The configuration JSON file stores all settings, but passwords are never stored in plain text. There are two encryption modes, controlled by the ConfigVersion field in the JSON.

AES encryption (ConfigVersion 1 — default)

By default (ConfigVersion: 1), the SharePoint password and application client secret are stored directly in the JSON file, encrypted with AES using a static key. The SharePoint username is stored as plain text. AES-encrypted values can be decrypted by any instance of the provisioning service, regardless of which Windows user account runs it.

DPAPI secret store (ConfigVersion 2 — after migration)

When secrets are migrated out of the JSON (ConfigVersion: 2), the password and client secret are removed from the file and stored in a separate encrypted file alongside the configuration. That file is protected using the Windows Data Protection API (DPAPI) (opens new window) with user scope (DataProtectionScope.CurrentUser), which ties the ciphertext to the Windows user account that performed the encryption. No other account can decrypt it, even on the same machine.

The provisioning service is configured to decrypt from this store using the same user-scoped DPAPI. This means after migration, the service must run under the same Windows account that was used to save the secrets in the Configurator. If the accounts differ, the service fails to decrypt the credentials at runtime.

Migration to the secret store does not have to be done manually. When enabled, the provisioning service migrates any not-yet-migrated configuration automatically, the first time it starts as an installed Windows service (not when run interactively from a console). This is the same migration the Configurator's manual "Migrate to Secret Store" action performs, just triggered automatically under the service's own account. If a configuration file is uploaded with plain-text or portable AES-encrypted credentials, the service secures it on its first start without any Configurator step.

Automatic migration is off by default. It runs only when the autoEncryptCredentials setting in the service's Epona.ProvisioningService.exe.config is explicitly set to true:

Setting	Location	Default	Effect
autoEncryptCredentials	appSettings in the service's .exe.config	false	true migrates not-yet-migrated configurations on service start; any other value leaves them as-is

A missing key or a value that is not true/false counts as false. When migration is skipped because the setting is off, the service writes an info message to the log, so the log distinguishes "deliberately disabled" from "not working". The Configurator's manual "Migrate to Secret Store" action is unaffected by this setting and always migrates.

Setting up on a server after migration

Always run the Configurator as the service account:

1. Log in to the server as the Windows account under which the provisioning service is configured to run (or use Run as different user).
2. Open the Configurator and save the configuration including all credentials.
3. The encrypted secrets are now bound to that account and the service can decrypt them.

If you save credentials while logged in as a different account, the service will not be able to read them. The Configurator detects this situation at startup: it queries the installed service via WMI and compares its configured logon account with the current Windows user. If they differ, the Configurator shows a warning dialog (interactive mode) or writes a warning to the output and continues (non-interactive -t/-d mode).

When the service runs as LocalSystem

If the provisioning service is configured to run as the Local System account, the steps above don't apply: LocalSystem has no password, so there is no way to log in as it or use Run as different user. To export a portable copy of a configuration whose secrets are protected under LocalSystem, run the Configurator's export directly under the LocalSystem identity using PsExec (opens new window), a free tool from Microsoft's Sysinternals suite:

PsExec.exe -s Epona.Configurator.exe -c ClientA -d --target "C:\temp\ClientA-portable.json"

• -s runs the Configurator under the LocalSystem account — the same identity the service uses to protect its secrets — so it can decrypt them.
• Epona.Configurator.exe -c ClientA -d --target ... is the normal export command; see Command-line parameters above.

Running PsExec with -s requires local administrator rights on the server — the same level of access already needed to install or reconfigure the provisioning service itself.

Moving a configuration to another server or account

Because a ConfigVersion: 2 secret store is bound to one Windows account on one machine, a configuration that has already been migrated cannot simply be copied elsewhere — the destination cannot decrypt it. To move a configuration to a different server or hand it off to a different user, export a portable copy first:

• In the Configurator UI, open the configuration and click Export Portable Copy on the toolbar. A save dialog appears; choose a file to write the portable copy there, or cancel the dialog to copy it to the clipboard instead.
• From the command line, use -d/--decrypt (see Command-line parameters above).

Either way, the exported copy has every credential re-encrypted with the portable AES method and ConfigVersion reset to 1, regardless of whether the source configuration was still in the JSON (ConfigVersion: 1) or already migrated to the secret store (ConfigVersion: 2). Save the exported JSON as a .json file in the destination's Config\ folder. No manual decryption step is needed there: the destination's own provisioning service migrates it to its own secret store automatically on first start, as described above.