You use TurnkeySettings.xml and its companion files to configure how a MDriven Turnkey application starts, authenticates users, manages sessions, and renders selected UI features; this page is for administrators of hosted and local Turnkey installations.
Settings files and location
Store the settings files in the Turnkey application's App_Data folder. Turnkey reads the files in the following order:
| File | Read order | Who manages it | Use it for |
|---|---|---|---|
TurnkeySettingsExtra.xml
|
First | You | Local or experimental settings that the portal does not manage. |
TurnkeySettings.xml
|
Second | The portal for portal-managed applications; you for local installations | The main application settings. |
TurnkeySettingsOverride.xml
|
Last | You | Values that must override the generated main settings file, including authentication configuration that must survive a settings refresh. |
Because settings read later take precedence over settings read earlier, put a value in TurnkeySettingsOverride.xml when it must win over the same value in TurnkeySettings.xml.
For example, if both the main file and the override file define HidePasswordLogin, Turnkey uses the value from TurnkeySettingsOverride.xml.
Choose the right file
Portal-managed applications
The portal at portal.mdriven.net recreates App_Data/TurnkeySettings.xml when you select SendSettingsAndRestart. Treat that file as generated configuration: changes made directly in it can be replaced the next time settings are sent.
Use one of the companion files for settings that the portal does not know about:
- Use
TurnkeySettingsExtra.xmlfor settings that must be available before the generated settings are read. - Use
TurnkeySettingsOverride.xmlfor settings that must take precedence over generated settings. For example, place OpenID Connect settings here so that a regeneratedTurnkeySettings.xmldoes not replace them.
Local or on-premise applications
For a standalone installation that the portal cannot reach, you must create and maintain TurnkeySettings.xml yourself. Turnkey needs this file to obtain the information it uses to connect to MDrivenServer.
- Open the Turnkey application's
App_Datafolder. - Copy the supplied
TurnkeySettings - NotInEffect.xmltemplate. - Name the copy
TurnkeySettings.xml. - Edit the file and enter the MDrivenServer user name and password required by the template.
- Save the file and restart the application pool so that Turnkey reads the changed configuration.
If the application does not restart after a file change, restart its application pool. The local setup walkthrough also demonstrates restarting by touching the web configuration file; restarting the application pool is the direct administrative action.
When applying updated Turnkey or MDrivenServer packages to an on-premise installation, use the package option that appends files. A delete-style update can remove local settings and the database. For the full installation procedure, see Documentation:Set up MDriven Turnkey on premise.
Common settings
Add settings as XML elements in the applicable settings file. The following examples show the element names and values described for Turnkey.
| Setting | Example | Effect |
|---|---|---|
HidePasswordLogin
|
<HidePasswordLogin>False</HidePasswordLogin>
|
Controls whether local password login is hidden. When you use social login and want users to use it instead of local accounts, set this to True. See Documentation:Hide Password login.
|
HideExternalLogin
|
<HideExternalLogin>False</HideExternalLogin>
|
Controls whether external login is hidden. |
AllowUserToChooseSocialLoginEmail
|
<AllowUserToChooseSocialLoginEmail>True</AllowUserToChooseSocialLoginEmail>
|
Controls whether a user can edit the email address when a local account is registered during the first external login. |
SkipExternalAccountConfirmationScreen
|
<SkipExternalAccountConfirmationScreen>False</SkipExternalAccountConfirmationScreen>
|
Controls whether the initial local-account confirmation screen for an external login is skipped. |
HideRegistration
|
<HideRegistration>True</HideRegistration>
|
Hides registration. |
CurrentUserViewModel
|
<CurrentUserViewModel>MyUserViewModel</CurrentUserViewModel>
|
Names the ViewModel to open when the user selects their logged-in name. Replace MyUserViewModel with the name of your ViewModel.
|
UseCSSGridByDefault
|
<UseCSSGridByDefault>True</UseCSSGridByDefault>
|
Sets CSS Grid as the default. |
ApplicationNameAsMenu
|
<ApplicationNameAsMenu>False</ApplicationNameAsMenu>
|
Prevents the application name from being added as an index link after the application logo in the menu bar. This can be kept in TurnkeySettingsExtra.xml so that sending settings does not replace it.
|
Authentication and OpenID Connect
Turnkey supports settings for external authentication, including OpenID Connect. Put configuration that must not be replaced by portal-generated settings in TurnkeySettingsOverride.xml.
For example, an organization that requires single sign-on can combine HidePasswordLogin, AllowUserToChooseSocialLoginEmail, and SkipExternalAccountConfirmationScreen with its OpenID Connect configuration. Configure the provider-specific values, redirect URL, scopes, token endpoint, and token-encryption secret as described in Documentation:OpenID config. For Azure AD-specific guidance, see Documentation:Openid AzureAD.
Session, capacity, and table settings
| Setting | Example | Effect and operational note |
|---|---|---|
TurnOffOWINButKeepSignalR
|
<TurnOffOWINButKeepSignalR>true</TurnOffOWINButKeepSignalR>
|
Use when running Windows Authentication in IIS while retaining SignalR. The default is false. Available from 2023-10-17.
|
RemoveTurnkeyAppAfterMinutes
|
<RemoveTurnkeyAppAfterMinutes>10</RemoveTurnkeyAppAfterMinutes>
|
Sets how long a Turnkey session may be disconnected from the network before it becomes a candidate for shutdown. Users lose unsaved changes if the session is shut down. |
NumberOfTurnkeyEcoSpacesToKeepWhenFree
|
<NumberOfTurnkeyEcoSpacesToKeepWhenFree>10</NumberOfTurnkeyEcoSpacesToKeepWhenFree>
|
Sets how many free EcoSpaces Turnkey prepares and retains. This setting trades memory use against the speed of starting work in an available EcoSpace. |
TurnkeyTimeoutMinutes
|
<TurnkeyTimeoutMinutes>1</TurnkeyTimeoutMinutes>
|
Sets how long a client screen continues to display the UI with no user interaction. See Documentation:Span.TurnkeyTimeoutMinutes. |
AdvancedTables
|
<AdvancedTables>true</AdvancedTables>
|
Enables resizing DataGrid column headers. |
TableColumnsExcludeNames
|
<TableColumnsExcludeNames>Dummy</TableColumnsExcludeNames>
|
Excludes comma-separated column names when DataGrids render. For example, exclude a legacy blank Dummy column that was added for WPF layout behavior and should not appear when advanced tables are enabled.
|
AttackBreakThreshold
|
<AttackBreakThreshold>2</AttackBreakThreshold>
|
Sets the threshold at which Turnkey slows the start of new sessions from an attacking IP address. Set a high value such as 100000 to make reaching the threshold unlikely, effectively disabling this behavior.
|
Debug information
ShowDebugInfo and ShowDebugInfoPassword control access to debugging information pages. When debug information is not shown, set a password to protect access:
<ShowDebugInfoPassword>password</ShowDebugInfoPassword>
Debug information makes the Turnkey server slower and increases memory use. Use it deliberately, especially in production.
Example: preserve local sign-in configuration
The following example belongs in App_Data/TurnkeySettingsOverride.xml when the portal manages the main settings file. It hides local password login and retains a locally defined external-login behavior after SendSettingsAndRestart regenerates the main file.
<HidePasswordLogin>True</HidePasswordLogin>
<AllowUserToChooseSocialLoginEmail>True</AllowUserToChooseSocialLoginEmail>
<SkipExternalAccountConfirmationScreen>False</SkipExternalAccountConfirmationScreen>
Complete the required provider configuration separately by following Documentation:OpenID config.