Authentication
You can configure various types of authentication for your Citrix Workspace app, including domain pass-through (single sign-on or SSON), smart card, and Kerberos pass-through.
Domain pass-through (single sign-on) authentication
Domain pass-through (single sign-on or SSON) lets you authenticate to a domain and use Citrix Virtual Apps and Desktops and Citrix DaaS (formerly Citrix Virtual Apps and Desktops service) without having to reauthenticate again.
Note:
If you disable the Enable MPR notifications for the System policy in the Group Policy Object template, the domain pass-through (single sign-on) authentication feature isn’t supported on Windows 11. This feature is available from Citrix Workspace app for Windows version 2012 and later.
When enabled, domain pass-through (single sign-on) caches your credentials, so that you can connect to other Citrix applications without having to sign in each time. Ensure that only software that is in accordance with your corporate policies runs on your device to mitigate the risk of credential compromise.
When you log on to Citrix Workspace app, your credentials are passed through to StoreFront, along with the apps and desktops and Start menu settings. After configuring single sign-on, you can log on to Citrix Workspace app and launch virtual apps and desktops sessions without having to retype your credentials.
All web browsers require you to configure single sign-on using the Group Policy Object (GPO) administrative template. For more information about configuring single sign-on using the Group Policy Object (GPO) administrative template, see Configure single sign-on with Citrix Gateway.
You can configure single sign-on on both fresh installation or upgrade setup, using any of the following options:
- Command-line interface
- GUI
Note:
The terms domain pass-through, single sign-on, and SSON might be used interchangeably in this document.
Limitations:
Domain pass-through using user credentials has the following limitations:
- Doesn’t support passwordless authentication with modern authentication methods such as Windows Hello or FIDO2. An additional component called the Federated Authentication Service (FAS) is required for single sign-on (SSO).
- Installation or upgrade of Citrix Workspace app with SSON enabled requires a reboot of the device.
- Requires Multi Provider Router (MPR) notifications to be enabled on Windows 11 machines.
- Must be on the top of the list of network providers order.
To overcome the preceding limitations, use Enhanced domain pass-through for single sign-on (Enhanced SSO).
Configure single sign-on during fresh installation
To configure single sign-on during fresh installation, do the following steps:
- Configuration on StoreFront.
- Configure XML trust services on the Delivery Controller.
- Modify Internet Explorer settings.
- Install Citrix Workspace app with single sign-on.
Configure single sign-on on StoreFront
Single sign-on lets you authenticate to a domain and use Citrix Virtual Apps and Desktops and Citrix DaaS from the same domain without having to reauthenticate to each app or desktop.
When you add a store using the Storebrowse utility, your credentials pass through the Citrix Gateway server, along with the apps and desktops enumerated for you, including your Start menu settings. After configuring single sign-on, you can add the store, enumerate your apps and desktops, and launch the required resources without having to type your credentials multiple times.
Depending on the Citrix Virtual Apps and Desktops deployment, single sign-on authentication can be configured on StoreFront using the Management Console.
Use the following table for different use cases and its respective configuration:
Use case | Configuration details | Additional information |
---|---|---|
Configured SSON on StoreFront | Launch Citrix Studio, go to Stores > Manage Authentication Methods - Store > enable Domain pass-through. | When Citrix Workspace app isn’t configured with single sign-on, it automatically switches the authentication method from Domain pass-through to User name and password, if available. |
When workspace for web is required | Launch Stores > Workspace for Web Sites > Manage Authentication Methods - Store > enable Domain pass-through. | When Citrix Workspace app isn’t configured with single sign-on, it automatically switches the authentication method from Domain pass-through to User name and password, if available. |
Configure single sign-on with Citrix Gateway
You enable single sign-on with Citrix Gateway using the Group Policy Object administrative template. However, you must ensure that you have enabled basic authentication and single factor (nFactor with 1 Factor) authentication on the Citrix Gateway.
- Open the Citrix Workspace app GPO administrative template by running
gpedit.msc
. - Under the Computer Configuration node, go to Administrative Template > Citrix Components > Citrix Workspace > User Authentication, and select Single Sign-on for Citrix Gateway policy.
- Select Enabled.
- Click Apply and OK.
- Restart Citrix Workspace app for the changes to take effect.
Configure XML trust services on the Delivery Controller
On Citrix Virtual Apps and Desktops and Citrix DaaS, run the following PowerShell command as an administrator on the Delivery Controller:
asnp Citrix* ; Set-BrokerSite -TrustRequestsSentToTheXmlServicePort $True
Modify the Internet Explorer settings
- Add the StoreFront server to the list of trusted sites using Internet Explorer. To add:
- Launch Internet Options from the Control panel.
-
Click Security > Local Intranet and click Sites.
The Local Intranet window appears.
- Select Advanced.
- Add the URL of the StoreFront FQDN with the appropriate HTTP or HTTPS protocols.
- Click Apply and OK.
- Modify the User Authentication settings in Internet Explorer. To modify:
- Launch Internet Options from the Control panel.
- Click Security tab > Local Intranet.
- Click Custom level. The Security Settings – Local Intranet Zone window appears.
-
In the User Authentication pane, select Automatic logon with current user name and password.
- Click Apply and OK.
Configure single sign-on using the command-line interface
Install Citrix Workspace app with the /includeSSON
switch and restart Citrix Workspace app for the changes to take effect.
Configure single sign-on using the GUI
- Locate the Citrix Workspace app installation file (
CitrixWorkspaceApp.exe
). - Double-click
CitrixWorkspaceApp.exe
to launch the installer. - In the Enable Single Sign-on installation wizard, select the Enable Single Sign-on option.
- Click Next and follow the prompts to complete the installation.
You can now log on to an existing store (or configure a new store) using Citrix Workspace app without entering user credentials.
Configure single sign-on on workspace for web
You can configure single sign-on on workspace for web using the Group Policy Object administrative template.
- Open the workspace for web GPO administrative template by running gpedit.msc.
- Under the Computer Configuration node, go to Administrative Template > Citrix Component > Citrix Workspace > User Authentication.
- Select the Local user name and password policy and set it to Enabled.
- Click Enable pass-through authentication. This option allows the workspace for web to use your login credentials for authentication on the remote server.
- 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.
- Click Apply and OK.
- 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 the Microsoft System Center Configuration Manager.
-
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.
-
Get the
CheckAndDeployCitrixReceiverPerMachineStartupScript.bat
template from the Citrix Workspace app for Windows Download page. -
Edit the content to reflect the location and the version of
CitrixWorkspaceApp.exe
. -
In the Active Directory Group Policy Management console, type
CheckAndDeployCitrixReceiverPerMachineStartupScript.bat
as a startup script. For more information on deploying the startup scripts, see the Active Directory section. -
In the Computer Configuration node, go to Administrative Templates > Add/Remove Templates to add the
receiver.adml
file. -
After adding the
receiver.adml
template, go to Computer Configuration > Administrative Templates > Citrix Components > Citrix Workspace > User authentication. For more information about adding the template files, see Group Policy Object administrative template. -
Select the Local user name and password policy and set it to Enabled.
-
Select Enable pass-through authentication and click Apply.
-
Restart the machine for the changes to take effect.
Configure single sign-on on StoreFront
StoreFront configuration
- Launch Citrix Studio on the StoreFront server and select Stores > Manage Authentication Methods - Store.
- Select Domain pass-through.
Authentication tokens
Authentication tokens are encrypted and stored on the local disk so that you don’t need to reenter your credentials when your system or session restarts. Citrix Workspace app provides an option to disable the storing of authentication tokens on the local disk.
For enhanced security, we now provide a Group Policy Object (GPO) policy to configure the authentication token storage.
Note:
This configuration is applicable only in cloud deployments.
To disable storing of authentication tokens using the Group Policy Object (GPO) policy:
- Open the Citrix Workspace app Group Policy Object administrative template by running
gpedit.msc
. - Under the Computer Configuration node, go to Administrative Templates > Citrix Components > SelfService.
-
In the Store authentication tokens policy, select one of the following:
- Enabled: Indicates that the authentication tokens are stored on the disk. By default, set to Enabled.
- Disabled: Indicates that the authentication tokens aren’t stored on the disk. Reenter your credentials when your system or session restarts.
- Click Apply and OK.
Starting with Version 2106, Citrix Workspace app provides another option to disable the storing of authentication tokens on the local disk. Along with the existing GPO configuration, you can also disable the storing of authentication tokens on the local disk using the Global App Configuration Service.
In the Global App Configuration Service, set the Store Authentication Tokens
attribute to False
.
You can configure this setting using the Global App Configuration service in one of the following methods:
- Global App Configuration service User Interface (UI): To configure using UI, see Configure Citrix Workspace app
- API: To configure settings using APIs, see the Citrix Developer documentation.
Configuration Checker
Configuration Checker lets you run a test to check if the single sign-on is configured properly. The test runs on different checkpoints of the single sign-on configuration and displays the configuration results.
- Right-click Citrix Workspace app icon in the notification area and click Advanced Preferences. The Advanced Preferences dialog appears.
-
Click Configuration Checker. The Citrix Configuration Checker window appears.
- Select SSONChecker from the Select pane.
- Click Run. A progress bar appears, displaying the status of the test.
The Configuration Checker window has the following columns:
-
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 isn’t configured properly.
- Provider: Displays the name of the module on which the test is run. In this case, single sign-on.
- Suite: Indicates the category of the test. For example, Installation.
- Test: Indicates the name of the specific test that is run.
- Details: Provides additional information about the test, for both pass and fail.
The user gets more information about each checkpoint and the corresponding results.
The following tests are done:
- Installed with single sign-on.
- Logon credential capture.
- 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.
- Single sign-on process is running.
- Group Policy: By default, this policy is configured on the client.
- Internet Settings for Security Zones: Make sure 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.
- Authentication method for StoreFront.
Note:
- If you’re accessing workspace for web, the test results aren’t 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
- Open the Citrix Workspace app GPO administrative template by running
gpedit.msc
. - Go to Citrix Components > Citrix Workspace > Self Service > DisableConfigChecker.
- Click Enabled to hide the Configuration Checker option from the Advanced Preferences window.
- Click Apply and OK.
- 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 do a beacon test using the Beacon checker that is available as part of the Configuration Checker utility. The Beacon test helps to confirm if the beacon (ping.citrix.com) is reachable. Starting from Citrix Workspace app for Windows 2402 LTSR CU1 version, beacon test works for all the beacons configured in the store added in Citrix Workspace app. This diagnostic test helps to eliminate one of the many possible causes for slow resource enumeration, that is the 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 the Beacon checker option 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 can contact the beacon intermittently.
Note:
- The test results aren’t applicable on workspace for web.
- The test results can be saved as reports. The default format for the report is .txt.
Domain pass-through (Single Sign-on) authentication with Kerberos
This topic applies only to connections between Citrix Workspace app for Windows and StoreFront, Citrix Virtual Apps and Desktops, and Citrix DaaS.
Citrix Workspace app supports Kerberos for domain pass-through (single sign-on or SSON) 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. As a result, prevents 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, and Citrix DaaS configured for smart card authentication- the Citrix Workspace app:
- Captures the smart card PIN during single sign-on.
-
Uses IWA (Kerberos) to authenticate the user to StoreFront. StoreFront then provides your Citrix Workspace app with information about the available Citrix Virtual Apps and Desktops and Citrix DaaS.
Note:
Enable Kerberos to avoid an extran PIN prompt. If Kerberos authentication isn’t used, Citrix Workspace app authenticates to StoreFront using the smart card credentials.
- 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 and Citrix DaaS then delivers the requested resources.
To use Kerberos authentication with Citrix Workspace app, check if the 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 are 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 and Citrix DaaS. For enhanced security and to make sure that Kerberos is used, disable any non-Kerberos IWA options on the domain.
- Kerberos logon isn’t available for Remote Desktop Services connections that’re configured to use either Basic authentication, always use specified logon information, or always prompt for a password.
Warning:
Using the Registry editor incorrectly might cause serious problems that can require you to reinstall the operating system. Citrix can’t guarantee that problems resulting from incorrect use of the Registry editor can be solved. Use the Registry Editor at your own risk. Make sure you back up the registry before you edit it.
Domain pass-through (Single Sign-on) authentication with Kerberos for use with smart cards
Before continuing, see Secure your deployment section in the Citrix Virtual Apps and Desktops document.
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, used by the HDX engine when it remotes the smart card hardware and credentials to Citrix Virtual Apps and Desktops and Citrix DaaS. Citrix Virtual Apps and Desktops and Citrix DaaS automatically selects a certificate from the smart card and gets 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.
- Open the Citrix Workspace app Group Policy Object administrative template by running gpedit.msc.
- Choose Administrative Templates > Citrix Components > Citrix Workspace > User authentication > Local user name and password
- Select Enable pass-through authentication.
-
Restart Citrix Workspace app for the changes to take effect.
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.
Support for Conditional Access with Azure Active Directory
Conditional Access is a tool used by Azure Active Directory to enforce organizational policies. Workspace administrators can configure and enforce Azure Active Directory conditional access policies for users authenticating to the Citrix Workspace app. The Windows machine running the Citrix Workspace app must have Microsoft Edge WebView2 Runtime version 99 or later installed.
For complete details and instructions about configuring conditional access policies with Azure Active Directory, see Azure AD Conditional Access documentation at Docs.microsoft.com/en-us/azure/active-directory/conditional-access/.
Note:
This feature is supported only on Workspace (Cloud) deployments.
Support for modern authentication methods for StoreFront stores
You can enable support for modern authentication methods for StoreFront stores using Group Policy Object (GPO) template. You can enable this feature using Global App Configuration service.
You can authenticate to Citrix StoreFront stores using any of the following ways:
- Using Windows Hello and FIDO2 security keys. For more information, see Other ways to authenticate.
- Single sign-on to Citrix StoreFront stores from Azure Active Directory (AAD) joined machines with AAD as the identity provider. For more information, see Other ways to authenticate.
- Workspace administrators can configure and enforce Azure Active Directory conditional access policies for users authenticating to Citrix StoreFront stores. For more information, see Support for Conditional access with Azure AD.
To enable this feature, you must use Microsoft Edge WebView2 as the underlying browser for direct StoreFront and gateway authentication.
Note:
Ensure that the Microsoft Edge WebView2 Runtime version is 102 or later.
You can enable modern authentication methods for StoreFront storess using Global App Config service and Group Policy Object (GPO) template.
Using Global App Config service
To enable this feature:
- From the Citrix Cloud menu, select Workspace Configuration and then select App Configuration.
- Click Security & Authentication.
- Ensure the Windows check box is selected.
-
Select Enabled next to Windows from the Microsoft Edge WebView for Storefront Authentication drop‑down list.
Note:
If you select Disabled next to Windows from the Microsoft Edge WebView for Storefront Authentication drop‑down list, Internet Explorer WebView is used within the Citrix Workspace app. As a result, the modern authentication methods for Citrix Storefront stores are not supported.
Using GPO
To enable this feature:
- Open the Citrix Workspace app Group Policy Object administrative template by running gpedit.msc.
- Under the Computer Configuration node, go to Administrative Templates > Citrix Workspace > User Authentication.
-
Click the Microsoft Edge WebView for StoreFront authentication policy and set it to Enabled.
- Click Apply and then OK.
When this policy is disabled, Citrix Workspace app uses Internet Explorer WebView. As a result, the modern authentication methods for Citrix StoreFront stores are not supported.
Other ways to authenticate
You can configure the following authentication mechanisms with the Citrix Workspace app. For the following authentication mechanisms to work as expected, the Windows machine running the Citrix Workspace app must have Microsoft Edge WebView2 Runtime version 99 or later installed.
-
Windows Hello based authentication – For instructions about configuring Windows Hello based authentication, see Configure Windows Hello for Business Policy settings - Certificate Trust at _Docs.microsoft.com/en-us/windows/security/identity-protection/hello-for-business/hello-cert-trust-policy-settings.
Note:
Windows Hello based authentication with domain pass-through (single-sign-on or SSON) is not supported.
- FIDO2 Security Keys based authentication – FIDO2 security keys provide a seamless way for enterprise employees to authenticate without entering a user name or password. You can configure FIDO2 Security Keys based authentication to Citrix Workspace. If you would like your users to authenticate to Citrix Workspace with their Azure AD account using a FIDO2 security key, see Enable passwordless security key sign-in at Docs.microsoft.com/en-us/azure/active-directory/authentication/howto-authentication-passwordless-security-key.
- You can also configure Single Sign-On (SSO) to Citrix Workspace app from Microsoft Azure Active Directory (AAD) joined machines with AAD as an identity provider. For more details about configuring Azure Active Directory Domain services, see Configuring Azure Active Directory Domain services at Docs.microsoft.com/en-us/azure/active-directory-domain-services/overview. For information about how to connect Azure Active Directory to Citrix Cloud, see Connect Azure Active Directory to Citrix Cloud.
Smart card
Citrix Workspace app for Windows supports the following smart card authentication:
-
Pass-through authentication (single sign-on) - Pass-through authentication captures the 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 using the smart card can start virtual desktops and applications without needing to reauthenticate.
- Citrix Workspace app running on non-domain joined devices with the 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 can’t 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, the StoreFront administrator can allow 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 availed 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 must reauthenticate after removing the smart card.
- When the Citrix Gateway SSL configuration is set to Mandatory client certificate authentication, operation is more secure. However, mandatory client certificate authentication isn’t 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.
-
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 virtual apps and desktops sessions.
Limitations:
- Certificates must be stored on the 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 isn’t 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. 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 isn’t available for smart card users.
- Citrix Workspace app updater communications with citrix.com and the Merchandising Server aren’t compatible with smart card authentication on Citrix Gateway.
Warning
Some configuration requires registry edits. Using the Registry editor incorrectly might cause problems that can require you to reinstall the operating system. Citrix can’t guarantee that problems resulting from incorrect use of the Registry Editor can be solved. Make sure 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.
-
In the Registry editor, navigate to the following path and set the
SSONCheckEnabled
string toFalse
if you have not installed the single sign-on component.HKEY_CURRENT_USER\Software{Wow6432}\Citrix\AuthManager\protocols\integratedwindows\
HKEY_LOCAL_MACHINE\Software{Wow6432}\Citrix\AuthManager\protocols\integratedwindows\
The key prevents the Citrix Workspace app authentication manager from checking for the single sign-on component and allows Citrix Workspace app to authenticate to StoreFront.
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 logs on to the endpoint with a different authentication method, for example, user name and password, the command line is:
/includeSSON LOGON_CREDENTIAL_CAPTURE_ENABLE=No
This type of authentication prevents capturing of the credentials at logon time and allows Citrix Workspace app to store the PIN during Citrix Workspace app login.
- Open the Citrix Workspace app Group Policy Object administrative template by running gpedit.msc.
- Go to Administrative Templates > Citrix Components > Citrix Workspace > User Authentication > Local user name and password.
- 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:
- Import the certificate authority root certificate into the device’s keystore.
- Install your vendor’s cryptographic middleware.
- 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. Instead, 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 include digital signature.
- Subject Alternative Name must include the User Principal Name (UPN).
- Enhanced key usage must include smart card logon and client authentication, or all key usages.
- One of the Certificate Authorities on the certificate’s issuer chain must match one of the allowed 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
orLatestExpiry
, 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={ PromptSmartCardDefault 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 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 support and removal changes
A Citrix Virtual Apps session logs off when you remove the smart card. If Citrix Workspace app is configured with smart card as the authentication method, configure the corresponding policy on Citrix Workspace app for Windows to enforce the Citrix Virtual Apps session for logoff. The user is still logged into the Citrix Workspace app session.
Limitation:
When you log on to the Citrix Workspace app site using smart card authentication, the user name is displayed as Logged On.
Fast smart card
Fast smart card is an improvement over the existing HDX PC/SC-based smart card redirection. It improves performance when smart cards are used in high-latency WAN environments.
Fast smart cards are supported on Windows VDA only.
To enable fast smart card logon on Citrix Workspace app:
Fast smart card logon is enabled by default on the VDA and disabled by default on Citrix Workspace app. To enable fast smart card logon, include the following parameter in the default.ica
file of the associated StoreFront site:
copy[WFClient]
SmartCardCryptographicRedirection=On
<!--NeedCopy-->
To disable fast smart card logon on Citrix Workspace app:
To disable fast smart card logon on Citrix Workspace app, remove the SmartCardCryptographicRedirection
parameter from the default.ica
file of the associated StoreFront site.
For more information, see smart-cards.
Silent authentication for Citrix Workspace
Citrix Workspace app introduces a Group Policy Object (GPO) policy to enable silent authentication for Citrix Workspace. This policy enables Citrix Workspace app to log in to Citrix Workspace automatically at system startup. Use this policy only when domain pass-through (single sign-on or SSON) is configured for Citrix Workspace on domain-joined devices. This feature is available from Citrix Workspace app for Windows version 2012 and later.
For this policy to function, the following criteria must be met:
- Single sign-on must be enabled.
- The
SelfServiceMode
key must be set toOff
in the Registry editor.
Enabling silent authentication:
- Open the Citrix Workspace app Group Policy Object administrative template by running
gpedit.msc
. - Under the Computer Configuration node, go to Administrative Templates > Citrix Workspace > Self Service.
- Click the Silent authentication for Citrix Workspace policy and set it to Enabled.
- Click Apply and OK.
Prevent Citrix Workspace app for Windows from caching passwords and usernames
By default, Citrix Workspace app for Windows automatically populates the last user name entered. To clear autofill of the user name field, edit the registry on the user device:
- Create a REG_SZ value HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\AuthManager\RememberUsername.
- Set its value false.
To disable the Remember my password check box and prevent an automatic sign-in, create following registry key on client machine where Citrix Workspace app for Windows is installed:
- Path: HKEY_LOCAL_MACHINE\Software\wow6432node\Citrix\AuthManager
- Type: REG_SZ
- Name: SavePasswordMode
- Value: Never
Note:
Using Registry Editor incorrectly can 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. Make sure you back up the registry before you edit it.
To prevent caching credentials for the StoreFront stores, see Prevent Citrix Workspace app for Windows from caching passwords and usernames in the StoreFront documentation.
Support for more than 200 groups in Azure AD
With this release, an Azure AD user who is part of more than 200 groups can view apps and desktops assigned to the user. Previously, the same user wasn’t able to view these apps and desktops.
Note:
Users must sign out from Citrix Workspace app and sign in back to enable this feature.
Proxy authentication support
Previously, on client machines configured with proxy authentication, if the proxy credentials don’t exist in the Windows Credential Manager, you aren’t allowed to authenticate to Citrix Workspace app.
From Citrix Workspace app for Windows version 2102 and later, on client machines configured for proxy authentication, if the proxy credentials aren’t stored in the Windows Credential Manager, an authentication prompt appears, asking you to enter the proxy credentials. Citrix Workspace app then saves the proxy server credentials in Windows Credential Manager. This results in a seamless login experience because you don’t need to manually save your credentials in Windows Credential Manager before accessing Citrix Workspace app.
User-Agent
Citrix Workspace app sends a user agent in network requests that can be used to configure authentication policies including redirection of authentication to other Identity Providers (IdPs).
Note:
The version numbers mentioned as part of the User-Agent in the following table are examples and it is automatically updated based on the versions that you are using.
The following table describes the scenario, description, and the corresponding User-Agent for each scenario:
Scenario | Description | User-Agent |
---|---|---|
Regular HTTP requests | In general, a network request made by Citrix Workspace app contains a User-Agent. For example, network requests like: GET /Citrix/Roaming/Accounts and GET / AGServices/discover
|
CitrixReceiver/23.5.0.63 Windows/10.0 (22H2 Build 19045.2965) SelfService/23.5.0.63 (Release) X1Class CWACapable |
Cloud store | When a user authenticates to a cloud store in Citrix Workspace app, network requests are made with a specific User-Agent. For example, network requests with path /core/connect/authorize . |
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36 Edg/113.0.1774.50 CWA/23.5.0.63 Windows/10.0 (22H2 Build 19045.2965) |
On-premises store with Gateway Advanced Auth using Edge WebView | When a user authenticates to the Gateway configured with Advanced Auth on Citrix Workspace app using Edge WebView, network requests are made with a specific User-Agent. For example, network requests that include: GET /nf/auth/doWebview.do and GET /logon/LogonPoint/tmindex.html . |
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36 Edg/108.0.1462.54 CWAWEBVIEW/23.2.0.2111 Windows/10.0 (22H2 Build 19045.2364) |
On-premises store with Gateway Advanced Auth using IE WebView | When a user authenticates to the Gateway configured with Advanced Auth on Citrix Workspace app using Internet Explorer WebView, network requests are made with a specific User-Agent. For example, network requests that include: GET /nf/auth/doWebview.do and GET /logon/LogonPoint/tmindex.html . |
Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0) like Gecko, CWAWEBVIEW/23.5.0.43 |
Custom web store | When a user adds a custom web store to Citrix Workspace app, the app sends a User-Agent. | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36 Edg/113.0.1774.50 CWA/23.5.0.63 Windows/10.0 (22H2 Build 19045.2965) |
In this article
- Domain pass-through (single sign-on) authentication
- Authentication tokens
- Domain pass-through (Single Sign-on) authentication with Kerberos
- Support for Conditional Access with Azure Active Directory
- Support for modern authentication methods for StoreFront stores
- Other ways to authenticate
- Smart card
- Silent authentication for Citrix Workspace
- Prevent Citrix Workspace app for Windows from caching passwords and usernames
- Support for more than 200 groups in Azure AD
- Proxy authentication support
- User-Agent