Product Documentation

Configure smart card authentication

May 22, 2017

This article gives an overview of the tasks involved in setting up smart card authentication for all the components in a typical StoreFront deployment. For more information and step-by-step configuration instructions, see the documentation for the individual products.  

pdf

Smart card configuration for Citrix environments

This overview for configuring a Citrix deployment for smart cards uses a specific smart card type. Note that similar steps apply to smart cards from other vendors.

Prerequisites

  • Ensure that accounts for all users are configured either within the Microsoft Active Directory domain in which you plan to deploy your StoreFront servers or within a domain that has a direct two-way trust relationship with the StoreFront server domain.
  • If you plan to enable pass-through with smart card authentication, ensure that your smart card reader types, middleware type and configuration, and middleware PIN caching policy permit this.
  • Install your vendor's smart card middleware on the virtual or physical machines running the Virtual Delivery Agent that provide users' desktops and applications. For more information about using smart cards with XenDesktop, see Smart cards.
  • Before continuing, ensure that your public-key infrastructure is configured appropriately. Check that certificate to account mapping is configured correctly for your Active Directory environment and that user certificate validation can be performed successfully.

Configure NetScaler Gateway

  • On your NetScaler Gateway appliance, install a signed server certificate from a certification authority. For more information, see Installing and Managing Certificates.
  • Install on your appliance the root certificate of the certification authority issuing your smart card user certificates. For more information, see To install a root certificate on NetScaler Gateway.
  • Create and configure a virtual server for client certificate authentication. Create a certificate authentication policy, specifying SubjectAltName:PrincipalName for user name extraction from the certificate. Then, bind the policy to the virtual server and configure the virtual server to request client certificates. For more information, see Configuring and Binding a Client Certificate Authentication Policy.
  • Bind the certification authority root certificate to the virtual server. For more information, see To add a root certificate to a virtual server.
  • To ensure that users do not receive an additional prompt for their credentials at the virtual server when connections to their resources are established, create a second virtual server. When you create the virtual server, disable client authentication in the Secure Sockets Layer (SSL) parameters. For more information, see Configuring smart card authentication.

    You must also configure StoreFront to route user connections to resources through this additional virtual server. Users log on to the first virtual server and the second virtual server is used for connections to their resources. When the connection is established, users do not need to authenticate to NetScaler Gateway but are required to enter their PINs to log on to their desktops and applications. Configuring a second virtual server for user connections to resources is optional unless you plan to enable users to fall back to explicit authentication if they experience any issues with their smart cards.

  • Create session policies and profiles for connections from NetScaler Gateway to StoreFront and bind them to the appropriate virtual server. For more information, see Access to StoreFront Through NetScaler Gateway.
  • If you configured the virtual server used for connections to StoreFront to require client certificate authentication for all communications, you must create a further virtual server to provide the callback URL for StoreFront. This virtual server is used only by StoreFront to verify requests from the NetScaler Gateway appliance and so does not need to be publically accessible. A separate virtual server is required when client certificate authentication is mandatory because StoreFront cannot present a certificate to authenticate. For more information, see Creating Virtual Servers.

Configure StoreFront

  • You must use HTTPS for communications between StoreFront and users' devices to enable smart card authentication. Configure Microsoft Internet Information Services (IIS) for HTTPS by obtaining an SSL certificate in IIS and then adding HTTPS binding to the default website. For more information about creating a server certificate in IIS, see http://technet.microsoft.com/en-us/library/hh831637.aspx#CreateCertificate. For more information about adding HTTPS binding to an IIS site, see http://technet.microsoft.com/en-us/library/hh831632.aspx#SSLBinding.
  • If you want to require that client certificates are presented for HTTPS connections to all StoreFront URLs, configure IIS on the StoreFront server.

    When StoreFront is installed, the default configuration in IIS only requires that client certificates are presented for HTTPS connections to the certificate authentication URL of the StoreFront authentication service. This configuration is required to provide smart card users with the option to fall back to explicit authentication and, subject to the appropriate Windows policy settings, enable users to remove their smart cards without needing to reauthenticate.

    When IIS is configured to require client certificates for HTTPS connections to all StoreFront URLs, smart card users cannot connect through NetScaler Gateway and cannot fall back to explicit authentication. Users must log on again if they remove their smart cards from their devices. To enable this IIS site configuration, the authentication service and stores must be collocated on the same server, and a client certificate that is valid for all the stores must be used. Moreover, this configuration where IIS is requiring client certificates for HTTPS connections to all StoreFront URLs, will conflict with authentication for Citrix Receiver for Web clients. For this reason, this configuration should be used when Citrix Receiver for Web client access is not required.

    If you are installing StoreFront on Windows Server 2012, note that non-self-signed certificates installed in the Trusted Root Certification Authorities certificate store on the server are not trusted when IIS is configured to use SSL and client certificate authentication. For more information about this issue, see http://support.microsoft.com/kb/2802568.

  • Install and configure StoreFront. Create the authentication service and add your stores, as required. If you configure remote access through NetScaler Gateway, do not enable virtual private network (VPN) integration. For more information, see Install and set up StoreFront.
  • Enable smart card authentication to StoreFront for local users on the internal network. For smart card users accessing stores through NetScaler Gateway, enable the pass-through with NetScaler Gateway authentication method and ensure that StoreFront is configured to delegate credential validation to NetScaler Gateway. If you plan to enable pass-through authentication when you install Citrix Receiver for Windows on domain-joined user devices, enable domain pass-through authentication. For more information, see Configure the authentication service.

    To allow Citrix Receiver for Web client authentication with smart cards, you must enable the authentication method per Citrix Receiver for Web site. For more information, see the Configure Citrix Receiver for Web sites instruction.

    If you want smart card users to be able to fall back to explicit authentication if they experience any issues with their smart cards, do not disable the user name and password authentication method. 

  • If you plan to enable pass-through authentication when you install Citrix Receiver for Windows on domain-joined user devices, edit the default.ica file for the store to enable pass-through of users' smart card credentials when they access their desktops and applications. For more information, see Enable pass-through with smart card authentication for Citrix Receiver for Windows.
  • If you created an additional NetScaler Gateway virtual server to be used only for user connections to resources, configure optimal NetScaler Gateway routing through this virtual server for connections to the deployments providing the desktops and applications for the store. For more information, see Configure optimal HDX routing for a store.
  • To enable users of non-domain-joined Windows desktop appliances to log on to their desktops using smart cards, enable smart card authentication to your Desktop Appliance sites. For more information, see Configure Desktop Appliance sites.

