Configure NetScaler Gateway

Important:

We recommend that you create NetScaler snapshots or save the NetScaler configuration before applying these changes.

  1. Download the script from https://www.citrix.com/downloads/citrix-secure-private-access/Shell-Script/Shell-Script-for-Gateway-Configuration.html.

    To create a new NetScaler Gateway, use ns_gateway_secure_access.sh. To update an existing NetScaler Gateway, use ns_gateway_secure_access_update.sh.

  2. Upload these scripts to the NetScaler machine. You can use the WinSCP app or the SCP command. For example, *scp ns_gateway_secure_access.sh nsroot@nsalfa.fabrikam.local:/var/tmp*.

    Note:

    • It’s recommended to use NetScaler /var/tmp folder to store temp data.
    • Make sure that the file is saved with LF line endings. FreeBSD does not support CRLF.
    • If you see the error -bash: /var/tmp/ns_gateway_secure_access.sh: /bin/sh^M: bad interpreter: No such file or directory, it means that the line endings are incorrect. You can convert the script by using any rich text editor, such as Notepad++.
  3. SSH to NetScaler and switch to shell (type ‘shell’ on NetScaler CLI).
  4. Make the uploaded script executable. Use the chmod command to do so.

    chmod +x /var/tmp/ns_gateway_secure_access.sh

  5. Run the uploaded script on the NetScaler shell.

    NetScaler configuration 1

  6. Input the required parameters. For the list of parameters, see Prerequisites.

    For authentication profile and SSL certificate you have to provide names on NetScaler.

    A new file with multiple NetScaler commands (the default is var/tmp/ns_gateway_secure_access) is generated.

    NetScaler configuration 2

  7. Switch to the NetScaler CLI and run the resultant NetScaler commands from the new file with the batch command. For example, batch -fileName /var/tmp/ns_gateway_secure_access -outfile /var/tmp/ns_gateway_secure_access_output

    NetScaler runs the commands from the file one by one. If a command fails, it continues with the next command.

    A command can fail if a resource exists or one of the parameters entered in step 6 is incorrect.

  8. Ensure that all commands are successfully completed.

Note:

If there’s an error, NetScaler still runs the remaining commands and partially creates/updates/binds resources. Therefore, if you see an unexpected error because of one of the parameters being incorrect, it’s recommended to redo the configuration from the start.

Configure Secure Private Access on a NetScaler Gateway with existing configuration

You can also use the scripts on an existing NetScaler Gateway to support Secure Private Access. However, the script does not update the following:

  • Existing NetScaler Gateway virtual server
  • Existing session actions and session policies bound to NetScaler Gateway

Ensure that you review each command before execution and create backups of the gateway configuration.

Settings on NetScaler Gateway virtual server

When you add or update the existing NetScaler Gateway virtual server, ensure that the following parameters are set to the defined values.

tcpProfileName: nstcp_default_XA_XD_profile deploymentType: ICA_STOREFRONT icaOnly: OFF

Examples:

To add a virtual server:

`add vpn vserver _SecureAccess_Gateway SSL 192.0.2.210 443 -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -deploymentType ICA_STOREFRONT -vserverFqdn gateway.mydomain.com -authnProfile auth_prof_name -icaOnly OFF`

To update a virtual server:

`set vpn vserver  _SecureAccess_Gateway -icaOnly OFF`

For details on the virtual server parameters, see vpn-sessionAction.

NetScaler Gateway session actions

Session action is bound to a gateway virtual server with session policies. When you create a session action, ensure that the following parameters are set to the defined values.

  • transparentInterception: OFF
  • SSO: ON
  • ssoCredential: PRIMARY
  • useMIP: NS
  • useIIP: OFF
  • icaProxy: OFF
  • wihome: "https://storefront.mydomain.com/Citrix/MyStoreWeb" - replace with real store URL
  • ClientChoices: OFF
  • ntDomain: mydomain.com - used for SSO
  • defaultAuthorizationAction: ALLOW
  • authorizationGroup: SecureAccessGroup (Make sure that this group is created, it’s used to bind Secure Private Access specific authorization policies)
  • clientlessVpnMode: ON
  • clientlessModeUrlEncoding: TRANSPARENT
  • SecureBrowse: ENABLED
  • Storefronturl: "https://storefront.mydomain.com"
  • sfGatewayAuthType: domain

