You can keep connection strings, mail credentials, and other sensitive MDrivenServer or Turnkey configuration values outside configuration files by storing them in environment variables and referring to them with %VariableName%; this is for administrators deploying Turnkey and MDrivenServer.

How environment-variable substitution works

Set a secret value in an environment variable that is available to the application. In the relevant MDriven configuration value, enter the environment-variable name surrounded by percent signs.

For example, if the application environment contains:

MDRIVEN_EMAIL_PASSWORD=the-secret-password

configure the corresponding MDriven value as:

%MDRIVEN_EMAIL_PASSWORD%

When MDriven reads that configuration value, it resolves %MDRIVEN_EMAIL_PASSWORD% to the value of the MDRIVEN_EMAIL_PASSWORD environment variable. The configuration file or MDrivenServer administration database therefore stores the reference rather than the secret.

Important: Use the exact environment-variable name between the percent signs. Do not put the secret itself in the XML file or in the MDrivenServer UI.

Supported configuration locations

Environment-variable substitution is supported in the following locations.

Location	Supported values	Example use
TurnkeySettings.xml and its overrides	All values	Put %MDRIVEN_EMAIL_PASSWORD% in the value of the Turnkey setting that requires the mail password.
MDrivenServerOverride.xml	MDrivenServerPWD	Refer to an environment variable instead of storing the MDrivenServer password in the override file.
MDrivenServer UI	EmailHost, EmailHostPWD, EmailFrom, EmailFromPresentation, and A0-ConnectionString	Set A0-ConnectionString to a value such as %MDRIVEN_A0_CONNECTIONSTRING%.

Configure a secret reference

1. Decide which setting should obtain its value from the environment. For example, use an environment variable for the password supplied to EmailHostPWD.
2. Create an environment variable for the application with the required value. For example, create MDRIVEN_EMAIL_PASSWORD with the mail password as its value.
3. In the MDriven configuration location that uses the value, replace the value with %MDRIVEN_EMAIL_PASSWORD%.
4. Ensure that the process hosting MDrivenServer or Turnkey can see that environment variable.
5. Keep the environment-variable name and the configuration reference aligned. A reference to %MDRIVEN_EMAIL_PASSWORD% requires an environment variable named MDRIVEN_EMAIL_PASSWORD.

Example: Turnkey setting

The following illustrates the substitution pattern in a Turnkey setting:

<EmailHostPWD>%MDRIVEN_EMAIL_PASSWORD%</EmailHostPWD>

Use the appropriate setting element from your existing TurnkeySettings.xml; the value between the element tags is the part that contains the environment-variable reference.

Use an override for deployment-specific Turnkey values

Use TurnkeySettingsOverride.xml for Turnkey settings that are specific to an installation. The override file is read after TurnkeySettings.xml and is not overwritten when the Turnkey installation is refreshed. This makes it a suitable place for deployment-specific references such as external-service settings or secret references.

For example, keep a shared-secret reference in TurnkeySettingsOverride.xml rather than adding the secret to a Turnkey file that may be refreshed. Do not share the secret value outside the administrators of the system.

Azure Web App: reference an Azure Key Vault secret

An Azure Web App can expose an Azure Key Vault secret as an application environment variable. Configure the Key Vault reference, then use the resulting variable name in MDriven with the percent-sign syntax.

1. In Azure Key Vault, open Access Control (IAM).
2. Assign the Key Vault Secrets User role to the identity of the App Service.
3. In the App Service, open Settings > Environment variables.
4. Add a setting. For example:

Name:  MY_SECRET_KEY
Value: @Microsoft.KeyVault(SecretUri=https://your-vault.vault.azure.net/secrets/your-secret-name/)

1. In the relevant MDriven setting, enter %MY_SECRET_KEY%.

For example, if MY_SECRET_KEY contains the value needed by EmailHostPWD, set EmailHostPWD in the MDrivenServer UI to %MY_SECRET_KEY%. MDriven resolves the reference when it reads the setting.

IIS on a virtual machine: set a variable for one application pool

If MDriven runs under IIS on a virtual machine, you can set an environment variable for a specific IIS application pool. The following PowerShell example obtains a Key Vault secret and assigns it to an application-pool environment variable:

$secret = (Get-AzKeyVaultSecret -VaultName "YourVault" -Name "YourSecret").SecretValueText
$appPool = "YourAppPoolName"
Set-WebConfigurationProperty -filter /system.applicationHost/applicationPools/add[@name='$appPool']/environmentVariables -name "." -value @{name='MY_SECRET';value=$secret}

Replace YourVault, YourSecret, and YourAppPoolName with the values for the deployment. Then use %MY_SECRET% in the applicable MDrivenServer or Turnkey setting. This scopes the variable to the named IIS application pool rather than making it a general configuration value.

Security guidance

• Store the secret value in the environment-variable provider. Store only the %VariableName% reference in MDriven configuration.
• Treat connection strings, mail passwords, shared secrets, access tokens, and refresh tokens as sensitive values.
• Restrict access to the Key Vault secret and to the identity used by the App Service or IIS application pool.
• Keep deployment-specific settings in TurnkeySettingsOverride.xml when you need them preserved across a Turnkey refresh.

See also

• Documentation:TurnkeySettings
• Documentation:MDrivenServer, Lost password or locked out
• Documentation:Turnkey local development tips