Configure smart card authentication

Citrix Workspace app for Windows supports the following smart card authentication:

  • Pass-through authentication (Single Sign-on) - Pass-through authentication captures smart card credentials when users log on to Citrix Workspace app. Citrix Workspace app uses the captured credentials as follows:

    • Users of domain-joined devices who log on to Citrix Workspace app with smart card credentials can start virtual desktops and applications without needing to reauthenticate.
    • Citrix Workspace app running on non-domain joined devices with smart card credentials must type their credentials again to start a virtual desktop or application.

Pass-through authentication requires configuration both on StoreFront and Citrix Workspace app.

  • Bimodal authentication - Bimodal authentication offers users a choice between using a smart card and typing the user name and password. This feature is effective when you cannot use the smart card, For example, the log on certificate has expired. Dedicated stores must be setup per site to allow Bimodal authentication, using the DisableCtrlAltDel method set to False to allow smart cards. Bimodal authentication requires StoreFront configuration. If Citrix Gateway is present in the solution, is also requires configuration.

    Using the Bimodal authentication, StoreFront administrator can allow the user both user name and password and smart card authentication to the same store by selecting them in the StoreFront console. See StoreFront documentation.

  • Multiple certificates - Multiple certificates can be available for a single smart card and if multiple smart cards are in use. When you insert a smart card in a card reader, the certificates are applicable to all applications running on the user device, including Citrix Workspace app.

  • Client certificate authentication - Client certificate authentication requires Citrix Gateway and StoreFront configuration.

    • For access to StoreFront through Citrix Gateway, you might have to reauthenticate after removing a smart card.
    • When the Citrix Gateway SSL configuration is set to mandatory client certificate authentication, operation is more secure. However mandatory client certificate authentication is not compatible with bimodal authentication.
  • Double hop sessions -If a double-hop is required, a connection is established between Citrix Workspace app and the user’s virtual desktop. Deployments supporting double hops are described in the Citrix Virtual Apps and Desktops documentation.

  • Smart card-enabled applications - Smart card-enabled applications, such as Microsoft Outlook and Microsoft Office, allow users to digitally sign or encrypt documents available in Citrix Virtual Apps and Desktops sessions.

Limitations

  • Certificates must be stored on a smart card and not on the user device.
  • Citrix Workspace app does not save the choice of the user certificate, but stores the PIN when configured. The PIN is cached in non-paged memory only during the user session and is not stored on the disk.
  • Citrix Workspace app does not reconnect to a session when a smart card is inserted.
  • When configured for smart card authentication, Citrix Workspace app does not support virtual private network (VPN) single-sign on or session pre-launch. To use VPN with smart card authentication, install the Citrix Gateway Plug-in and log on through a webpage, using their smart cards and PINs to authenticate at each step. Pass-through authentication to StoreFront with the Citrix Gateway Plug-in is not available for smart card users.
  • Citrix Workspace app Updater communications with citrix.com and the Merchandising Server are not compatible with smart card authentication on Citrix Gateway.

Warning

Some configuration require registry edits. Using Registry editor incorrectly might cause problems that can require you to reinstall the operating system. Citrix cannot guarantee that problems resulting from incorrect use of Registry Editor can be solved. Ensure you back up the registry before you edit it.

To enable Single Sign-on for smart card authentication

To configure Citrix Workspace app for Windows, include the following command-line option during installation:

  • ENABLE\_SSON=Yes

    Single sign-on is another term for pass-through authentication. Enabling this setting prevents Citrix Workspace app from displaying a second prompt for a PIN.

  • Set SSONCheckEnabled to false if the Single Sign-on component is not installed. The key prevents the Citrix Workspace app authentication manager from checking for the Single Sign-on component, thus allowing Citrix Workspace app to authenticate to StoreFront.

    HKEY_CURRENT_USER\Software\Citrix\AuthManager\protocols\integratedwindows\

    HKEY_LOCAL_MACHINE\Software\Citrix\AuthManager\protocols\integratedwindows\

To enable smart card authentication to StoreFront instead of Kerberos, install Citrix Workspace app for Windows with the command line options below.

  • /includeSSON installs Single Sign-on (pass-through) authentication. Enables credential caching and the use of pass-through domain-based authentication.

  • If the user is logging on to the endpoint with a different method to smart card for Citrix Workspace app for Windows authentication (for example, user name and password), the command line is:

/includeSSON LOGON_CREDENTIAL_CAPTURE_ENABLE=No

This prevents the credentials being captured at logon time and allows Citrix Workspace app to store the PIN when logging on to Citrix Workspace app.

  1. Open the Citrix Workspace app Group Policy Object administrative template by running gpedit.msc.
  2. Go to Administrative Templates > Citrix Components > Citrix Workspace > User Authentication > Local user name and password.
  3. Select Enable pass-through authentication. Depending on the configuration and security settings, select Allow pass-through authentication for all ICA option for pass-through authentication to work.

To configure StoreFront:

  • When you configure the authentication service, select the Smart card check box.

For more information about using smart cards with StoreFront, see Configure the authentication service in the StoreFront documentation.

To enable user devices for smart card use

  1. Import the certificate authority root certificate into the device’s keystore.
  2. Install your vendor’s cryptographic middleware.
  3. Install and configure Citrix Workspace app.

To change how certificates are selected

By default, if multiple certificates are valid, Citrix Workspace app prompts the user to choose a certificate from the list. Alternatively, you can configure Citrix Workspace app to use the default certificate (per the smart card provider) or the certificate with the latest expiry date. If there are no valid logon certificates, the user is notified, and given the option to use an alternate logon method if available.

A valid certificate must have all of these characteristics:

  • The current time of the clock on the local computer is within the certificate validity period.
  • The Subject public key must use the RSA algorithm and have a key length of 1024 bits, 2048 bits, or 4096 bits.
  • Key Usage must contain Digital Signature.
  • Subject Alternative Name must contain the User Principal Name (UPN).
  • Enhanced Key Usage must contain Smart Card log on and Client Authentication, or All Key Usages.
  • One of the Certificate Authorities on the certificate’s issuer chain must match one of the permitted Distinguished Names (DN) sent by the server in the TLS handshake.

Change how certificates are selected by using either of the following methods:

  • On the Citrix Workspace app command line, specify the option AM\_CERTIFICATESELECTIONMODE={ Prompt | SmartCardDefault | LatestExpiry }.

    Prompt is the default. For SmartCardDefault or LatestExpiry, if multiple certificates meet the criteria, Citrix Workspace app prompts the user to choose a certificate.

  • Add the following key value to the registry key HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE\Software\[Wow6432Node\]Citrix\AuthManager: CertificateSelectionMode={ Prompt SmartCardDefault LatestExpiry }.

Values defined in HKEY_CURRENT_USER take precedence over values in HKEY_LOCAL_MACHINE to best assist the user in selecting a certificate.

To use CSP PIN prompts

By default, the PIN prompts presented to users are provided by Citrix Workspace app for Windows rather than the smart card Cryptographic Service Provider (CSP). Citrix Workspace app prompts users to enter a PIN when required and then passes the PIN to the smart card CSP. If your site or smart card has more stringent security requirements, such as to disallow caching the PIN per-process or per-session, you can configure Citrix Workspace app to instead use the CSP components to manage the PIN entry, including the prompt for a PIN.

Change how PIN entry is handled by using either of the following methods:

  • On the Citrix Workspace app command line, specify the option AM\_SMARTCARDPINENTRY=CSP.
  • Add the following key value to the registry key HKEY_LOCAL_MACHINE\Software\[Wow6432Node\]Citrix\AuthManager: SmartCardPINEntry=CSP.