Skip to main content
Version: Developer

FIDO2 security key passthrough

Overview​

Phishing-resistant sign-in increasingly depends on a physical FIDO2 security key, such as a YubiKey, rather than a password. This guide enables FIDO2 security key passthrough for container-based Kasm Workspaces, so a WebAuthn ceremony started inside a streamed workspace reaches the user's physical security key. As a result, users complete WebAuthn registration and sign-in from inside an isolated container while the key's cryptographic material and raw USB/HID access stay on the user's local device.

note

FIDO2 security key passthrough is distinct from Kasm Workspaces' existing allow_webauthn_2fa setting, which lets a user register a security key as a two-factor authentication method for signing in to Kasm Workspaces itself. This guide covers passing a physical security key through to applications running inside a workspace.

caution

FIDO2 security key passthrough is under active development. It becomes available for external testing in the Kasm Workspaces 1.20.0 rolling images once the underlying components merge into the develop branches. It is not available in any static or generally available release yet. Confirm current availability before relying on this guide in production.

note

FIDO2 security key passthrough currently supports only the ES256 (ECDSA with P-256 and SHA-256) COSE algorithm for WebAuthn ceremonies. A relying party that requires a different algorithm, such as EdDSA or RS256, does not complete registration or sign-in through passthrough yet.

For forwarding the user's local SSH agent and keys instead of a security key, see SSH-agent passthrough.

Prerequisites​

Before you begin, confirm the following:

  • Kasm Workspaces 1.20.0 or later.
  • A container-based Kasm Workspaces workspace built from a workspace image with FIDO2 support installed.
  • Administrator access to the Kasm Workspaces deployment, with permission to manage Group Settings.
  • A supported client platform: Windows or macOS, with the Kasm Native Smartcard Client installed. FIDO2 passthrough reuses the same native client used for smart card passthrough.
  • The Kasm-provided browser extension that carries FIDO2 requests to the native client. Confirm with your Kasm representative which extension build and installation source apply to your release, because distribution for this capability is still being finalized.
  • A physical security key that supports FIDO2/CTAP2 or U2F, connected to the user's local device.

Solution approach​

This guide progresses through the following phases:

  1. Enable FIDO2 passthrough for user groups.
  2. Install the Kasm Native Smartcard Client and browser extension on the user's device.
  3. Verify FIDO2 security key passthrough.

Detailed steps​

Enable FIDO2 passthrough for user groups​

The allow_kasm_webauthn_passthrough Group Setting controls FIDO2 passthrough, independent of smart card passthrough. The setting is disabled by default and applies only to container-based workspaces. RDP sessions use the separate allow_kasm_rdp_webauthn_passthrough setting.

  1. In the Kasm Workspaces UI, open the Group Settings for the relevant group.
  2. Set the allow_kasm_webauthn_passthrough Group Setting to true.
  3. Apply this setting before users launch any session that requires FIDO2 passthrough. The setting takes effect the next time a user in the group launches a session.

The Group Setting sets the KASM_SVC_FIDO2 environment variable on the user's session container. When a Session Casting configuration has Enforce Client Settings enabled, its Allow Kasm WebAuthn Passthrough option overrides the Group Setting for sessions launched from that casting link. For Session Staging, enable Allow WebAuthn Passthrough on the staging configuration so that staged sessions match the users who require passthrough.

caution

Setting KASM_SVC_FIDO2=1 in a Workspace's Docker Run Config Override also enables FIDO2 passthrough. That environment variable takes precedence over the Group Setting, so it enables passthrough for every user who launches the Workspace, regardless of group membership. Use the Group Setting to control access by group.

Install the Kasm Native Smartcard Client and browser extension​

  1. Download and install the Kasm Native Smartcard Client. Follow the instructions in the Kasm Native Smartcard Client section of the smart card passthrough guide.
  2. Install the Kasm-provided browser extension build that supports FIDO2 passthrough for your release.
  3. Launch a container-based Kasm session as a user whose group has allow_kasm_webauthn_passthrough enabled.

If the user already has the native client installed and up to date for smart card passthrough, no additional native client installation is required.

Verify FIDO2 security key passthrough​

  1. Insert the physical security key into the user's local device before starting the WebAuthn ceremony.
  2. Inside the workspace, open a site that prompts for a security key, such as a WebAuthn registration or sign-in page.
  3. Confirm the browser inside the workspace surfaces a security key prompt, and that touching the physical key completes the ceremony.
  4. On Windows, confirm the native security key prompt from webauthn.dll appears rather than a raw USB dialog. This confirms the native client is using the native Windows WebAuthn API.

Technical implementation​

Container-based FIDO2 passthrough extends the same multi-component architecture as container-based smart card passthrough: a native client on the user's device, a browser extension in the client-side browser, a KasmVNC relay between the browser and the container, and a bridge process inside the container.

  • Kasm-provided browser extension (client-side) relays ctap_make_credential, ctap_get_assertion, and ctap_list_devices requests to the native client over Chrome native messaging.
  • Kasm Native Smartcard Client (kasm_smart_card_bridge) performs the CTAP2 ceremony against the physical key. On macOS, it uses libfido2. On Windows, it calls the native webauthn.dll API rather than raw USB/HID access, which avoids a FIDO_ERR_INTERNAL failure that raw USB/HID access can produce on Windows.
  • KasmVNC carries the request and response between the browser and the container over a dedicated relay channel, as an opaque pass-through.
  • Kasm FIDO2 bridge (kasm_fido2_bridge, inside the container) forwards WebAuthn-level requests to the KasmVNC relay and returns the response. It has no PC/SC or virtual smart card reader concept, unlike smart card passthrough.

The communication flow is: workspace browser (WebAuthn call) → Kasm FIDO2 bridge → KasmVNC relay → Kasm-provided browser extension → Kasm Native Smartcard Client → physical security key.

Common troubleshooting steps​

Confirm the following before deeper diagnosis:

  • The allow_kasm_webauthn_passthrough Group Setting is set to true for one of the user's groups.
  • If the session came from a Session Casting configuration with Enforce Client Settings enabled, Allow Kasm WebAuthn Passthrough is enabled on that configuration.
  • The Kasm Native Smartcard Client is installed and running on the user's device.
  • The Kasm-provided browser extension is enabled in the client-side browser.
  • The physical security key is connected before the ceremony starts.

If FIDO2 passthrough fails:

  1. On Windows, confirm webauthn.dll is available. Earlier Windows builds fall back to raw USB/HID access through libfido2 and are more likely to surface FIDO_ERR_INTERNAL.
  2. Open chrome://extensions, inspect the extension's service worker, and look for ctap_make_credential or ctap_get_assertion errors.
  3. Check the native client log for the user's operating system, at the same log paths used for smart card passthrough.