Workspace app pre–configuration

Pre-configuration allows IT administrators to deploy Workspace Windows app with pre-configured settings and data sources (Devolutions Server and Devolutions Hub Business) across Windows endpoints. This eliminates the need for end users to manually configure the application after installation.

• Zero-touch deployment: Users start with fully configured applications

• Consistency: Ensure all users have the same data sources and settings

• Time savings: Eliminate manual configuration steps

• Flexibility: Multiple deployment methods to fit different IT infrastructures

• Scalability: Deploy to hundreds or thousands of endpoints efficiently

1. An IT Admin configures datasources and settings via MSI parameters or configuration files.

2. Deployment tool pushes installation to managed devices (Intune, SCCM, PDQ Deploy, etc.).

3. Users launche app for the first time.

4. The app reads the configuration and automatically creates datasources.

5. Users log in to complete the connection.

• Authentication required: Pre-configured datasources are created in a "pending" state. Users must still log in to complete the connection.

• First launch only: Configuration is applied once on first launch. Subsequent changes require app reinstallation or manual configuration.

• Credentials NOT Stored: Pre-configuration does NOT include user credentials. Users must log in with their own credentials.

Pass configuration parameters directly to the Windows installer during deployment. You can combine data source parameters with application settings.

Use case: Quick deployments, simple configurations, testing

• Basic example (data sources only):

msiexec /i Workspace.msi /qn DVLS_SERVER_URL="https://server.com" HUB_NAME="mycompany"

• With settings (data sources + application settings):

msiexec /i Workspace.msi /qn ^
  DVLS_SERVER_URL="https://server.com" ^
  HUB_NAME="mycompany" ^
  ORGANIZATION_ID="guid-here" ^
  LANGUAGE="fr" ^
  LOCKING_OPTION="windowsCredentials"

Limitations: Only one Devolutions Server can be configured via MSI parameters. For multiple servers, use Method 2.

Deploy a pre-created .cfg file to target systems.

• Use case: Intune, SCCM, complex configurations, multiple data sources

msiexec /i Workspace.msi /qn DEPLOY_CONFIG="C:\path\to\Config.cfg"

• Target: %ProgramData%\net.devolutions\Workspace\DefaultConfig.cfg

• How it works:

1. MSI writes config to ProgramData during installation

2. When any user launches Workspace, app detects system-wide config

3. Config automatically copies to user's Roaming profile

4. User has configured application

1. Reliable: Works regardless of user context (no "Default user" issues)

2. Consistent: All users on machine get same configuration

3. Automation-friendly: Perfect for Intune, SCCM, silent installs

4. Multi-user support: Applies to all existing and future users

• Best for: Intune, SCCM, silent installs, multi-user machines, shared workstations

msiexec /i Workspace.msi /qn USER_CONFIG="C:\path\to\Config.cfg"

• Target: %LOCALAPPDATA%\net.devolutions\Workspace\Config.cfg

• How it works:

1. MSI writes config to installing user's Local AppData

2. User launches Workspace

3. Config copies to user's Roaming profile

4. Only that user has configured application

• Limitations:

1. Only configures the user who ran the installer

2. May fail in automated deployments (user context issues)

3. Not suitable for multi-user machines

• Best for: Interactive installations by end users, single-user devices

Use the desktop application to create configuration files and MSI commands.

• Use case: IT administrators preparing deployment packages

• Access: Tools – Custom installation (in the desktop application)

See Configuration file creator section for details.

Configuration files use the .cfg extension and contain JSON-formatted data.

{
  "hubs": [
    {
      "url": "https://mycompany.devolutions.app",
      "organizationId": "00000000-0000-0000-0000-000000000000",
      "type": "Business",
      "version": ""
    }
  ],
  "dvls": [
    {
      "name": "Production DVLS",
      "serverUrl": "https://dvls.company.com",
      "serverVersion": ""
    },
    {
      "name": "Development DVLS",
      "serverUrl": "https://dvls-dev.company.com",
      "serverVersion": ""
    }
  ],
  "configs": {
    "language": "en-US",
    "reduceToTrayOnClose": true,
    "clearClipboardSensitiveData": true,
    "clipboardTimer": 30,
    "useFavicon": true,
    "useEntriesSyncOnDatasourceAccess": false,
    "useHubEmbeddedBrowser": true,
    "shareUsageData": false,
    "lockingOption": "windowsCredentials",
    "useBackgroundLock": true,
    "useLockWhenInactive": true,
    "lockInactivityDelay": 300
  }
}

Array of Devolutions Hub Business instances to configure.

Array of Devolutions Server instances to configure.

Application settings to pre-configure.

See Configuration settings reference for complete list.

Configuration files are loaded in priority order based on location.

• Roaming AppData: %APPDATA%\net.devolutions\Workspace\Config.cfg

• Default: C:\Users\[Username]\AppData\Roaming\net.devolutions\Workspace\Config.cfg

• Syncs across domain-joined computers

• Highest priority (user-specific)

• • Local AppData: %LOCALAPPDATA%\net.devolutions\Workspace\Config.cfg

  • Default: C:\Users\[Username]\AppData\Local\net.devolutions\Workspace\Config.cfg

  • Machine-specific, not synced

  • Used during MSI installation, then copied to Roaming

