Client certificate authentication


  • When using StoreFront, Citrix Workspace app supports:
    • Citrix Access Gateway Enterprise Edition Version 9.3
    • NetScaler Gateway Version 10.x through Version 11.0
    • Citrix Gateway Version 11.1 and later
  • Citrix Workspace app for iOS supports client certificate authentication.
  • Only Access Gateway Enterprise Edition 9.x and 10.x (and later releases) support client certificate authentication.
  • Double-source authentication types must be CERT and LDAP.
  • Citrix Workspace app also supports optional client certificate authentication.
  • Only P12 formatted certificates are supported.

Users signing in to a Citrix Gateway virtual server can also be authenticated based on the attributes of the client certificate that is presented to the virtual server. Client certificate authentication can also be used with another authentication type, LDAP, to provide double-source authentication.

Administrators can authenticate end users based on the client-side certificate attributes as follows:

  • the client authentication is enabled on the virtual server.
  • the virtual server requests for a client certificate.
  • to bind a root certificate to the virtual server on Citrix Gateway.

When users sign in to the Citrix Gateway virtual server, after authentication, users can extract the user name and domain information from the SubjectAltName:OtherName:MicrosoftUniversalPrincipalName field in the certificate. It is in the format “username@domain.”

When the user extracts the user name and domain successfully, and provides the other required information, such as password, the authentication is successful. If the user does not provide a valid certificate and credentials, or if the username/domain extraction fails, authentication fails.

You can authenticate users based on the client certificate by setting the default authentication type to use the client certificate. You can also create a certificate action that defines what is to be done during the authentication based on a client SSL certificate.

To configure the XenApp farm

Create a XenApp farm for mobile devices in the Citrix Virtual Apps console or Web Interface console. The console depends on the version of Citrix Virtual Apps that you’ve installed.

Citrix Workspace app uses a XenApp farm to get information about the applications a user has rights to. The same information is shared to the apps that are running on the device. This method is similar to the way you use the Web Interface for traditional SSL-based Citrix Virtual Apps connections where, you can configure Citrix Gateway.

Configure the XenApp farm for Citrix Workspace app for mobile devices to support connections from Citrix Gateway as follows:

  1. In the XenApp farm, select Manage secure client access > Edit secure client access settings.
  2. Change the Access Method to Gateway Direct.
  3. Enter the FQDN of the Citrix Gateway appliance.
  4. Enter the Secure Ticket Authority (STA) information.

To configure the Citrix Gateway appliance

For client certificate authentication, configure Citrix Gateway with two-factor authentication using the Cert and LDAP authentication policies. To configure the Citrix Gateway appliance:

  1. Create a session policy on Citrix Gateway to allow incoming Citrix Virtual Apps connections from Citrix Workspace app. Specify the location of your newly created XenApp farm.

    • Create a session policy to identify that the connection is from Citrix Workspace app. As you create the session policy, configure the following expression and choose Match All Expressions as the operator for the expression:

      REQ.HTTP.HEADER User-Agent CONTAINS CitrixWorkspace

    • In the associated profile configuration for the session policy, on the Security tab, set Default Authorization to Allow.

      On the Published Applications tab, if the setting isn’t a global setting (you selected the Override Global check box), verify if the ICA Proxy field is set to ON.

      In the Web Interface Address field, enter the URL including the config.xml for the XenApp farm that the device users use, for example:

      • /XenAppServerName/Citrix/PNAgent/config.xml or
      • /XenAppServerName/CustomPath/config.xml.
    • Bind the session policy to a virtual server.

    • Create authentication policies for Cert and LDAP.

    • Bind the authentication policies to the virtual server.

    • Configure the virtual server to request client certificates in the TLS handshake. To do so, navigate to the Certificate > open SSL Parameters > Client Authentication > set Client Certificate to Mandatory.


    If the server certificate that is used on the Citrix Gateway is a part of a certificate chain, for example, an intermediate certificate, install the certificates on the Citrix Gateway. For information about installing certificates, see the Citrix Gateway documentation.

