docs: add desktop troubleshooting step to check for conflicting softw…

…are (#41427)

Some third-party security tools override the default Microsoft smart
card driver with custom software. These custom drivers can prevent
Windows from reading certificates from Teleport's virtual smart card,
which prevents the automatic logon process from completing.

docs/cspell.json

@@ -18,6 +18,7 @@
     "AWSARN",
     "AWSIIDTTL",
     "Aarch",
+    "Activ",
     "Addrs",
     "Afax",
     "Aqxs",
@@ -586,6 +587,7 @@
     "mongosh",
     "mpghq",
     "msapi",
+    "msclmd",
     "mspan",
     "msprod",
     "msteams",

docs/pages/desktop-access/troubleshooting.mdx

@@ -32,6 +32,49 @@ If the "Smart Card" service is not running, open PowerShell and run
 `gpupdate.exe /force`. This forces a Group Policy sync and should pick up the
 service changes.
 
+### Smart card PIN not detected
+
+Teleport uses a cryptographically secure random number generator to generate
+a smart card PIN for each new desktop session. In order to prevent the smart
+card certificate from being used for any purpose other than the initial login,
+this PIN is never shared with the Teleport user.
+
+Teleport provides this PIN to the desktop during the RDP connection phase.
+If your group policy prevents the desktop from seeing this PIN, the user will
+remain at the login screen even though the smart card was detected.
+
+**Solution:** Ensure that group policy allows specifying credentials during
+RDP connection establishment.
+
+Expand Computer Configuration, Administrative Templates, Windows Components,
+Remote Desktop Services, and Remote Desktop Session Host.
+
+Under Remote Desktop Session Host, select **Security**.
+
+Right-click **Always prompt for password upon connection**, select **Edit**,
+select **Disabled**, then click **OK**.
+
+Note: despite mention of passwords in the name of this policy, no passwords are
+sent on the wire. This mechanism is used only to send the smart card PIN.
+
+### Third-party smart card drivers prevent automatic login
+
+Some third-party smart card drivers such as HID ActivID ActivClient may prevent
+the automatic login process from working correctly. To check for the presence of
+third-party drivers, connect to the host where automatic logon is not working
+and view the contents of the
+`Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards\Identity Device (NIST SP 800-73 [PIV])`
+entry.
+
+On a correctly configured system, you expect to see an entry pointing at a DLL
+for the default Windows driver: `C:\Windows\System32\msclmd.dll`. On a system
+with custom drivers installed, you will typically see this path overridden to
+point to a DLL under `C:\Program Files`.
+
+**Solution:** Disable or uninstall any third party smart card tools that may be
+interfering with the logon process. Ensure that the registry entry mentioned
+above points to `msclmd.dll` after completing the uninstall.
+
 ### Smart card not supported for Account
 
 You connect to a Windows host and get the error message: **"Signing in with a smart card
@@ -69,31 +112,6 @@ If that doesn't help, log into the target host directly, open PowerShell and
 run `gpupdate.exe /force`. This forces a Group Policy update and should pick up
 the new CA.
 
-### Smart card PIN not detected
-
-Teleport uses a cryptographically secure random number generator to generate
-a smart card PIN for each new desktop session. In order to prevent the smart
-card certificate from being used for any purpose other than the initial login,
-this PIN is never shared with the Teleport user.
-
-Teleport provides this PIN to the desktop during the RDP connection phase.
-If your group policy prevents the desktop from seeing this PIN, the user will
-remain at the login screen even though the smart card was detected.
-
-**Solution:** Ensure that group policy allows specifying credentials during
-RDP connection establishment.
-
-Expand Computer Configuration, Administrative Templates, Windows Components,
-Remote Desktop Services, and Remote Desktop Session Host.
-
-Under Remote Desktop Session Host, select **Security**.
-
-Right-click **Always prompt for password upon connection**, select **Edit**,
-select **Disabled**, then click **OK**.
-
-Note: despite mention of passwords in the name of this policy, no passwords are
-sent on the wire. This mechanism is used only to send the smart card PIN.
-
 ## New session "hangs"
 
 ### Host unreachable