• • ProgramData: %ProgramData%\net.devolutions\Workspace\DefaultConfig.cfg

  • Default: C:\ProgramData\net.devolutions\Workspace\DefaultConfig.cfg

  • Applies to all users on the system

  • Requires config.ready indicator file in same directory

  • Copied to user Roaming location on first launch (if user config doesn't exist)

• File: config.ready

• Location: Same directory as DefaultConfig.cfg

• Purpose: Signals that system-wide config is ready for deployment

• Content: Empty file, presence is checked only

Configuration sources are checked in the following order (first found wins):

1. User Configuration File – User – specific config

2. System Configuration File – System – wide default (copied to user location)

The Windows MSI installer accepts the following parameters for pre-configuration.

• Note: Only one (Devolutions Server can be configured via MSI parameters. For multiple servers, use a configuration file.

• Note: The full Devolutions Hub URL is constructed as https://{HUB_NAME}.devolutions.app

• Note: ORGANIZATION_ID is optional. Some Devolutions Hub Business instances don't require an organization ID. If not applicable, you can omit this parameter or pass an empty string.

The desktop application includes a visual tool for creating configuration files.

1. Launch Devolutions Workspace (desktop version).

2. Navigate to: Tools – Custom Installation.

1. Data Source Selection.

• View all configured (Devolutions Server and Hub Business instances

• Select which data sources to include via checkboxes

• Multiple data sources supported

2. Settings Configuration

• Enable/disable individual application settings grouped by category:

• General (Language, Tray behavior)

• Security (Clipboard, Locking)

• Synchronization

• Privacy (Usage statistics)

3. Live Preview

• Real-time JSON preview of configuration

• Copy JSON to clipboard

• Preview updates as selections change

4. Export Options

• Generate .cfg File: Save configuration to .cfg file

• Copy MSI Command: Generate complete MSI command with all parameters

1. File Selection

• Browse for .cfg files

• File validation and parsing

2. Preview Before Import

• View data sources and settings before applying

• Duplicate detection (warns if data source already exists)

3. Import Actions

• Applies configuration to current application

• Creates new data sources if they don't exist

• Updates settings immediately

Complete reference of all configurable settings.

• Note: If Windows Hello is not available, falls back to password.

msiexec /i Workspace.msi /qn ^
  DVLS_SERVER_URL="https://dvls.company.com" ^
  LOCKING_OPTION="windowsCredentials" ^
  USE_LOCK_WHEN_INACTIVE="true" ^
  LOCK_INACTIVITY_DELAY="300" ^
  CLEAR_CLIPBOARD_SENSITIVE_DATA="true" ^
  CLIPBOARD_TIMER="60"

# With Organization ID
msiexec /i Workspace.msi /qn ^
  HUB_NAME="mycompany" ^
  ORGANIZATION_ID="12345678-1234-1234-1234-123456789abc" ^
  LANGUAGE="fr" ^
  REDUCE_TO_TRAY_ON_CLOSE="true"

# Without Organization ID (for Hubs that don't require it)
msiexec /i Workspace.msi /qn ^
  HUB_NAME="mycompany" ^
  LANGUAGE="fr" ^
  REDUCE_TO_TRAY_ON_CLOSE="true"

Create a working folder (e.g., C:\IntuneApps\Workspace\) and place these files:

• Workspace.msi

• config.cfg (created via Tools – Custom installation or manually)

• Install-Workspace.ps1 (PowerShell script below)

Create Install-Workspace.ps1:

# Install-Workspace.ps1
# Source files in the Intune package
$ConfigSource = "$PSScriptRoot\config.cfg"
$ConfigTarget = "C:\Program Files\config.cfg"
$MsiPath = "$PSScriptRoot\Workspace.msi"

# Copy config.cfg to Program Files
try {
    Copy-Item -Path $ConfigSource -Destination $ConfigTarget -Force
} catch {
    Write-Host "Error copying config file: $($_.Exception.Message)"
    exit 1
}

# Install MSI silently with DEPLOY_CONFIG parameter
$Arguments = "/i `"$MsiPath`" /qn /norestart DEPLOY_CONFIG=`"C:\Program Files\config.cfg`""
$Process = Start-Process "msiexec.exe" -ArgumentList $Arguments -Wait -PassThru

# Return exit code to Intune
exit $Process.ExitCode

Use the Microsoft Win32 Content Prep Tool (IntuneWinAppUtil.exe):

IntuneWinAppUtil.exe -c C:\IntuneApps\Workspace -s Install-Workspace.ps1 -o C:\IntuneApps\Output

In Microsoft Intune Portal:

1. Navigate to: Apps – Windows – Add – Windows app (Win32)

2. App Package File: Upload Workspace.intunewin

3. App Information: Fill in name, description, publisher

4. Program configuration:

• Install command: powershell.exe -ExecutionPolicy Bypass -File .\Install-Workspace.ps1

• Uninstall command: msiexec.exe /x {PRODUCT-CODE-GUID} /qn /norestart

• Install behavior: System

5. Requirements: Windows 10 1607+ (64-bit)

6. Detection Rules: MSI product code (auto-detected)

7. Assignments: Assign to target groups

When the app is deployed to a device, the following happens automatically:

1. Intune downloads and executes Install-Workspace.ps1

2. The script copies config.cfg to C:\Program Files\config.cfg

3. The script installs the MSI with DEPLOY_CONFIG="C:\Program Files\config.cfg"

4. The MSI reads the configuration file and writes it to %ProgramData%\net.devolutions\Workspace\DefaultConfig.cfg

5. When a user launches Workspace Windows app, the app detects the system-wide config and applies it

The result: the configuration file is distributed with the application, placed automatically in the correct location, and the installation is fully silent and Intune-compatible.

• Install command:

msiexec /i Workspace.msi /qn /norestart DEPLOY_CONFIG="%~dp0Config.cfg"

• Uninstall command:

msiexec /x {PRODUCT-CODE} /qn /norestart

• Detection method: Registry key HKLM\SOFTWARE\Devolutions\Workspace\Version

Create config.cfg:

{
  "dvls": [
    {
      "name": "Production DVLS",
      "serverUrl": "https://dvls-prod.company.com"
    },
    {
      "name": "Development DVLS",
      "serverUrl": "https://dvls-dev.company.com"
    },
    {
      "name": "Test DVLS",
      "serverUrl": "https://dvls-test.company.com"
    }
  ],
  "configs": {
    "language": "en-US",
    "shareUsageData": false
  }
}

Deploy via:

msiexec /i Workspace.msi /qn DEPLOY_CONFIG="\\fileserver\IT\Workspace\config.cfg"

Configuration file present but settings not applied.

1. Check file location: Verify correct path (%ProgramData%\net.devolutions\Workspace\DefaultConfig.cfg)

2. Check JSON validity: Validate JSON syntax (no trailing commas, proper quotes)

3. Check permissions: User must have read access to config file

4. Verify indicator file: Check if config.ready file exists in same directory

5. Check logs: Review application logs for parsing errors

• Problem: System-wide configuration ignored.

• Solution: Create config.ready file:

type nul > "%ProgramData%\net.devolutions\Workspace\config.ready"

• Problem: USER_CONFIG fails in silent/automated installs, config ends up in C:\Users\Default\AppData\Local.

• Cause: USER_CONFIG requires active user session context, which isn't available during automated MSI installation.

• Solution: Use DEPLOY_CONFIG for enterprise deployments:

# CORRECT for Intune/SCCM
msiexec /i Workspace.msi /qn /norestart DEPLOY_CONFIG="%~dp0Config.cfg"

# WRONG for automated deployment
msiexec /i Workspace.msi /qn /norestart USER_CONFIG="%~dp0Config.cfg"

MSI parameters not creating configuration.

1. Check parameter syntax: Ensure proper quoting (use "value", not 'value')

2. Log MSI installation: Add /l*v install.log to see detailed errors

3. Verify PowerShell execution: Check if execution policy blocks scripts

4. Administrative rights: Ensure installer runs with elevation

• Example with logging:

msiexec /i Workspace.msi /qn /l*v C:\Temp\install.log DVLS_SERVER_URL="https://server.com"

Settings revert to defaults after restart.

1. User vs System Config: System config only applies if user config doesn't exist. Once user modifies settings, they are saved to user config and override system defaults.

2. Group Policy Override: Check if GPO is enforcing settings

3. File Permissions: Verify write permissions to user config location

Problem: Import fails with "data source already exists" message.

Explanation: Configuration parser detects duplicates by normalized URL (case-insensitive, trailing slash removed).

1. Remove existing data source manually before importing

2. Edit configuration file to remove duplicate entries

3. Use Custom Installation tool to merge configurations

Windows Hello not activating.

1. Windows Hello Setup: Ensure Windows Hello is configured in Windows Settings

2. Fallback: System automatically falls back to password if hardware unavailable

3. Check logs: Review application logs for biometric initialization errors

Before deploying to all users:

1. Create a test user/device group

2. Apply configuration to test group

3. Verify datasources and settings work as expected

4. Roll out to production

• Always use DEPLOY_CONFIG for:

• Intune deployments

• SCCM deployments

• Silent/unattended installations

• Multi-user machines

• Shared workstations

• Only use USER_CONFIG for:

• Interactive installations by end users

• Single-user devices

• Testing scenarios

Maintain documentation of your configuration including:

• Which datasources are pre-configured

• What settings are enforced

• Expected user experience

• Support contact for issues

Inform users:

• Datasources will be pre-configured

• They still need to log in with their credentials

• Configuration happens on first app launch

• Contact IT if datasources don't appear

Recommended security settings:

{
  "lockingOption": "windowsCredentials",
  "useBackgroundLock": true,
  "useLockWhenInactive": true,
  "lockInactivityDelay": 300,
  "clearClipboardSensitiveData": true,
  "clipboardTimer": 60,
  "shareUsageData": false
}

Why:

• Enforces Windows Hello authentication

• Locks app immediately when backgrounded

• Auto-locks after 5 minutes of inactivity

• Clears clipboard after 60 seconds

• Disables usage data collection (optional)

All URLs must:

• Include protocol (https://)

• Be valid, accessible URLs

• Not end with trailing slash (app will normalize)

Examples:

• https://dvls.company.com

• https://workspace.devolutions.app

• dvls.company.com (missing https://)

• http://dvls.company.com (HTTP not recommended)

• Domain-Joined: Use Roaming AppData (TARGET_LOCATION="roaming") for profile sync

• Standalone: Use Local AppData (TARGET_LOCATION="local") or System (TARGET_LOCATION="system")

{
  "dvls": [
    {
      "name": "DVLS Server",
      "serverUrl": "https://dvls.example.com"
    }
  ]
}

msiexec /i Workspace.msi /qn /norestart DEPLOY_CONFIG="\\server\share\Config.cfg"

Pre-configuration allows IT administrators to deploy Workspace with pre-configured settings and data sources (Devolutions Server and Devolutions Hub Business instances) across managed macOS endpoints. This eliminates the need for end-users to manually configure the application after installation.

• Zero-touch deployment: Users start with fully configured applications

• Consistency: Ensure all users have the same data sources and settings

• Time savings: Eliminate manual configuration steps

• Centralized management: Configure from MDM console

• Policy enforcement: Can prevent users from changing settings

• Enterprise standard: Recommended approach for managed macOS fleets

1. IT Admin configures datasources and settings via MDM or configuration files

2. MDM pushes configuration to managed devices

3. User launches app for the first time

4. App reads configuration and creates datasources automatically

5. User authenticates to complete the connection (enters credentials)

• Authentication required: Pre-configured datasources are created in a "pending" state. Users must still authenticate (log in) to complete the connection.

• First launch only: Configuration is applied once on first launch. Subsequent changes require app reinstallation or manual configuration.

• Credentials NOT Stored: Pre-configuration does NOT include user credentials. Users must log in with their own credentials.

Deploy configuration via Mobile Device Management (MDM) solutions for managed macOS environments.

• Use case: Jamf Pro, Microsoft Intune for Mac, other MDM solutions

• Priority: Highest (overrides all file-based configurations)

• Preference domain: net.devolutions.authenticator

• Centralized management: Configure from MDM console

• Policy enforcement: Can prevent users from changing settings

• Highest priority: Overrides local configuration files

• Enterprise standard: Recommended approach for managed macOS fleets

See MDM/Managed Preferences section for detailed instructions.

Deploy a pre-created .cfg file to target systems.

• Use Case: Scripted deployments, non-MDM environments, testing

• System-Wide Location: /Library/Application Support/Devolutions/Workspace/DefaultConfig.cfg

• Per-User Location: ~/Library/Application Support/Workspace/Config.cfg

See Configuration file structure section for details.

For manual configuration or scripting:

# Set language
defaults write net.devolutions.authenticator language -string "en-US"

# Enable tray minimize
defaults write net.devolutions.authenticator reduceToTrayOnClose -bool true

# Set locking option
defaults write net.devolutions.authenticator lockingOption -string "biometric"

Use case: Manual setup, testing, shell scripts

1. Download or copy the Jamf Pro JSON Schema for Workspace:

{
  "title": "Devolutions Workspace Configuration (net.devolutions.authenticator)",
  "description": "Configuration settings for Devolutions Workspace application deployed via Jamf Pro. These settings are deployed as managed preferences to managed devices.",
  "__version": "1.0",
  "__preferencedomain": "net.devolutions.authenticator",
  "options": {
    "remove_empty_properties": true
  },
  "properties": {
    "dvls": {
      "title": "DVLS Configuration",
      "description": "Devolutions Server connection settings",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "title": "Server Name",
            "description": "Display name for the DVLS server",
            "type": "string",
            "default": "Devolutions Server"
          },
          "serverUrl": {
            "title": "Server URL",
            "description": "Full URL to the DVLS server (e.g., https://server.company.com)",
            "type": "string",
            "pattern": "^https?://.*"
          },
          "serverVersion": {
            "title": "Server Version",
            "description": "DVLS server version (optional)",
            "type": "string",
            "default": ""
          }
        },
        "required": ["serverUrl"]
      },
      "default": []
    },
    "hubs": {
      "title": "Hub Business Configuration",
      "description": "Devolutions Hub Business connection settings",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "title": "Hub URL",
            "description": "Full Hub URL (e.g., https://yourcompany.devolutions.app)",
            "type": "string",
            "pattern": "^https://.*\\.devolutions\\.app$"
          },
          "organizationId": {
            "title": "Organization ID",
            "description": "Organization identifier for Hub Business",
            "type": "string"
          },
          "type": {
            "title": "Hub Type",
            "description": "Hub connection type (optional)",
            "type": "string"
          },
          "version": {
            "title": "Hub Version",
            "description": "Hub version compatibility",
            "type": "string",
            "default": "2020"
          }
        },
        "required": ["url"]
      },
      "default": []
    },
    "configs": {
      "title": "Application Settings",
      "description": "User preferences and application behavior settings",
      "type": "object",
      "properties": {
        "language": {
          "title": "Language",
          "description": "Default language for Workspace interface",
          "type": "string",
          "enum": [
            "en-US", "fr", "de", "es", "cs", "hu", "it", "nl", "pl", "ru", "sv", "tr", "uk", "zh-CHS", "zh-TW"
          ],
          "default": "en-US",
          "options": {
            "enum_titles": [
              "English", "Français", "Deutsch", "Español", "Čeština", "Magyar", "Italiano",
              "Nederlands", "Polski", "Русский", "Svenska", "Türkçe", "Українська", "简体中文", "繁體中文"
            ]
          }
        },
        "reduceToTrayOnClose": {
          "title": "Minimize to Tray on Close",
          "description": "When enabled, closing the window minimizes to system tray instead of quitting",
          "type": "boolean",
          "default": false
        },
        "clearClipboardSensitiveData": {
          "title": "Clear Clipboard Sensitive Data",
          "description": "Automatically clear sensitive data from clipboard after a specified timeout",
          "type": "boolean",
          "default": false
        },
        "clipboardTimer": {
          "title": "Clipboard Timeout (seconds)",
          "description": "Duration in seconds before clearing clipboard when sensitive data clearing is enabled",
          "type": "integer",
          "enum": [30, 60, 120, 180, 240, 300, 0],
          "default": 30,
          "options": {
            "enum_titles": ["30 seconds", "1 minute", "2 minutes", "3 minutes", "4 minutes", "5 minutes", "Never"]
          }
        },
        "useFavicon": {
          "title": "Use Favicons",
          "description": "Download and display website favicons for entries",
          "type": "boolean",
          "default": false
        },
        "useEntriesSyncOnDatasourceAccess": {
          "title": "Sync Entries on Data Source Access",
          "description": "Automatically synchronize entries when accessing a data source",
          "type": "boolean",
          "default": false
        },
        "useHubEmbeddedBrowser": {
          "title": "Use Hub Embedded Browser",
          "description": "Open Hub connections in embedded browser (disable if using credential providers)",
          "type": "boolean",
          "default": true
        },
        "lockingOption": {
          "title": "Locking Method",
          "description": "Authentication method used when locking/unlocking Workspace. Leave empty for no locking method.",
          "type": "string",
          "enum": ["", "password", "biometric"],
          "default": "",
          "options": {
            "enum_titles": ["None", "Password/PIN", "Biometric (Touch ID)"]
          }
        },
        "useBackgroundLock": {
          "title": "Lock When Backgrounded",
          "description": "Automatically lock the application when minimized or sent to system tray",
          "type": "boolean",
          "default": false
        },
        "useLockWhenInactive": {
          "title": "Auto-Lock When Inactive",
          "description": "Automatically lock the application after a period of inactivity",
          "type": "boolean",
          "default": false
        },
        "lockInactivityDelay": {
          "title": "Inactivity Lock Delay (seconds)",
          "description": "Time in seconds before locking due to inactivity (requires Auto-Lock to be enabled)",
          "type": "integer",
          "enum": [30, 60, 120, 180, 240, 300],
          "default": 30,
          "options": {
            "enum_titles": ["30 seconds", "1 minute", "2 minutes", "3 minutes", "4 minutes", "5 minutes"]
          }
        }
      }
    },
    "preventStartup": {
      "title": "Prevent Startup",
      "description": "When true, prevents Workspace from starting automatically after configuration deployment",
      "type": "boolean",
      "default": true
    }
  }
}