To configure the mobile device

If client certificate authentication is enabled on Citrix Gateway, users are authenticated based on certain attributes of the client certificate. After authentication, you can extract the user name and domain from the certificate. You can apply specific policies for each user.

  1. From Citrix Workspace app, open the Account, and in the Server field, type the matching FQDN of your Citrix Gateway server. For example, Citrix Workspace app automatically detects that the client certificate is required.
  2. Users can either install a new certificate or choose one from the already installed certificate list. For iOS client certificate authentication, download and install the certificate from Citrix Workspace app only.
  3. After you select a valid certificate, the user name and domain fields on the sign-in screen is prepopulated using the user name from the certificate. An end user can type other details, including the password.
  4. If client certificate authentication is set to optional, users can skip the certificate selection by pressing Back on the certificates page. In this case, Citrix Workspace app proceeds with the connection and provides the user with the logon screen.
  5. After users complete the initial sign-in, they can start applications without providing the certificate again. Citrix Workspace app stores the certificate for the account and uses it automatically for future logon requests.

Configure Rewrite policy for authentication process

On iOS or iPad devices, administrators can switch the browser being used for the authentication process from embedded browser to system browser, when an advanced authentication policy is configured on the on-premises Citrix Gateway and StoreFront Deployment. To achieve this, configure the NetScaler Rewrite policy by using the Netscaler command line:

  1. enable ns feature REWRITE
  2. add rewrite action insert_auth_browser_type_hdr_act insert_http_header X-Auth-WebBrowser "\"System\""
  3. add rewrite policy insert_auth_browser_type_hdr_pol "HTTP.REQ.URL.EQ(\"/cgi/authenticate\")" insert_auth_browser_type_hdr_act
  4. bind vpn vserver <VPN-vserver-Name> -policy insert_auth_browser_type_hdr_pol -priority 10 -gotoPriorityExpression END -type AAA_RESPONSE

Moving to the system browser provides support for additional capabilities such as:

  • Better experience with certificate based authentication.
  • Ability to use existing user certificate from the devices keystore during authentication process.
  • Support for few third-party authenticators like SITHS eID.

Embedded browser is used as the default browser for authentication if the administrator has not configured the above Rewrite policy.

This table lists the browsers that are used for authentication based on the configuration on the NetScaler Gateway and Global App Config Service:

NetScaler Gateway Global App Configuration Service Browser used for authentication
System System System
System Embedded System
Embedded System System
Embedded Embedded Embedded
No Configuration System System
No Configuration Embedded Embedded

Support certificate based authentication for on-premises stores

End users can now handle certificate-based authentication where, the certificates are saved onto the device keychain. While signing in, Citrix Workspace app detects the list of certificates on your device, and you can choose a certificate for authentication.


After you choose the certificate, the selection persists for the next Citrix Workspace app launch. To choose another certificate, you can “Reset Safari” from iOS device settings or reinstall Citrix Workspace app.

Safari View Controller


This feature supports on-premises deployments.

