Citrix Workspace app for iOS

Authenticate

March 22, 2024

Contributed by:

S S C

Client certificate authentication

Important:

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.

The authentication is completed when the user extracts the user name and domain, and provides the required information (such as password). 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 that you use the Web Interface for traditional SSL-based Citrix Virtual Apps connections, where you can configure the Citrix Gateway.

Configure the XenApp farm for Citrix Workspace app for mobile devices to support connections from the 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 checkbox), 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.
Important:

If the server certificate that is used on the Citrix Gateway is a part of a certificate chain. For example, if it is an intermediate certificate, then 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.

Configure Rewrite policy for authentication process

Administrators can switch the browser being used for the authentication process from embedded browser to system browser. It is only possible when an advanced authentication policy is configured on the on-premises Citrix Gateway and StoreFront Deployment. To configure an advanced authentication policy, configure the NetScaler Rewrite policy by using the NetScaler command line:

enable ns feature REWRITE
add rewrite action insert_auth_browser_type_hdr_act insert_http_header X-Auth-WebBrowser "\"System\""
add rewrite policy insert_auth_browser_type_hdr_pol "HTTP.REQ.URL.EQ(\"/cgi/authenticate\")" insert_auth_browser_type_hdr_act
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 more capabilities such as:

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

Embedded browser is used as the default browser for authentication if the administrator hasn’t 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.

Important:

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

Note:

This feature supports on-premises deployments.

To configure:

Navigate to the Global App Configuration Store Settings API URL and enter the cloud store URL. For example, https://discovery.cem.cloud.us/ads/root/url/<hash coded store URL>/product/workspace/os/ios.
Navigate to API Exploration > SettingsController > postDiscoveryApiUsingPOST > click POST.
Click INVOKE API.
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. You can switch 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.
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
- Type-C CCID-compliant readers
- twocanoes smart card utility 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

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:
- StoreFront.organization.com
- netscalervserver.organization.com
Select the Use Smartcard option when you’re using a smart card to authenticate.

Note:

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

Support for the twocanoes smart card utility reader

Starting with the 24.3.5 version, Citrix Workspace app for iOS supports the twocanoes smartcard utility readers. For more information about supported smart card readers, see Smart Cards.

Note:

The twocanoes smart card utility USB-C reader is supported for both Citrix Workspace app login and virtual session login. However, the twocanoes smart card utility Bluetooth reader is supported only for Citrix Workspace app login and not for virtual session login.

To configure the twocanoes smart card utility Bluetooth reader, do the following steps:

Download and install the Smart Card Utility app from the App store. For more information, see Smart Card Utility Bluetooth Reader Quick Start in the twocanoes knowledge base.
Make sure that the Bluetooth on your device is turned on and the smart card is inserted into the reader.
Open the Smart Card Utility app.
If you are using the Bluetooth reader, then tap Add Bluetooth or Other Reader… and select your reader to connect.

Note:

If the reader is enabled with pin pairing, then you must enter the PIN when prompted. The PIN is available on the backside of the reader.
Tap Insert on the required certificate to copy it to the keychain interface.

Note:

The Smart Card Utility app has implemented a cryptokit extension provided by Apple to write certificates to the keychain interface in the form of tokens. For more information, see Configure Smart Card Authentication in the Apple developer documentation.
Make sure that the reader remains connected to the device.
Open Citrix Workspace app and enter the store URL that is configured with smart card authentication.
On the Certificates screen, select the required certificate and enter the smart card PIN provided by your IT administrator to sign in.
If you have access to multiple stores, then select the required store and tap Continue.
After successful authentication, you are signed in to the Citrix Workspace app.

YubiKey support for smart card authentication

You can now perform smart card authentication using YubiKey. This feature provides a single-device authentication experience for Citrix Workspace app and for the virtual sessions and published apps in the VDA session. It eliminates the need to connect smart card readers or other external authenticators. It simplifies the end-user experience as YubiKey supports a wide variety of protocols, such as OTP, FIDO and so on.

To sign in to Citrix Workspace app, end users need to insert the YubiKey into their iPhone or iPad, turn on the Smart card toggle, and provide their Store URL.

Note:

This feature supports only direct connection to Citrix Workspace app on StoreFront deployments and not through Citrix Gateway. The YubiKey support for smart card authentication through Citrix Gateway will be available on the future release. Citrix Workspace app for iOS supports only the YubiKey 5 series. For more information on YubiKey, see YubiKey 5 series.