2. In Jamf Pro, navigate to: Computers – Configuration Profiles – Application & Custom Settings

3. Click Configure and upload the JSON schema file

4. Configure your desired settings using the GUI interface provided by Jamf

5. Scope the profile to your target computers

6. Deploy the configuration profile

If not using Jamf Pro, you can create a standard macOS configuration profile:

Example profile (com.devolutions.workspace.mobileconfig):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>net.devolutions.authenticator</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadIdentifier</key>
            <string>net.devolutions.authenticator.config</string>
            <key>PayloadUUID</key>
            <string>GENERATE-UUID-HERE</string>
            <key>PayloadDisplayName</key>
            <string>Workspace Configuration</string>
            <key>language</key>
            <string>en-US</string>
            <key>reduceToTrayOnClose</key>
            <true/>
            <key>lockingOption</key>
            <string>biometric</string>
            <key>dvls</key>
            <array>
                <dict>
                    <key>name</key>
                    <string>Corporate DVLS</string>
                    <key>serverUrl</key>
                    <string>https://dvls.company.com</string>
                </dict>
            </array>
        </dict>
    </array>
</dict>
</plist>

Deploy via:

• Jamf Pro: Configuration Profiles – Upload profile

• Microsoft Intune: Device Configuration – Custom profile

• Other MDMs: Custom configuration profile upload