Examples:

To add a session action:

add vpn sessionAction AC_OS_SecureAccess_Gateway -transparentInterception OFF -SSO ON -ssoCredential PRIMARY -useMIP NS -useIIP OFF -icaProxy OFF -wihome "https://storefront.mydomain.com/Citrix/MyStoreWeb" -ClientChoices OFF -ntDomain mydomain.com -defaultAuthorizationAction ALLOW -authorizationGroup SecureAccessGroup -clientlessVpnMode ON -clientlessModeUrlEncoding TRANSPARENT -SecureBrowse ENABLED -storefronturl "https://storefront.mydomain.com" -sfGatewayAuthType domain

To update a session action:

set vpn sessionAction AC_OS_SecureAccess_Gateway -transparentInterception OFF -SSO ON

For details on session action parameters, see https://developer-docs.netscaler.com/en-us/adc-command-reference-int/13-1/vpn/vpn-sessionaction.

Compatibility with the ICA apps

NetScaler Gateway created or updated to support the Secure Private Access plug-in can also be used to enumerate and launch ICA apps. In this case, you must configure Secure Ticket Authority (STA) and bind it to the NetScaler Gateway. Note: STA server is usually a part of Citrix Virtual Apps and Desktops DDC deployment.

For details, see the following topics:

Support for smart access tags

In the following versions, NetScaler Gateway sends the tags automatically. You do not have to use the gateway callback address to retrieve the smart access tags.

  • 13.1.48.47 and later
  • 14.1–4.42 and later

Smart access tags are added as a header in the Secure Private Access plug-in request.

Use the toggle ns_vpn_enable_spa_onprem or ns_vpn_disable_spa_onprem to enable/disable this feature on these NetScaler versions.

  • You can toggle with command (FreeBSD shell):

    nsapimgr_wr.sh -ys call=ns_vpn_enable_spa_onprem

  • Enable SecureBrowse client mode for HTTP callout config by running the following command (FreeBSD shell).

    nsapimgr_wr.sh -ys call=toggle_vpn_enable_securebrowse_client_mode

  • To disable, run the same command again.

  • To verify whether the toggle is on or off run the nsconmsg command.

  • To configure smart access tags on NetScaler Gateway, see Configuring Custom Tags (SmartAccess Tags) on NetScaler Gateway.

Known limitations

  • Existing NetScaler Gateway can be updated with script but there can be an infinite number of possible NetScaler configurations that can’t be covered by a single script.
  • Do not use ICA Proxy on NetScaler Gateway. This feature is disabled when NetScaler Gateway is configured.
  • If you use NetScaler deployed in the cloud, you must make some changes in the network. For example, allow communications between NetScaler and other components on certain ports.
  • If you enable SSO on NetScaler Gateway, make sure that NetScaler communicates to StoreFront using a private IP address. You might have to add a new StoreFront DNS record to NetScaler with a StoreFront private IP address.

Upload public gateway certificate

If the public gateway is not reachable from the Secure Private Access machine, then you must upload a public gateway certificate to the Secure Private Access database.

Perform the following steps to upload a public gateway certificate:

  1. Open PowerShell or the command prompt window with the admin privileges.
  2. Change the directory to the Admin\AdminConfigTool folder under the Secure Private Access installation folder (for example, cd “C:\Program Files\Citrix\Citrix Access Security\Admin\AdminConfigTool”)
  3. Run the following command:

    \AdminConfigTool.exe /UPLOAD_PUBLIC_GATEWAY_CERTIFICATE <PublicGatewayUrl> <PublicGatewayCertificatePath>