# 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 filename to load. The .json extension is optional.
-t, --test Test the SharePoint connection and exit. Requires -c.
--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"
# Exit codes
The exit codes are only meaningful when running with --test (-t).
| Code | Meaning |
|---|---|
0 | SharePoint connection test succeeded |
-1 | SharePoint connection test failed |
-2 | Configuration file not found |
-3 | Current Windows user does not match the configured service account |
The service account check (-3) runs before any other logic: the Configurator verifies that the user starting it matches the account under which the provisioning Windows service is configured to run. If they differ, the Configurator exits immediately.
# 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) when running from the service directory.
# 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.
# Setting up on a server after migration
Always run the Configurator as the service account:
- Log in to the server as the Windows account under which the provisioning service is configured to run (or use
Run as different user). - Open the Configurator and save the configuration including all credentials.
- 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 exits with code -3 (non-interactive --test mode).