1. Navigate to: Devices – Configuration profiles – Create profile.

2. Platform: macOS.

3. Profile type: Custom.

4. Upload the configuration profile (.mobileconfig file).

5. Assign to target groups.

6. Deploy.

On a managed Mac:

# Check if preferences are set
defaults read net.devolutions.authenticator

# Check for specific setting
defaults read net.devolutions.authenticator language

Configuration files use the .cfg extension and contain JSON-formatted data.

{
  "hubs": [
    {
      "url": "https://mycompany.devolutions.app",
      "organizationId": "00000000-0000-0000-0000-000000000000",
      "type": "Business",
      "version": ""
    }
  ],
  "dvls": [
    {
      "name": "Production DVLS",
      "serverUrl": "https://dvls.company.com",
      "serverVersion": ""
    },
    {
      "name": "Development DVLS",
      "serverUrl": "https://dvls-dev.company.com",
      "serverVersion": ""
    }
  ],
  "configs": {
    "language": "en-US",
    "reduceToTrayOnClose": true,
    "clearClipboardSensitiveData": true,
    "clipboardTimer": 30,
    "useFavicon": true,
    "useEntriesSyncOnDatasourceAccess": false,
    "useHubEmbeddedBrowser": true,
    "shareUsageData": false,
    "lockingOption": "biometric",
    "useBackgroundLock": true,
    "useLockWhenInactive": true,
    "lockInactivityDelay": 300
  }
}

