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:
- In the XenApp farm, select Manage secure client access > Edit secure client access settings.
- Change the Access Method to Gateway Direct.
- Enter the FQDN of the Citrix Gateway appliance.
- 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:
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
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.
- From Citrix Workspace app, open the Account, and in the Server field, type the matching FQDN of your Citrix Gateway server. For example, GatewayClientCertificateServer.organization.com. Citrix Workspace app automatically detects that the client certificate is required.
- 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.
- 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.
- 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.
- 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.
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
- 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
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:
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
Import the RSA soft token provided to you by your organization.
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.
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.
Close the import message, and in Citrix Workspace app, tap Add Account.
Enter the URL for the Store provided by your organization and click Next.
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.
At the top left, click Log On. A message appears to create a PIN.
- Enter a PIN that is 4 to 8 digits long and click OK. A message appears to verify your new PIN.
- 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.
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:
- Go to Settings > Advanced > Derived Credentials.
- Tap Use Derived Credentials.
To create a virtual smart card to use with derived credentials:
- In Settings > Advanced > Derived Credentials, tap Add New Virtual Smart Card.
- Edit the name of the virtual smart card.
- Enter an 8-digit numeric-only PIN and confirm.
- Tap Next.
- Under Authentication Certificate, tap Import Certificate…
- The document picker displays. Tap Browse.
- Under Locations, select Purebred Key Chain.
- Select the suitable authentication certificate from the list.
- Tap Import Key.
- Repeat steps 5–9 for the Digital Signature Certificate and the Encryption Certificate, if wished.
- 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.
- 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.
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.
- Certificate-based authentication isn’t supported.
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.
By default, the user-agent string used during nFactor authentication now includes the Citrix Workspace app identifier.
Therefore, it has been changed from:
Mozilla/5.0 (iPhone; CPU iPhone OS 15_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 AuthManager/188.8.131.52
Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 CWA/23.3.0 iOS/15.0 X1Class CWACapable 302RedirectionCapable CFNetwork Darwin CWA-iPhone
This change is only applicable to authentication requests that are initiated through WKWebview. WKWebview is not specific to nFactor authentication, it can also be used for cloud accounts if the admin configures the authentication agent as webAuth.
This change is applicable for on-premises deployments only.
The version or device model information might vary based on the environment.