Client certificate authentication


  • When using StoreFront, Citrix Workspace app for iOS 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.
  • Client certificate authentication is supported by Citrix Workspace app for iOS.
  • Only Access Gateway Enterprise Edition 9.x and 10.x (and subsequent releases) support client certificate authentication.
  • Double-source authentication types must be CERT and LDAP.
  • Citrix Workspace app for iOS also supports optional client certificate authentication.
  • Only P12 formatted certificates are supported.

Users logging on 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.

To authenticate users based on the client-side certificate attributes, client authentication should be enabled on the virtual server and the client certificate should be requested. You must bind a root certificate to the virtual server on Citrix Gateway.

When users log on to the Citrix Gateway virtual server, after authentication, the user name and domain information is extracted from the specified field of the certificate. This information must be in the certificate’s SubjectAltName:OtherName:MicrosoftUniversalPrincipalName field. It is in the format “username@domain.” If the user name and domain are extracted successfully, and the user provides the other required information (for example, a password), then the user is authenticated. 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 Services site

If you do not already have a XenApp Services site created, in the Citrix Virtual Apps console or Web Interface console (depending on the version of Citrix Virtual Apps you have installed), create a XenApp Services site for mobile devices.

Citrix Workspace app for iOS for mobile devices uses a XenApp Services site to get information about the applications a user has rights to and presents them to the app running on the device. This is similar to the way you use the Web Interface for traditional SSL-based Citrix Virtual Apps connections for which a Citrix Gateway can be configured.

Configure the XenApp Services site for Citrix Workspace app for iOS for mobile devices to support connections from a Citrix Gateway connection.

  1. In the XenApp Services site, 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 two authentication policies: Cert and LDAP.

  1. Create a session policy on Citrix Gateway to allow incoming Citrix Virtual Apps connections from Citrix Workspace app for iOS, and specify the location of your newly created XenApp Services site.
    • Create a session policy to identify that the connection is from Citrix Workspace app for iOS. 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 this is not a global setting (you selected the Override Global check box), ensure that the ICA Proxy field is set to ON.

      In the Web Interface Address field, type the URL including the config.xml for the XenApp Services site that the device users use, such as //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 (on the Certificate tab, open SSL Parameters, and for Client Authentication, set Client Certificate to Mandatory.


    If the server certificate used on Citrix Gateway is part of a certificate chain (with an intermediate certificate), ensure that the intermediate certificates are also installed correctly on Citrix Gateway. For information about installing certificates, see 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 is completed successfully, the user name and domain are extracted from the certificate and any policies specified for that user are applied.

  1. From Citrix Workspace app for iOS, open the Account, and in the Server field, type the matching FQDN of your Citrix Gateway server, such as Citrix Workspace app for iOS 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, the certificate must be downloaded and installed by Citrix Workspace app for iOS only.
  3. After selecting a valid certificate, the user name and domain fields on the logon screen is prepopulated using the user name information from the certificate, and a user types the remaining 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 for iOS proceeds with the connection and provides the user with the logon screen.
  5. After users complete the initial log on, they can start applications without providing the certificate again. Citrix Workspace app for iOS stores the certificate for the account and uses it automatically for future logon requests.

Smart cards

Citrix Workspace app for iOS provides support for SITHS smart cards for in-session connections only.

If you are 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 (4th generation) and Tactivo for iPad (3rd generation) and iPad 2 Firmware version 3.8.0
    • BaiMobile® 301MP and 301MP-L Smart Card Readers
  • 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 for iOS to access apps

  1. If you want to configure Citrix Workspace app for iOS to automatically access apps when creating an account, in the Address field, type the matching URL of your store, such as or
  2. Select the Use Smartcard option when you are 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

RSA SecurID authentication for Citrix Workspace app for iOS is supported for Secure Web Gateway configurations (through the Web Interface only) and 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 for iOS registers the URL scheme com.citrix.securid only.

If users have installed both the Citrix Workspace app for iOS 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 for iOS on their devices.

To import an RSA SecurID soft token

To use an RSA Soft Token with the Citrix Workspace app for iOS, have your users follow this procedure.

The policy for PIN length, type of PIN (numeric only, alphanumeric), and limits on PIN reuse are specified on the RSA administration server.

Your users should only need to do this once, after they have successfully authenticated to the RSA server. After your users verify their PINs, they are are also authenticated with the StoreFront server, and it presents 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 for iOS 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 will see a message that the token was successfully imported.

  4. Close the import message, and in Citrix Workspace app for iOS, click the 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 may have changed it to comply with their security policies.)

  7. At the top left, click Log On. After you click Log On, you are prompted to create a new PIN.

  8. Enter a PIN from 4 to 8 digits and click OK.

  9. You are then prompted to verify your new PIN. Re-enter your PIN and click OK. After clicking OK, you will be able to access your apps and desktops.

Next Token Code

If you configure Citrix Gateway for RSA SecurID authentication, Citrix Workspace app for iOS supports Next Token Code. With this feature enabled, if a user enters three (by default) incorrect passwords, the Citrix Gateway plug-in prompts the user to wait until the next token is active before logging on. 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 for iOS is available. When connecting to a Store that allows derived credentials, users can log on to Citrix Workspace app for iOS 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 for iOS:

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

Then, 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 desired authentication certificate from the list.
  9. Tap Import Key.
  10. Repeat steps 5–9 for the Digital Signature Certificate and the Encryption Certificate, if desired.
  11. Tap Save.

You can import up to three 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 inside of 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. To make changes to the virtual smart card, users must delete the card and create a new card.
  • A PIN can be invalid up to 10 times. After the tenth attempt, the virtual smart card gets deleted.
  • When derived credentials are selected, the virtual smart card that was created earlier overrides a physical smart card when a smart card is needed in a session.