Array of Devolutions Hub Business instances to configure.

Array of Devolutions Server instances to configure.

Application settings to pre-configure.

See Configuration settings reference for complete list.

• Path: ~/Library/Application Support/Workspace/Config.cfg

• Priority: Highest for user-specific configs

• Path: /Library/Application Support/Devolutions/Workspace/DefaultConfig.cfg

• Priority: Applied if user config doesn't exist

• Priority: Highest (overrides all file-based configs)

• Preference domain: net.devolutions.authenticator

• Keys: Same as configs object in JSON format

• Configuration: Via MDM profile or defaults command

Configuration sources are checked in the following order (first found wins):

1. macOS managed preferences – MDM/Jamf policies (highest priority)

2. User configuration file – User-specific config

3. System configuration file – System-wide default (copied to user location)

Complete reference of all configurable settings.

Using Jamf JSON Schema:

1. Upload the JSON schema to Jamf Pro

2. Configure via GUI:

   • Devolutions Server configuration: Add server with URL https://dvls.company.com

   • Locking Method: Biometric (Touch ID)

   • Lock When Backgrounded: Enabled

   • Auto-Lock When Inactive: Enabled

   • Inactivity Lock Delay: 5 minutes (300 seconds)

3. Scope to target computers

4. Deploy

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>net.devolutions.authenticator</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadIdentifier</key>
            <string>net.devolutions.authenticator.config</string>
            <key>PayloadUUID</key>
            <string>REPLACE-WITH-UNIQUE-UUID</string>
            <key>PayloadDisplayName</key>
            <string>Workspace Hub Configuration</string>
            <key>hubs</key>
            <array>
                <dict>
                    <key>url</key>
                    <string>https://mycompany.devolutions.app</string>
                    <key>organizationId</key>
                    <string>12345678-1234-1234-1234-123456789abc</string>
                    <key>type</key>
                    <string>Business</string>
                    <key>version</key>
                    <string>2020</string>
                </dict>
            </array>
            <key>configs</key>
            <dict>
                <key>language</key>
                <string>en-US</string>
                <key>lockingOption</key>
                <string>biometric</string>
            </dict>
        </dict>
    </array>