Configure the Desktop Appliance site for both smart card and explicit authentication to enable users to log on with explicit credentials if they experience any issues with their smart cards.

  • To enable users of domain-joined desktop appliances and repurposed PCs running the Citrix Desktop Lock to authenticate using smart cards, enable pass-through with smart card authentication to your XenApp Services URLs. For more information, see Configure authentication for XenApp Services URLs.

Configure user devices

  • Ensure that your vendor's smart card middleware is installed on all user devices.
  • For users with non-domain-joined Windows desktop appliances, install Receiver for Windows Enterprise using an account with administrator permissions. Configure Internet Explorer to start in full-screen mode displaying the Desktop Appliance site when the device is powered on. Note that Desktop Appliance site URLs are case sensitive. Add the Desktop Appliance site to the Local intranet or Trusted sites zone in Internet Explorer. Once you have confirmed that you can log on to the Desktop Appliance site with a smart card and access resources from the store, install the Citrix Desktop Lock. For more information, see To install the Desktop Lock.
  • For users with domain-joined desktop appliances and repurposed PCs, install Receiver for Windows Enterprise using an account with administrator permissions. Configure Receiver for Windows with the XenApp Services URL for the appropriate store. Once you have confirmed that you can log on to the device with a smart card and access resources from the store, install the Citrix Desktop Lock. For more information, see To install the Desktop Lock.
  • For all other users, install the appropriate version of Citrix Receiver on the user device. To enable pass-through of smart card credentials to XenDesktop and XenApp for users with domain-joined devices, use an account with administrator permissions to install Receiver for Windows at a command prompt with the /includeSSON option. For more information, see Configure and install Receiver for Windows using command-line parameters.

    Ensure that Receiver for Windows is configured for smart card authentication either through a domain policy or a local computer policy. For a domain policy, use the Group Policy Management Console to import the Receiver for Windows Group Policy Object template file, icaclient.adm, onto the domain controller for the domain containing your users' accounts. To configure an individual device, use the Group Policy Object Editor on that device to configure the template. For more information, see Configure Receiver with the Group Policy Object template.

    Enable the Smart card authentication policy. To enable pass-through of users' smart card credentials, select Use pass-through authentication for PIN. Then, to pass users' smart card credentials through to XenDesktop and XenApp, enable the Local user name and password policy and select Allow pass-through authentication for all ICA connections. For more information, see ICA Settings Reference.

    If you enabled pass-through of smart card credentials to XenDesktop and XenApp for users with domain-joined devices, add the store URL to the Local intranet or Trusted sites zone in Internet Explorer. Ensure that Automatic logon with the current user name and password is selected in the security settings for the zone.

  • Where necessary, provide users with connection details for the store (for users on the internal network) or NetScaler Gateway appliance (for remote users) using an appropriate method. For more information about providing configuration information to your users, see Citrix Receiver.

Enable pass-through with smart card authentication for Receiver for Windows

You can enable pass-through authentication when you install Receiver for Windows on domain-joined user devices. To enable pass-through of users' smart card credentials when they access desktops and applications hosted by XenDesktop and XenApp, you edit the default.ica file for the store.

Important: In multiple server deployments, use only one server at a time to make changes to the configuration of the server group. Ensure that the Citrix StoreFront management console is not running on any of the other servers in the deployment. Once complete, propagate your configuration changes to the server group so that the other servers in the deployment are updated.
  1. Use a text editor to open the default.ica file for the store, which is typically located in the C:\inetpub\wwwroot\Citrix\storename\App_Data\ directory, where storename is the name specified for the store when it was created.
  2. To enable pass-through of smart card credentials for users who access stores without NetScaler Gateway, add the following setting in the [Application] section.
    DisableCtrlAltDel=Off
    

    This setting applies to all users of the store. To enable both domain pass-through and pass-through with smart card authentication to desktops and applications, you must create separate stores for each authentication method. Then, direct your users to the appropriate store for their method of authentication.

  3. To enable pass-through of smart card credentials for users accessing stores through NetScaler Gateway, add the following setting in the [Application] section.
    UseLocalUserAndPassword=On
    

    This setting applies to all users of the store. To enable pass-through authentication for some users and require others to log on to access their desktops and applications, you must create separate stores for each group of users. Then, direct your users to the appropriate store for their method of authentication.