Install the Kasm smart card bridge native client
Overview
The Kasm Smart Card Bridge native client passes a smart card connected to a local machine into a Kasm Workspaces workspace. It pairs a Windows or macOS application with a Chrome extension, so users can authenticate and sign with a physical smart card from inside a streamed workspace. This guide installs the native client, upgrades or removes it, and configures logging for troubleshooting.
Prerequisites
Before you begin, confirm the following:
- Administrator access on the local Windows or macOS machine, with permission to run an installer.
- A supported operating system from the system requirements below.
- A Kasm Workspaces deployment, and the installer version that matches its release.
- The Google Chrome browser, which hosts the companion extension.
- On Windows, permission for installers to edit the Windows Registry, because the installer registers an event-log source.
Solution approach
This guide progresses through the following phases:
- Review the system requirements.
- Install the native client.
- Upgrade or uninstall the native client.
- Configure logging for troubleshooting.
Detailed steps
Review the system requirements
Confirm that the local machine runs a supported operating system before you download an installer.
- Windows
- macOS
| Supported Operating Systems |
|---|
| Windows 10 (x86_64) |
| Windows 11 (x86_64) |
| Windows Server 2019 (x86_64) |
| Windows Server 2022 (x86_64) |
| Windows Server 2025 (x86_64) |
| Supported Operating Systems |
|---|
| MacOS Sonoma (Intel/Apple Silicon) |
| MacOS Sequoia (Intel/Apple Silicon) |
| MacOS Tahoe (Intel/Apple Silicon) |
Install the native client
Select the installer that matches your Kasm Workspaces version, then run it. The installer places all required files in C:\Program Files\Kasm on Windows and /Library/Application Support/Kasm on macOS. Use the latest version that supports your installed version of Kasm Workspaces.
- Windows
- MacOS
| Installer Version | Installer Link | Kasm Workspaces Compatibility | SHA256 |
|---|---|---|---|
| Developer Preview | Kasm_Smart_Card_Bridge_develop_1.0.90f5dda2.msi | Developer Preview | rolling |
| 1.0.47121342 | Kasm_Smart_Card_Bridge_1.0.0_1.0.47121342.msi | 1.18.1 | d3202cd2d387c7926bb75245e4d47d068138d704160143d7da40f70226cbba05 |
| 1.0.4304bc51 | Kasm_Smart_Card_Bridge_1.0.0_1.0.4304bc51.msi | 1.18.0 | 3b0a58c2950927b53e1668990a3a47ff29d08cc0cf91acc01482b6c5ad572104 |
| Installer Version | Installer Link | Kasm Workspaces Compatibility | SHA256 |
|---|---|---|---|
| Developer Preview | Kasm_Smart_Card_Bridge_develop_1.0.90f5dda2.signed.pkg | Developer Preview | rolling |
| 1.0.47121342 | Kasm_Smart_Card_Bridge_release_1.0.47121342.signed.pkg | 1.18.1 | e7ca0d54819b681112acc4157c1d964faf31cdc516b1439c028f227e13f5c5d1 |
| 1.0.4304bc51 | Kasm_Smart_Card_Bridge_release_1.0.4304bc51.signed.pkg | 1.18.0 | 3f089e73a08233aad7be037d5f46a4d9ffeabdcdcc3e949cbe8c85ffbb8f001a |
The Developer Preview Build of the Kasm Smart Card Bridge service listed above should be used only with the developer preview build of Kasm Workspaces on non-production systems.
The documentation on this page applies to the latest version of the installer listed in the table above. It may not be accurate for older versions.
Upgrade or uninstall the native client
To upgrade an existing installation, run the installer on a machine that already has the Kasm Smart Card Bridge. The installer detects the existing version and performs an upgrade.
Close all browser windows before you upgrade the Kasm Smart Card Bridge.
To uninstall the native client, follow the steps for your operating system.
- Windows
- macOS
To remove the Kasm Smart Card Bridge, open Add or remove programs, select Kasm Smartcard Bridge, then select Uninstall.
A dialog box asks you to confirm the removal. Click OK to continue.
Remove the folder and file manually, or run the uninstaller:
Folder: /Library/Application Support/Kasm/Smart Card Bridge
File: /Library/Google/Chrome/NativeMessagingHosts/com.kasm.smartcard.json
Uninstaller: Kasm_Smart_Card_Bridge_Uninstaller
Configure logging for troubleshooting
By default, the native client writes only warning and error messages to the Windows event log (under Applications->KasmSmartcardBridge) or the macOS syslog. It writes all log messages to log files on the local machine.
- Windows
- macOS
Log file path: %APPDATA%\Kasm\Smart Card Bridge\logs\kasm_scard_bridge.log Alternative log file path: C:\temp\kasm-logs\kasm_scard_bridge.log
Log file path: ~/Library/Logs/Kasm Smart Card Bridge/kasm_scard_bridge.log Alternative log file path: /tmp/kasm-logs/kasm_scard_bridge.log
The native client uses the alternative log file path when it cannot write to the normal log path. This usually happens when the Smart Card Bridge lacks write permissions to the desired folder.
The native client generates a new log file each time the Smart Card Bridge launches, or when the active log file reaches 10 MB. The system keeps a maximum of four log files. Once it reaches this limit, the Smart Card Bridge overwrites the oldest log file, so it retains only the four most recent log files.
To redirect logs to a specific file, set the log_file parameter in config.yaml. Logs are also sent to the Kasm Workspaces deployment. Search them in the Kasm Admin UI under Diagnostics->Logging.
Common troubleshooting steps
- The Windows install fails partway through. During installation, the installer adds a path to a config file at
HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\KasmSmartCardBridgein the Windows Registry. Endpoint security software that blocks installers from editing the Windows Registry can cause the install to fail. Allow the installer to edit the registry, then run it again. - An upgrade does not take effect. Close all browser windows before you run the installer, so the existing Smart Card Bridge is not in use during the upgrade.
- Logs do not appear at the expected path. The native client falls back to the alternative log file path when it cannot write to the normal path. Confirm that the Smart Card Bridge has write permissions to the log folder.
- The developer preview build behaves unexpectedly. Use the developer preview build only with the developer preview build of Kasm Workspaces on non-production systems. For production, use the installer version that matches your installed release.