To configure:

  1. Navigate to the Global App Configuration Store Settings API URL and enter the cloud store URL. For example,<hash coded store URL>/product/workspace/os/ios.
  2. Navigate to API Exploration > SettingsController > postDiscoveryApiUsingPOST > click POST.
  3. Click INVOKE API.
  4. Enter and upload the payload details. Select one of the following values:

    • “Embedded”: you can use WKWebView. This option is set by default.
    • “system”: you can use the Safari view controller.

    For example,

    "category": "Authentication",
    "userOverride": false,
    "settings": [
    { "name": "Web Browser to use for Authentication", "value": "*Embedded*/*System*" },

    On iOS or iPad devices, administrators can switch the browser being used for the authentication process from embedded browser to system browser, when an advanced authentication policy is configured on the on-premises Citrix Gateway and StoreFront Deployment. For more information, see Configure Rewrite policy for authentication process.

  5. Click EXECUTE to push the service.

Smart cards

Citrix Workspace app supports SITHS smart cards for in-session connections only.

If you’re using FIPS Citrix Gateway devices, configure your systems to deny SSL renegotiations. For details, see Knowledge Center article CTX123680.

The following products and configurations are supported:

  • Supported readers:
    • Precise Biometrics Tactivo for iPad Mini Firmware version 3.8.0
    • Precise Biometrics Tactivo for iPad (fourth generation) and Tactivo for iPad (third generation) and iPad 2 Firmware version 3.8.0
    • BaiMobile® 301MP and 301MP-L Smart Card Readers
    • Thursby PKard USB reader
    • Feitian iR301 USB reader
  • Supported VDA Smart Card Middleware
    • ActiveIdentity
  • Supported smartcards:
    • PIV cards
    • Common Access Card (CAC)
  • Supported configurations:
    • Smart card authentication to Citrix Gateway with StoreFront 2.x and XenDesktop 7.x or later or XenApp 6.5 or later

To configure Citrix Workspace app to access apps

  1. If you want to configure Citrix Workspace app automatically to access apps when you create an account, in the Address field, type the matching URL of your store. For example:

  2. Select the Use Smartcard option when you’re using a smart card to authenticate.


Logons to the store are valid for about one hour. After that time, users must log on again to refresh or launch other applications.

RSA SecurID authentication

Citrix Workspace app supports RSA SecurID authentication for Secure Web Gateway configurations. The configurations are through the Web Interface and for all Citrix Gateway configurations.

URL scheme required for the software token on Citrix Workspace app for iOS: The RSA SecurID software token used by Citrix Workspace app registers the URL scheme com.citrix.securid only.

If end users have installed both the Citrix Workspace app and the RSA SecurID app on their iOS device, users must select the URL scheme com.citrix.securid to import the RSA SecurID Software Authenticator (software token) to Citrix Workspace app on their devices.

To import an RSA SecurID soft token

To use an RSA Soft Token with the Citrix Workspace app, as an administrator, ensure that the end users follow:

  • the policy for PIN length
  • the type of PIN (numeric only and alphanumeric)
  • the limits on PIN reuse

After the end user is successfully authenticated to the RSA server, the end user needs to set up the PIN only once. After the PIN verification, they’re also authenticated with the StoreFront server. After all the verification, the Workspace app displays available, published applications and desktops.

To use an RSA soft token

  1. Import the RSA soft token provided to you by your organization.

  2. From the email with your SecurID file attached, select Open in Workspace as the import destination. After the soft token is imported, Citrix Workspace app opens automatically.

  3. If your organization provided a password to complete the import, enter the password provided to you by your organization and click OK. After clicking OK, you’ll see a message that the token was successfully imported.

  4. Close the import message, and in Citrix Workspace app, tap Add Account.

  5. Enter the URL for the Store provided by your organization and click Next.

  6. On the Log On screen, enter your credentials: user name, password, and domain. For the Pin field, enter 0000, unless your organization has provided you with a different default PIN. The PIN 0000 is an RSA default, but your organization might have changed it to follow with their security policies.

  7. At the top left, click Log On. A message appears to create a PIN.

  8. Enter a PIN that is 4 to 8 digits long and click OK. A message appears to verify your new PIN.
  9. Enter your PIN again and click OK. You can now access your apps and desktops.

Next Token Code

Citrix Workspace app supports the next token code feature when you configure Citrix Gateway with RSA SecurID authentication. If you enter three incorrect passwords, an error message appears on the Citrix Gateway plug-in. To sign in, wait for the next token. The RSA server can be configured to disable a user’s account if a user logs on too many times with an incorrect password.

Derived credentials

Support for Purebred derived credentials within Citrix Workspace app is available. When connecting to a Store that allows derived credentials, users can log on to Citrix Workspace app using a virtual smart card. This feature is supported only on on-premises deployments.


Citrix Virtual Apps and Desktops 7 1808 or later is required to use this feature.

To enable derived credentials in Citrix Workspace app:

  1. Go to Settings > Advanced > Derived Credentials.
  2. Tap Use Derived Credentials.

To create a virtual smart card to use with derived credentials:

  1. In Settings > Advanced > Derived Credentials, tap Add New Virtual Smart Card.
  2. Edit the name of the virtual smart card.
  3. Enter an 8-digit numeric-only PIN and confirm.
  4. Tap Next.
  5. Under Authentication Certificate, tap Import Certificate…
  6. The document picker displays. Tap Browse.
  7. Under Locations, select Purebred Key Chain.
  8. Select the suitable authentication certificate from the list.
  9. Tap Import Key.
  10. Repeat steps 5–9 for the Digital Signature Certificate and the Encryption Certificate, if wished.
  11. Tap Save.

You can import three or less certificates for your virtual smart card. The authentication certificate is required for the virtual smart card to work properly. The encryption certificate and digital signature certificate can be added for use in a VDA session.


When connecting to an HDX session, the created virtual smart card is redirected into the session.

Known limitations

  • Users can only have one active card at a time.
  • Once a virtual smart card is created, it cannot be edited. Delete and create card.
  • A PIN can be invalid up to 10 times. After the tenth try, the virtual smart card gets deleted.
  • When you select derived credentials, the virtual smart card overrides a physical smart card.

nFactor authentication

Support for multi-factor (nFactor) authentication

Multifactor authentication enhances the security of an application by requiring users to provide multiple proofs of identify to gain access. Multifactor authentication makes authentication steps and the associated credential collection forms configurable by the administrator.

Native Citrix Workspace app can support this protocol by building on the Forms logon support already implemented for StoreFront. The web logon page for Citrix Gateway and Traffic Manager virtual servers also consumes this protocol.

For more information, see SAML authentication, and Multi-Factor (nFactor) authentication.


  • With nFactor support enabled, you can’t use biometric authentication such as Touch ID and Face ID.

nFactor Advanced authentication policy support

We now support certificate-based authentication on Citrix Workspace app when configured through nFactor Advanced authentication policies on Citrix Gateway. nFactor authentication helps configure flexible and agile multi-factor schemas.

User-agent string:

While performing advanced (nFactor) authentication for Citrix Workspace app on iPhone or iPad, the authentication process is redirected to an embedded WebView. The resultant user agent string may vary slightly based on the OS version, CWA build version, the device model, and the AuthManager version. For example, consider the following user agent strings for iPhone and iPad.

For iPhone:

Mozilla/5.0 (iPhone; CPU iPhone OS 16_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 CWA/23.5.0 iOS/16.2 X1Class CWACapable 302RedirectionCapable CFNetwork Darwin CWA-iPhone AuthManager/

For iPad:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 CWA/23.5.0 iOS/15.0 X1Class CWACapable 302RedirectionCapable CFNetwork Darwin CWA-iPad AuthManager/

This feature is currently in preview. It can be enabled on request using the Podio link or by contacting Citrix Technical Support. However, it will eventually be rolled out to every customer after the preview has ended.


  • The version or device model information might vary based on the environment.
  • To apply Citrix Workspace app for iOS-specific user agent-based policies during authentication, leverage the following keywords:
    • iOS
    • CWA
    • CWACapable

Support for FIDO2-based authentication


  • This feature is in public preview.

Citrix Workspace app for iOS now supports password-less authentication within a Citrix Virtual Apps and Desktops session using FIDO2-based authentication methods. This allows users to sign in to a WebAuthn-supported website in browsers such as Google Chrome or Microsoft Edge using FIDO2-supported Yubico security keys. Simply opening a WebAuthn-supported website triggers password-less authentication.

Only lightning port-based devices are supported (devices with USB-C or USB 4 ports aren’t supported). Signing in to the Citrix Workspace app or desktop session using password-less authentication isn’t supported.

For more information about the prerequisites for this feature, see Local authorization and virtual authentication using FIDO2 in the Citrix Virtual Apps and Desktops documentation.