Authenticate

To maximize the security of your environment, the connections between Citrix Workspace app and the resources you publish must be secured. You can configure various types of authentication for your Citrix Workspace app, including domain pass-through, smart card, and Kerberos pass-through.

Domain pass-through authentication

Single Sign-on lets you authenticate to a domain and use the Citrix Virtual Apps and Desktops without having to reauthenticate again.

When you log on to Citrix Workspace app, your credentials are passed through to StoreFront, along with the enumerated apps and desktops and Start menu settings. After configuring single sign-on,you can log on to Citrix Workspace app and launch Citrix Virtual Apps and Desktops sessions without having to retype your credentials.

Note:

Single Sign-on is not supported if Citrix Workspace app is connected to Citrix Virtual Apps and Desktops using Citrix Gateway.

You can configure single sign-on on both fresh installation or upgrade setup, using any of the following options:

  • Command line interface
  • Graphical user interface

Configure single sign-on during fresh installation

To configure single sign-on during fresh installation of Citrix Workspace app, perform the following steps:

  1. Configuration on StoreFront or the Web Interface.
  2. Configure XML trust services on the Delivery Controller.
  3. Modify Internet Explorer settings.
  4. Install Citrix Workspace app with single sign-on.

Configure single sign-on on StoreFront or the Web Interface

Depending on the Citrix Virtual Apps and Desktops deployment, single sign-on authentication can be configured on StoreFront or the Web Interface using the Management Console.

Use the table below for different use case and its respective configuration:

Use case Configuration details Additional information
Configured SSON on StoreFront or Web Interface Launch Citrix Studio, go to Store > Manage Authentication methods > enable Domain pass-through. When Citrix Workspace app is not configured with Single Sign-on, it automatically switches the authentication method from Domain pass-through to Username and Password, if available.
When Workspace for Web is required Launch Store > Workspace for Websites > Manage Authentication methods > enable Domain pass-through. When Citrix Workspace app is not configured with Single Sign-on, it automatically switches the authentication method from Domain pass-through to Username and Password, if available.
When StoreFront is not configured If Web Interface is configured on a Citrix Virtual Apps and Desktops server, launch XenApp Services Sites > Authentication Methods > enable Pass-through. When Citrix Workspace app is not configured with single sign-on, it automatically switches the authentication method from Pass-through to Explicit, if available.

Configure single sign-on with Citrix Gateway

