Skip to main content
Version: Developer

Smart card passthrough

Overview​

Many enterprise workflows depend on a physical smart card for PIN authentication, digital signing, and certificate-based operations. This guide enables smart card passthrough in Kasm Workspaces so that a user's physical smart card reaches both RDP-based Windows sessions and containerized workspaces. As a result, users authenticate and sign with their own credentials inside a streamed workspace, without the card ever leaving their local device.

Video tutorial​

Prerequisites​

Before you begin, confirm the following:

  • Administrator access to the Kasm Workspaces deployment, with permission to manage Group Settings.
  • The allow_kasm_smart_card_passthrough Group Setting set to true for the groups whose users require passthrough. This setting applies to both RDP-based and container-based workspaces.
  • A physical smart card and reader, with the manufacturer-provided drivers, middleware, and certificates installed on the user's local device.
  • For RDP-based Windows sessions, the same manufacturer-provided drivers, middleware, and certificates installed on the target Windows environment.
  • A supported client platform. Windows and macOS use the Kasm Native Smartcard Client. ChromeOS uses the Google Smart Card Connector App and the DriveLock Smart Card Middleware (CSSI).

Solution approach​

This guide progresses through the following phases:

  1. Enable smart card passthrough in Kasm Workspaces.
  2. Configure passthrough for RDP-based Windows sessions.
  3. Configure passthrough for container-based workspaces.
  4. Install and verify the Kasm Native Smartcard Client.

Detailed steps​

Enable smart card passthrough in Kasm Workspaces​

Smart card passthrough is gated by a single Group Setting that applies to every session type.

  1. In the Kasm Workspaces UI, open the Group Settings for the relevant group.
  2. Set the allow_kasm_smart_card_passthrough Group Setting to true.
  3. Apply this setting before users launch any session that requires smart card passthrough, including both container-based and RDP-based workspaces.

Configure passthrough for RDP-based Windows sessions​

RDP-based passthrough reaches a Windows session through either the web native client in the browser or a local RDP client. Prepare the target Windows environment first.

  1. Install the manufacturer-provided drivers, middleware, and certificates for the smart card readers and smart cards on the target Windows environment.

Web native client​

The web native client passes the smart card to the Windows session directly from the browser. Use the tab that matches the user's local operating system.

  1. Confirm the allow_kasm_smart_card_passthrough Group Setting is set to true.
  2. Download and install the Kasm Native Smartcard Client. Follow the instructions in the Kasm Native Smartcard Client section below.
  3. Install the Kasm Workspaces Smart Card Extension from the Chrome Web Store.
  4. Launch a Kasm session.
  5. The smart card is detected automatically and made available to applications within the session.

The web native client extends the Guacamole protocol to carry smart card operations. The implementation uses the Remote Desktop Protocol smart card channel to transmit operations securely between the client and the remote Windows system. The implementation is PC/SC (Personal Computer/Smart Card) compliant. Available functions are limited to the functionality the ChromeOS Smart Card Connector App provides. An application that calls a PC/SC function unsupported on ChromeOS receives an S_CARD_E_UNSUPPORTED error code, per the PC/SC standard.

Smart card passthrough also emulates cache-related functionality that is normally part of the Windows platform. For security reasons, the corresponding PC/SC functions (SCardReadCache and SCardWriteCache) run in the Chrome extension rather than on the server. This approach keeps sensitive cached smart card data local to the user's browser.

RDP local client​

A local RDP client passes the smart card through its own implementation of the feature. Capabilities and limitations therefore depend on that specific RDP client.

Configure passthrough for container-based workspaces​

Container-based workspaces support smart card passthrough by creating a virtual smart card reader within the container. This virtual reader forwards commands to the physical smart card connected to the user's device through the Kasm Smartcard Chrome extension. The implementation maintains full container isolation. It requires no privileged container access and no external host mounts.

note

For performance reasons, disconnecting the reader or card takes effect immediately within the container. An inserted card might be detected with a slight delay, no longer than 2 to 3 seconds.

To enable this feature, complete the following steps:

  1. Confirm the allow_kasm_smart_card_passthrough Group Setting is set to true before launching the session.
  2. Install the required components for the user's operating system.
  1. Download and install the Kasm Native Smartcard Client. Follow the instructions in the Kasm Native Smartcard Client section below.
  2. Install the Kasm Workspaces Smart Card Extension from the Chrome Web Store.
  1. Launch a container-based Kasm session.
  2. Confirm the live smart card passthrough status. The status is visible under Control Panel > Smartcard Passthrough.
  3. The smart card is detected automatically and made available to applications within the container.

Technical implementation​

Container-based smart card passthrough uses a multi-component architecture. The architecture maintains container security through virtual device emulation:

  • PC/SC Daemon (pcscd) runs within the container to provide standard PC/SC services.
  • VPCD (Virtual PC/SC Device) creates a virtual smart card reader named "Kasm Remote Smartcard". This reader appears as a standard PC/SC reader to applications within the container.
  • Kasm Smartcard Bridge (kasm_smartcard_bridge) acts as a VPCD server. It translates between the VPCD protocol and the KasmVNC relay protocol.
  • Kasm Web App coordinates communication between the browser and the container.
  • Kasm Chrome Extension communicates with either the native client (Windows and macOS) or the ChromeOS exposed APIs directly.
  • Kasm Native Smartcard Client interfaces with the physical smart card reader on Windows and macOS.