Support for multiple certificates in smart card authentication

Previously, Citrix Workspace app for iOS displayed the certificate available on the first slot of the connected smart card.

Starting with the 24.1.0 version, Citrix Workspace app for iOS displays all the certificates available on the smart card. This feature allows you to select the required certificate while authenticating through smart card authentication.

Select cert

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.

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.

Note:

Citrix Virtual Apps and Desktops 7 1808 or later are 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.

Note:

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 can’t be edited. Delete and create the card.
A PIN can be invalid up to ten times. If it is invalid after ten tries then the virtual smart card gets deleted.
When you select derived credentials, the virtual smart card overrides a physical smart card.

User-agent string for WKWebView

By default, the user-agent string used during some of the network requests initiated through WKWebView 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/3.2.4.0

To one of the following:

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 (iPhone example)

nFactor authentication

Support for multi-factor (nFactor) authentication

Multifactor authentication enhances the security of an application by requiring users to provide multiple proofs of identification 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.

Limitations:

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 an iPhone or iPad, the authentication process is redirected to an embedded WebView. The resultant user agent string might vary slightly based on the OS version, the 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/3.3.0.0

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/3.3.0.0

This feature is 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.

Note:

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, use the following keywords:

iOS

CWA

CWACapable

Support for FIDO2-based authentication

Citrix Workspace app for iOS now supports password-less authentication within a Citrix Virtual Apps and Desktops session using FIDO2-based authentication methods. This feature 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, see Local authorization and virtual authentication using FIDO2 in the Citrix Virtual Apps and Desktops documentation.

Support for configuring storage of authentication tokens on the on-premises deployment

Citrix Workspace app for iOS now provides an option to configure the storage of authentication tokens on the local disk for on-premises stores. With this feature, you can disable the storage of the authentication token for the enhanced security. After disabling, when the system or session restarts, you need to authenticate again to access the session.

To disable the storage of authentication tokens on the on-premises deployment using the administration config file, do the following:

Use a text editor to open the web.config file, which is typically at C:\inetpub\wwwroot\Citrix\Roaming directory.
Locate the user account element in the file (store is the account name of your deployment). For example: <account id=... name="Store">
Before the </account> tag, navigate to the properties of that user account and add the following:

    <properties>   
        <property name="TokenPersistence" value="false" />  
    </properties>
<!--NeedCopy-->

The following is an example of the web.config file:

    <account id="#########################################" name="Store Service"
        description="" published="true" updaterType="None" remoteAccessType="StoresOnly">
        <annotatedServices>
            <clear />
            <annotatedServiceRecord serviceRef="1__Citrix_Store">
                <metadata>
                    <plugins>
                        <clear />
                    </plugins>
                    <trustSettings>
                        <clear />
                    </trustSettings>
                    <properties>
                        <clear />
                        <property name="TokenPersistence" value="false" />
                     </properties>
                </metadata>
            </annotatedServiceRecord>
        </annotatedServices>
        <metadata>
        <plugins>
          <clear />
        </plugins>
        <trustSettings>
          <clear />
        </trustSettings>
        <properties>
        </properties>
     </metadata>
    </account>
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Authenticate

March 22, 2024

Contributed by:

S S C

March 22, 2024

Contributed by:

S S C

Client certificate authentication
Smart cards
YubiKey support for smart card authentication
Support for multiple certificates in smart card authentication
RSA SecurID authentication
Derived credentials
User-agent string for WKWebView
nFactor authentication
Support for FIDO2-based authentication
Support for configuring storage of authentication tokens on the on-premises deployment

Was this helpful

Authenticate

Client certificate authentication

To configure the XenApp farm

To configure the Citrix Gateway appliance

To configure the mobile device

Configure Rewrite policy for authentication process

Support certificate-based authentication for on-premises stores

Smart cards

To configure Citrix Workspace app to access apps

Support for the twocanoes smart card utility reader

YubiKey support for smart card authentication

Support for multiple certificates in smart card authentication

RSA SecurID authentication

To import an RSA SecurID soft token

To use an RSA soft token

Next Token Code

Derived credentials

Known limitations

User-agent string for WKWebView

nFactor authentication

Support for multi-factor (nFactor) authentication

nFactor Advanced authentication policy support

Support for FIDO2-based authentication

Support for configuring storage of authentication tokens on the on-premises deployment

In this article