You enable single sign-on with Citrix Gateway using the Group Policy Object administrative template.

  1. Open the Citrix Workspace app GPO administrative template by running gpedit.msc.
  2. Under the Computer Configuration node, go to Administrative Template > Citrix Components > Citrix Workspace > User Authentication.
  3. Select Single Sign-on for Citrix Gateway policy.
  4. Select Enabled.
  5. Click Apply and `OK.
  6. Restart Citrix Workspace app for the changes to take effect.

Configure XML trust services on the Delivery Controller

On Citrix Virtual Apps and Desktops, run the following PowerShell command as an administrator on the Delivery Controller:

asnp Citrix* Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $True

Modify the Internet Explorer settings

  1. Add the StoreFront server to the list of trusted sites using Internet Explorer. To do this:
    1. Launch Internet Explorer.
    2. Select Tools > Internet Options > Security > Local Internet and click Sites. The Local intranet window appears.
    3. Select Advanced.
    4. Add the URL of the StoreFront or Web Interface FQDN with the appropriate HTTP or HTTPS protocols.
    5. Click Apply and OK.
  2. Modify the User Authentication settings in Internet Explorer. To do this:
    1. Launch Internet Explorer.
    2. On the Internet Options > Security tab, click Trusted Sites.
    3. Click Custom level. The Security Settings – Trusted Sites Zone window appears.
    4. In the User Authentication pane, select Automatic logon with current user name and password.

    User authentication

Configure single sign-on using the command line interface

Install Citrix Workspace app for Windows with the /includeSSON switch and restart Citrix Workspace app for the changes to take effect.

Note:

If Citrix Workspace app for Windows is installed without the single sign-on component, upgrading to the latest version of Citrix Workspace app with the /includeSSON switch is not supported.

Configure single sign-on using the graphical user interface

  1. Locate the Citrix Workspace app installation file (CitrixWorkspaceApp.exe).
  2. Double click CitrixWorkspaceApp.exe to launch the installer.
  3. In the Enable Single Sign-on installation wizard, select the Enable Single Sign-on option.
  4. Click Next to complete the installation.

You can now log on to an existing Store (or configure a new Store) using Citrix Workspace app without providing user credentials.

Configure single sign-on on Citrix Workspace for Web

You can configure single sign-on on Workspace for Web using the Group Policy Object administrative template.

  1. Open the Workspace for Web GPO administrative template by running gpedit.msc.
  2. Under the Computer Configuration node, go to Administrative Template > Citrix Component > Workspace for Windows > User Authentication.
  3. Select the Local user name password policy and set it to Enabled.
  4. Click Enable pass-through authentication. This option allows Workspace for Web to use your login credentials for authentication on the remote server.
  5. Click Allow pass-through authentication for all ICA connections. This option bypasses any authentication restriction and allows credentials to pass-through on all the connections.
  6. Click Apply and OK.
  7. Restart the Workspace for Web for the changes to take effect.

Verify that the single sign-on is enabled by launching the Task Manager and check if the ssonsvr.exe process is running.

Configure single sign-on using Active Directory

Complete the following steps to configure Citrix Workspace app for pass-through authentication using Active Directory group policy. In this scenario, you can achieve the single sign-on authentication without using the enterprise software deployment tools, such as Microsoft System Center Configuration Manager.

  1. Download and place the Citrix Workspace app installation file (CitrixWorkspaceApp.exe) on a suitable network share. It must be accessible by the target machines you install Citrix Workspace app on.

  2. Get the CheckAndDeployWorkspacePerMachineStartupScript.battemplate from the Citrix Workspace app for Windows Download page.

  3. Edit the content to reflect the location and the version of CitrixWorkspaceApp.exe.

  4. In the Active Directory Group Policy Management console, enter CheckAndDeployWorkspacePerMachineStartupScript.bat as a startup script. For more information on deploying the startup scripts, see the Active Directory section.

  5. In the Computer Configuration node, go to Administrative Templates > Add/Remove Templates to add the icaclient.adm file.

  6. After adding the icaclient.adm template, go to Computer Configuration > Administrative Templates > Citrix Components > Citrix Workspace > User authentication

  7. Select the Local user name password policy and set it to Enabled.

  8. Select Enable pass-through authentication and click Apply.

  9. Restart the machine for the changes to take effect.

Configure single sign-on on StoreFront and Web Interface

StoreFront configuration

Open Citrix Studio on the StoreFront server and select Authentication > Add /Remove Authentication Methods. Select Domain pass-through.

alt_text

Configuration Checker

Configuration Checker lets you run a test to ensure that single sign-on is configured properly. The test runs on different checkpoints of the Single Sign-on configuration and displays the configuration results.

  1. Right-click Citrix Workspace app icon in the notification area and click Advanced Preferences. The Advanced Preferences dialog appears.
  2. Click Configuration Checker. The Citrix Configuration Checker window appears.

    Configuration Checker

  3. Select SSONChecker from the Select pane.
  4. Click Run. A progress bar appears, displaying the status of the test.

The Configuration Checker window has the following columns:

  1. Status: Displays the result of a test on a specific check point.

    • A green check mark indicates that the specific checkpoint is configured properly.
    • A blue I indicates information about the checkpoint.
    • A Red X indicates that the specific checkpoint is not configured properly.
  2. Provider: Displays the name of the module on which the test is run. In this case, single sign-on.
  3. Suite: Indicates the category of the test. For example, Installation.
  4. Test: Indicates the name of the specific test that is run.
  5. Details: Provides additional information about the test, irrespective of pass or fail.

The user gets more information about each checkpoint and the corresponding results.

The following tests are performed:

  1. Installed with single sign-on
  2. Logon credential capture
  3. Network Provider registration: The test result against Network Provider registration displays a green check mark only when “Citrix Single Sign-on” is set to be first in the list of Network Providers. If Citrix Single Sign-on appears anywhere else in the list, the test result against Network Provider registration appears with a blue I and additional information.
  4. Single sign-on process is running
  5. Group Policy: By default, this policy is configured on the client.
  6. Internet Settings for Security Zones: Ensure that you add the Store/XenApp Service URL to the list of Security Zones in the Internet Options. If the Security Zones are configured via Group policy, any change in the policy requires the Advanced Preferences window to be reopened for the changes to take effect and to display the correct status of the test.
  7. Authentication method for Web Interface/StoreFront.

Note:

  • If you are accessing Workspace for Web, the test results are not applicable.
  • If Citrix Workspace app is configured with multiple stores, the authentication method test runs on all the configured stores.
  • You can save the test results as reports. The default report format is .txt.

Hide the Configuration Checker option from the Advanced Preferences window

  1. Open the Citrix Workspace app Group Policy Object administrative template by running gpedit.msc.
  2. Go to Citrix Components > Workspace for Windows > Self Service > DisableConfigChecker.
  3. Click Enabled to hide the Configuration Checker option from the Advanced Preferences window.
  4. Click Apply and OK.
  5. Run the gpupdate /force command.

Limitation:

Configuration Checker does not include the checkpoint for the configuration of Trust requests sent to the XML service on Citrix Virtual Apps and Desktops servers.

Beacon test

Citrix Workspace app allows you to perform a beacon test using the Beacon checker that is available as part of the Configuration Checker utility. Beacon test helps to confirm if the beacon (ping.citrix.com) is reachable. This diagnostic test helps to eliminate one of the many possible causes for slow resource enumeration, that is beacon not being available. To run the test, right-click the Citrix Workspace app in the notification area and select Advanced Preferences > Configuration Checker. Select Beacon checker from the list of Tests and click Run.

The test results can be any of the following:

  • Reachable – Citrix Workspace app is successfully able to contact the beacon.
  • Not reachable - Citrix Workspace app is unable to contact the beacon.
  • Partially reachable - Citrix Workspace app is able to contact the beacon intermittently.

Note:

  • The test results are not applicable on Workspace for Web.
  • The test results can be saved as reports. The default format for the report is .txt.

Domain pass-through authentication with Kerberos

This topic applies only to connections between Citrix Workspace app for Windows and StoreFront, Citrix Virtual Apps and Desktops.

Citrix Workspace app supports Kerberos for domain pass-through authentication for deployments that use smart cards. Kerberos is one of the authentication methods included in Integrated Windows Authentication (IWA).

When enabled, Kerberos authenticates without passwords for Citrix Workspace app. Thereby, preventing Trojan horse-style attacks on the user device that try to gain access to passwords. Users can log on using any authentication method and access published resources. For example, a biometric authenticator such as a fingerprint reader.

When you log on using a smart card to Citrix Workspace app, StoreFront, Citrix Virtual Apps and Desktops configured for smart card authentication- the Citrix Workspace app:

  1. Captures the smart card PIN during single sign-on
  2. Uses IWA (Kerberos) to authenticate the user to StoreFront. StoreFront then provides your Workspace app with information about available the Citrix Virtual Apps and Desktops.

    Note

    Enable Kerberos to avoid an extran PIN prompt. If Kerberos authentication is not used, Citrix Workspace app authenticates to StoreFront using the smart card credentials.

  3. The HDX engine (previously referred to as the ICA client) passes the smart card PIN to the VDA to log the user on to Citrix Workspace app session. Citrix Virtual Apps and Desktops then delivers the requested resources.

To use Kerberos authentication with Citrix Workspace app, ensure your Kerberos configuration conforms to the following.

  • Kerberos works only between Citrix Workspace app and servers that belong to the same or to trusted Windows Server domains. Servers must also be trusted for delegation, an option you configure through the Active Directory Users and Computers management tool.
  • Kerberos must be enabled both on the domain and Citrix Virtual Apps and Desktops. For enhanced security and to ensure that Kerberos is used, disable any non-Kerberos IWA options on the domain.
  • Kerberos log on is not available for Remote Desktop Services connections that are configured to use either Basic authentication, always use specified logon information, or always prompt for a password.

Warning

Using Registry editor incorrectly might cause serious 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. Use Registry Editor at your own risk. Ensure you back up the registry before you edit it.

Domain pass-through authentication with Kerberos for use with smart cards

See the smart card information present in the Secure your deployment section in the Citrix Virtual Apps and Desktops documentation before continuing.

When you install Citrix Workspace app for Windows, include the following command-line option:

  • /includeSSON

    This option installs the single sign-on component on the domain-joined computer, enabling your workspace to authenticate to StoreFront using IWA (Kerberos). The single sign-on component stores the smart card PIN, which is used by the HDX engine when it remotes the smart card hardware and credentials to Citrix Virtual Apps and Desktops. Citrix Virtual Apps and Desktops automatically selects a certificate from the smart card and obtains the PIN from the HDX engine.

    A related option, ENABLE\_SSON, is enabled by default.

If a security policy prevents you from enabling single sign-on on a device, configure Citrix Workspace app using Group Policy Object administrative template.

  1. Open the Citrix Workspace app Group Policy Object administrative template by running gpedit.msc.
  2. Choose Administrative Templates > Citrix Components > Citrix Workspace > User authentication > Local user name and password
  3. Select Enable pass-through authentication.
  4. Restart Citrix Workspace app for the changes to take effect.

    Enable pass-through authentication

To configure StoreFront:

When you configure the authentication service on the StoreFront server, select the Domain pass-through option. That setting enables Integrated Windows Authentication. You do not need to select the Smart card option unless you also have non domain-joined clients connecting to StoreFront using smart cards.

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

Smart card

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 logon certificate has expired. Dedicated stores must be set up per site to allow Bimodal authentication, using the DisableCtrlAltDel method set to False to allow smart cards. Bimodal authentication requires StoreFront 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 requires 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 following command line options:

  • /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.

Smart card authentication for Web Interface

If Citrix Workspace app for Windows is installed with an SSON component, pass-through authentication is enabled by default even if the PIN pass-through for smart card is not enabled on the XenApp PNAgent site; the pass-through setting for authentication methods will no longer be effective. The screen below illustrates how to enable smart card as the authentication method when Citrix Workspace app is properly configured with SSON.

Use the smart card removal policy to control the behavior for smart card removal when a user authenticates to the Citrix Web Interface 5.4 PNAgent site.

When this policy is enabled, the user is logged off from the Citrix Virtual Apps session if the smart card is removed from the client device. However, the user is still logged in to the Citrix Workspace app.

For this policy to take effect, the smart card removal policy must set in Web Interface XenApp Services site. The settings can be found on Web Interface 5.4, XenApp Services Site > Pass-through with smart card > Enable Roaming > Logoff the sessions when smart card removed.

When the smart card removal policy is disabled, the user’s Citrix Virtual Apps session is disconnected if the smart card is removed from the client device. Smart card removal on the Web Interface XenApp Services site does not have any effect.

Note:

There are separate policies for 32 bit and 64 bit clients. For 32 bit devices, the policy name is Smartcard Removal Policy (32 Bit machine) and for 64 bit devices, the policy name is Smartcard Removal Policy (64 Bit machine).

alt_text

Smart card support and removal changes

Consider the following when connecting to a XenApp 6.5 PNAgent site:

  • Smart card login is supported for PNAgent site logins.
  • The smart card removal policy has changed on the PNAgent Site:

A Citrix Virtual Apps session is logged off when the smart card is removed – if the PNAgent site is configured with smart card as the authentication method, the corresponding policy has to be configured on Citrix Workspace app for Windows to enforce the Citrix Virtual Apps session for logoff. Enable roaming for smart card authentication on the XenApp PNAgent site and enable the smart card removal policy, which logs off Citrix Virtual Apps from the Citrix Workspace app session. The user is still logged into the Citrix Workspace app session.

Limitation:

When you log on to the PNAgent site using smart card authentication, the user name is displayed as Logged On.