This architecture allows applications to use standard PC/SC APIs without privileged container access or host system mounts. The communication flow is: Container Applications → PC/SC Daemon → VPCD ("Kasm Remote Smartcard") → Smartcard Bridge → KasmVNC Relay → Web App → Chrome Extension → Native Client/ChromeOS APIs → Physical Reader.

Kasm Native Smartcard Client​

The Kasm Native Smartcard Client is a native host application. It enables smart card functionality for container-based workspaces by bridging communication between the browser extension and local smart card readers on Windows and macOS systems.

Installation​

Install the client on the user's local device using the package for their operating system.

  1. Download and run the .msi installer package.
  2. The installer places the application in C:\Program Files\Kasm\Smart Card Bridge\ and registers it with Chrome for native messaging.

Verification​

To verify the native client is working, complete the following steps:

  1. Open chrome://extensions/ in the browser.
  2. Find the Kasm Workspaces Smart Card Extension.
  3. Click background page under the extension.
  4. Look for the following messages in the console:
Initializing smartcard native client...
Smartcard native client initialized

Common troubleshooting steps​

The following sections cover the most likely failure modes for each session type.

Web native client​

Confirm the following before deeper diagnosis:

  1. The smart card reader is connected properly.
  2. The allow_kasm_smart_card_passthrough Group Setting is enabled.
  3. The Google Smart Card Connector App Chrome extension is enabled.
  4. The DriveLock Smart Card Middleware (CSSI) Chrome extension is enabled.
  5. The Kasm Workspaces Smart Card Extension is enabled.
  6. The drivers, middleware, and certificates required by the smart card and reader manufacturers are installed on the system.
  7. If the smart card appears unresponsive, remove and reinsert the card.

If issues continue, use the following client-side tools:

  1. Open chrome://extensions and inspect the Kasm Workspaces Smart Card Extension service worker for detailed logs about client-side smart card operations.
  2. Check the native client detailed logs at the path for the operating system.

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

note

The alternative log file path is used when the native client cannot write to the normal log path. This is usually due to the native client not having write permissions to the desired folder.

note

A new log file is generated each time the native client launches, or when the active log file reaches 10 MB. The system retains a maximum of four log files. Once this limit is reached, the native client overwrites the oldest log file, so only the four most recent log files are retained.

Use the following server-side checks:

  1. Check the kasm_guac container logs for smart card related messages.
  2. Look for a Registering smartcard container log message to confirm smart card support was enabled for the session.

Use the following diagnostic tools inside the Windows session:

  1. Open Command Prompt or PowerShell in the Windows session.
  2. Run certutil -scinfo to get detailed information about connected smart card readers and cards. This tool helps identify whether Windows recognizes the smart card hardware.

For certificate-enabled smart cards, verify the certificate:

  1. Verify the certificate is recognized:
    • Press Win + R, type certmgr.msc, and press Enter.
    • In the left pane, expand Personal > Certificates.
    • Look for a certificate issued by the smart card's Certificate Authority.
  2. If the client certificate is missing, verify the required configuration entries in the Windows registry at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards for the smart card. Missing entries can prevent proper smart card certificate propagation and affect smart card functionality.

RDP local client​

Confirm the following before deeper diagnosis:

  1. The smart card reader is connected properly.
  2. The allow_kasm_smart_card_passthrough Group Setting is enabled.
  3. The drivers, middleware, and certificates required by the smart card and reader manufacturers are installed on the system.
  4. If the smart card appears unresponsive, remove and reinsert the card.

If issues continue, consult the documentation and troubleshooting guides for the RDP client.

Use the following diagnostic tools inside the Windows session:

  1. Open Command Prompt or PowerShell in the Windows session.
  2. Run certutil -scinfo to get detailed information about connected smart card readers and cards. This tool helps identify whether Windows recognizes the smart card hardware.

Container-based workspaces​

Confirm the following before deeper diagnosis:

  1. The smart card reader is connected properly.
  2. The allow_kasm_smart_card_passthrough Group Setting is enabled.
  3. The Kasm Native Smartcard Client is installed and running.
  4. The Kasm Workspaces Smart Card Extension is enabled.
  5. The smart card status under Control Panel > Smartcard Passthrough confirms the status of each component (extension, reader, and card).
  6. The container has smart card support enabled (KASM_SVC_SMARTCARD=1).
  7. If the smart card appears unresponsive, remove and reinsert the card.

Use the following client-side checks:

  1. Check the smart card status under Control Panel > Smartcard Passthrough to verify the status of each component (extension, reader, and card).
  2. Open chrome://extensions and inspect the Kasm Workspaces Smart Card Extension service worker for detailed logs about client-side smart card operations.
  3. Verify the native client is running in the system process list.

Use the following container-side checks:

  1. Check the container logs for smart card related errors (pcscd and bridge).
  2. Check whether the PC/SC daemon is running: docker exec CONTAINER_ID ps aux | grep pcscd
  3. Check whether the smart card bridge is running: docker exec CONTAINER_ID ps aux | grep kasm_smartcard_bridge
  4. Test PC/SC connectivity within the container: docker exec CONTAINER_ID opensc-tool -l -a

Use the following diagnostic tools:

  1. List available readers within the container: docker exec CONTAINER_ID opensc-tool --list-readers
  2. Verify the card is detected: docker exec CONTAINER_ID opensc-tool --atr
  3. Verify card data transmission works: docker exec CONTAINER_ID opensc-tool --serial
  4. List certificates on the card: docker exec CONTAINER_ID pkcs15-tool --list-certificate