</dict>
</plist>

#!/bin/bash

# Configure DVLS server (complex structure requires plist file)
defaults write net.devolutions.authenticator dvls -array-add \
  '{name = "Production DVLS"; serverUrl = "https://dvls.company.com"; }'

# Configure application settings
defaults write net.devolutions.authenticator language -string "en-US"
defaults write net.devolutions.authenticator lockingOption -string "biometric"
defaults write net.devolutions.authenticator useBackgroundLock -bool true
defaults write net.devolutions.authenticator useLockWhenInactive -bool true
defaults write net.devolutions.authenticator lockInactivityDelay -int 300
defaults write net.devolutions.authenticator clearClipboardSensitiveData -bool true
defaults write net.devolutions.authenticator clipboardTimer -int 60

#!/bin/bash

# Create system-wide configuration directory
sudo mkdir -p "/Library/Application Support/Devolutions/Workspace"

# Deploy configuration file
sudo cp "/path/to/config.cfg" "/Library/Application Support/Devolutions/Workspace/DefaultConfig.cfg"

# Set proper permissions
sudo chmod 644 "/Library/Application Support/Devolutions/Workspace/DefaultConfig.cfg"

Create config.cfg:

{
  "dvls": [
    {
      "name": "Production DVLS",
      "serverUrl": "https://dvls-prod.company.com"
    },
    {
      "name": "Development DVLS",
      "serverUrl": "https://dvls-dev.company.com"
    },
    {
      "name": "Test DVLS",
      "serverUrl": "https://dvls-test.company.com"
    }
  ],
  "configs": {
    "language": "en-US",
    "shareUsageData": false
  }
}

Deploy via script or manually place in system-wide location.

Configuration profile installed but settings not applying.

1. Verify preference domain: Ensure using net.devolutions.authenticator (not net.devolutions.workspace).

2. Check profile status: System Preferences – Profiles – Verify profile is installed.

3. Force profile refresh: sudo profiles renew -type enrollment.

4. Check for conflicts: Remove any existing user configuration files.

5. Review logs: Check Console.app for Workspace – related errors.

Configuration file present but not being applied.

1. Check file location: Verify correct path (/Library/Application Support/Devolutions/Workspace/DefaultConfig.cfg).

2. Check JSON validity: Validate JSON syntax (no trailing commas, proper quotes).

3. Check permissions: Ensure file is readable by all users (chmod 644).

4. Check ownership: Should be owned by root or admin.

5. Delete user config: Remove ~/Library/Application Support/Workspace/Config.cfg to allow system config to apply.

Touch ID not activating.

1. Hardware Check: Verify Mac has Touch ID hardware

2. Touch ID Setup: Ensure Touch ID is configured in System Preferences – Touch ID

3. Fallback: System automatically falls back to password if hardware unavailable

4. Check logs: Review application logs for biometric initialization errors

Unsure which preference domain to use.

Solution: Always use net.devolutions.authenticator for all Workspace configurations (both mobile and desktop).

Settings revert to defaults after restart.

1. MDM vs User config: MDM settings have highest priority and will override user changes

2. User vs System config: System config only applies if user config doesn't exist

3. File permissions: Verify write permissions to user config location

Import fails with "data source already exists" message.

Explanation: Configuration parser detects duplicates by normalized URL (case-insensitive, trailing slash removed).

1. Remove existing data source manually before applying configuration.

2. Edit configuration to remove duplicate entries.

3. Delete user config file to force re-import of system config.

Before deploying to all users:

1. Create a test computer group in Jamf/Intune.

2. Apply configuration to test group.

3. Verify datasources and settings work as expected.

4. Roll out to production.

Always use MDM/Managed preferences for:

• Jamf Pro managed Macs

• Intune managed Macs

• Any MDM-managed environment

Benefits:

• Centralized management

• Policy enforcement

• Highest priority (overrides local configs)

• Enterprise standard approach

Maintain documentation of your MDM configuration including:

• Which datasources are pre-configured

• What settings are enforced

• Expected user experience

• Support contact for issues

Inform users:

• Datasources will be pre-configured

• They still need to log in with their credentials

• Configuration happens on first app launch

• Contact IT if datasources don't appear

Recommended security settings:

{
  "lockingOption": "biometric",
  "useBackgroundLock": true,
  "useLockWhenInactive": true,
  "lockInactivityDelay": 300,
  "clearClipboardSensitiveData": true,
  "clipboardTimer": 60,
  "shareUsageData": false
}

Why:

• Enforces Touch ID authentication

• Locks app immediately when backgrounded

• Auto-locks after 5 minutes of inactivity

• Clears clipboard after 60 seconds

• Disables usage data collection (optional)

All URLs must:

• Include protocol (https://)

• Be valid, accessible URLs

• Not end with trailing slash (app will normalize)

Examples:

• https://dvls.company.com

• https://workspace.devolutions.app

• dvls.company.com (missing https://)

• http://dvls.company.com (HTTP not recommended)

For Jamf Pro deployments, always use the JSON schema:

• Provides user-friendly GUI interface

• Validates configuration before deployment

• Prevents syntax errors

• Shows all available options with descriptions

{
  "dvls": [
    {
      "name": "DVLS Server",
      "serverUrl": "https://dvls.example.com"
    }
  ]
}

net.devolutions.authenticator

/Library/Application Support/Devolutions/Workspace/DefaultConfig.cfg

defaults read net.devolutions.authenticator

MDM (Mobile Device Management) pre–configuration allows IT administrators to automatically provision Workspace datasources (Devolutions Server and Devolutions Hub Business) and application settings on managed iOS devices before users first launch the app.

• Zero–touch deployment: Users receive pre–configured datasources.

• Consistent configuration: Ensure all users have the same settings.

• Reduced support burden: No need to manually guide users through setup.

• Enforce security policies: Pre–configure biometric lock, clipboard timers, etc.

1. IT Admin configures datasources and settings in MDM console (Jamf or Apple MDM).

2. MDM pushes configuration to managed devices.

3. User launches app for the first time.

4. App reads MDM configuration and creates datasources automatically.

5. User authenticates to complete the connection (enters credentials).

• Authentication Required: Pre–configured datasources are created in a "pending" state. Users must still authenticate (log in) to complete the connection.

• First Launch Only: Configuration is applied once on first launch. Subsequent changes require app reinstallation or manual configuration.

• Credentials NOT Stored: MDM pre–configuration does NOT include user credentials. Users must log in with their own credentials.

• Jamf Pro server or Apple MDM solution

• Workspace app deployed via MDM (App Store or in–house)

• iOS 13.0 or later on managed devices

• Devices enrolled in MDM

1. Log in to Jamf Pro.

2. Navigate to Mobile Device Apps – Find "Workspace" app.

3. Click on the app – Go to App Configuration tab.

4. Click Add to create a new configuration.

In the App configuration screen:

• Select: Upload specfile to the Jamf AppConfig Generator for a GUI form (recommended), OR

• Select: Enter configuration directly as a plist/dictionary in Jamf Pro

Jamf Pro uses the AppConfig community standard for iOS managed app configuration. The specfile provides a GUI form in the Jamf AppConfig Generator where administrators can configure settings without writing raw configuration.

1. Download the Workspace Mobile AppConfig specfile: workspace_mobile_appconfig_specfile.xml.

2. Open the Jamf AppConfig Generator.

3. Upload the specfile and configure settings using the GUI form.

4. Download the generated configuration plist from the generator.

5. In Jamf Pro, navigate to Mobile Device Apps – Workspace – App Configuration.

6. Paste the generated plist into the App Configuration field, scope to target devices, and deploy.

If not using the specfile, you can enter configuration directly as a plist dictionary in Jamf Pro. Use the flat key format below — the app automatically transforms flat keys (e.g., dvls_serverUrl, hub_url) into the internal nested structure:

<dict>
  <!–– DVLS Server ––>
  <key>dvls_serverUrl</key>
  <string>https://dvls.company.com</string>

  <!–– Hub Business ––>
  <key>hub_url</key>
  <string>https://workspace.devolutions.app</string>
  <key>hub_organizationId</key>
  <string>your–org–id</string>

  <!–– Application Settings ––>
  <key>language</key>
  <string>en–US</string>
  <key>lockingOption</key>
  <string>biometric</string>
  <key>shareUsageData</key>
  <false/>
  <key>useBackgroundLock</key>
  <true/>
  <key>backgroundLockDelay</key>
  <integer>0</integer>
  <key>useLockWhenInactive</key>
  <true/>
  <key>lockInactivityDelay</key>
  <integer>300</integer>
  <key>useFavicon</key>
  <true/>
  <key>autoSearch</key>
  <false/>
  <key>useHubEmbeddedBrowser</key>
  <true/>
</dict>

Note: The flat key format (dvls_serverUrl, hub_url) is used for Jamf managed app configuration. The app automatically detects this format and transforms it into the internal nested structure. A display name is auto–generated from the DVLS URL.

1. Set Distribution Method to appropriate scope (users, devices, or groups).

2. Click Save.

3. Push the configuration to target devices.

On a managed iOS device:

1. Install/launch Workspace iOS app.

2. App should automatically show pre–configured datasources.

3. User taps datasource – enters credentials – connects.

{
  "name": string,           // Display name (required)
  "serverUrl": string,      // Full URL with https:// (required)
  "serverVersion": string   // Version like "2024.1" (optional)
}

{
  "url": string,            // Full URL with https:// (required)
  "organizationId": string, // Org ID (optional)
  "type": "business",       // Always "business" (required)
  "version": "2020"         // Always "2020" (required)
}

Jamf Configuration (using schema GUI):

• Devolutions Server: Add one server

  • Name: "Corporate DVLS"

  • Server URL: "https://dvls.acme.com"

  • Server Version: "2024.1"

• Devolutions Hub Business instances: Leave empty

• Application settings: Leave default

Direct JSON (if not using schema):

{
  "dvls": [
    {
      "name": "Corporate DVLS",
      "serverUrl": "https://dvls.acme.com",
      "serverVersion": "2024.1"
    }
  ]
}

Jamf Configuration (using schema GUI):

• Devolutions Hub Business instances: Add one Hub

  • Hub URL: "https://workspace.devolutions.app"

  • Organization ID: (leave empty or enter your org ID)

• Application Settings:

  • Locking Method: "Biometric (Touch ID/Face ID)"

  • Lock When Backgrounded: Enabled

  • Background Lock Delay: "Immediately"

  • Auto–Lock When Inactive: Enabled

  • Inactivity Lock Delay: "3 minutes"

Direct JSON (if not using schema):

{
  "hubs": [
    {
      "url": "https://workspace.devolutions.app",
      "organizationId": "",
      "type": "business",
      "version": "2020"
    }
  ],
  "configs": {
    "lockingOption": "biometric",
    "useBackgroundLock": true,
    "backgroundLockDelay": 0,
    "useLockWhenInactive": true,
    "lockInactivityDelay": 180
  }
}

Jamf Configuration (using schema GUI):

• Devolutions Server: Add multiple

  • Server 1: Name "Production DVLS", URL "https://dvls–prod.company.com"

  • Server 2: Name "Test DVLS", URL "https://dvls–test.company.com"

• Devolutions Hub Business instances: Add one

  • Hub URL: "https://workspace.devolutions.app"

  • Organization ID: "org–abc123"

• Application Settings:

  • Language: "English"

  • Share Usage Data: Disabled

Direct JSON (if not using schema):

{
  "dvls": [
    {
      "name": "Production DVLS",
      "serverUrl": "https://dvls–prod.company.com",
      "serverVersion": "2024.1"
    },
    {
      "name": "Test DVLS",
      "serverUrl": "https://dvls–test.company.com",
      "serverVersion": "2024.1"
    }
  ],
  "hubs": [
    {
      "url": "https://workspace.devolutions.app",
      "organizationId": "org–abc123",
      "type": "business",
      "version": "2020"
    }
  ],
  "configs": {
    "language": "en–US",
    "shareUsageData": false
  }
}

Problem: Users report no pre–configured datasources appear.

Solutions:

1. Verify MDM enrollment:

   • iOS: Settings – General – VPN & Device Management – Check profile

2. Check configuration syntax:

   • Validate JSON syntax (use jsonlint.com)

   • Ensure all required fields are present

3. Verify app is MDM–managed:

   • App must be deployed via MDM (not manually installed from App Store)

4. Re–apply configuration:

   • Delete app – Reinstall via MDM – Configuration applies on first launch

Users stuck with pending datasources they can't remove.

• New in version 2025.3.2: Users can now delete pending datasources

  • From drawer menu: Long–press datasource – Select "Remove"

  • From pending screen: Tap "Remove" button

Settings don't match expected values.

1. Check data types:

   • Booleans: Use true/false (not "true"/"false" strings)

   • Integers: Use numbers without quotes (e.g., 60 not "60")

   • Strings: Always use quotes (e.g., "en–US")

2. Verify setting names:

   • Check spelling (e.g., lockInactivityDelay not lockInactivityTimeout)

   • Case–sensitive (use exact casing shown in schema)

Duplicate datasources appear. Configuration was applied multiple times (app reinstalled or configuration changed).

• Pre–configuration checks for existing datasources by URL

• If duplicates exist, users can delete extras via drawer menu

Face ID/Touch ID not activating.

1. Check device support: Verify device has Face ID or Touch ID hardware

2. Check iOS settings: Ensure Face ID/Touch ID is set up in Settings

3. Check permissions: App may need biometric permission from user

4. Fallback: System automatically falls back to passcode if biometric unavailable

Before deploying to all users:

1. Create a test user/device group in Jamf.

2. Apply configuration to test group.

3. Verify datasources and settings work as expected.

4. Roll out to production.

For Jamf Pro deployments:

• Always use the AppConfig specfile (option A).

• Provides user–friendly GUI form via the Jamf AppConfig Generator.

• Validates configuration before deployment.

• Prevents syntax errors.

• Shows all available options with descriptions.

Maintain documentation of your MDM configuration including:

• Which datasources are pre–configured

• What settings are enforced

• Expected user experience

• Support contact for issues

Inform users:

• Datasources will be pre–configured

• They still need to log in with their credentials

• Configuration happens on first app launch

• Contact IT if datasources don't appear

Recommended security settings:

{
  "lockingOption": "biometric",
  "useBackgroundLock": true,
  "backgroundLockDelay": 0,
  "useLockWhenInactive": true,
  "lockInactivityDelay": 300,
  "shareUsageData": false
}

Why:

• Enforces Face ID/Touch ID authentication

• Locks app immediately when backgrounded

• Auto–locks after 5 minutes of inactivity

• Disables usage data collection (optional)

• Minimum Version: 2025.3.2 (for full pending datasource support)

• Devolutions Server versions: Devolutions Server 2023.3+ recommended

• iOS: 13.0+ required

All URLs must:

• Include protocol (https://)

• Be valid, accessible URLs

• Not end with trailing slash (app will normalize)

Examples:

• https://dvls.company.com

• https://workspace.devolutions.app

• dvls.company.com (missing https://)

• http://dvls.company.com (HTTP not recommended)

For organizations with multiple environments (prod, dev, test):

• Create separate Jamf configuration profiles for each environment

• Scope each profile to appropriate device groups

• Users in each environment get correct datasources automatically

{
  "dvls": [
    {
      "name": "DVLS Server",
      "serverUrl": "https://dvls.example.com"
    }
  ]
}

net.devolutions.workspace.mobile

1. Download the AppConfig specfile.

2. Upload to the Jamf AppConfig Generator.

3. Configure settings via the GUI form.

4. Download the generated plist.

5. In Jamf Pro: Mobile Device Apps – Workspace – App Configuration.

6. Paste the plist, scope to target devices, and deploy.