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.

   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.

   

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

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

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

   Note:

   During script execution, NetScaler and Secure Private Access plug-in compatibility is checked. If NetScaler supports the Secure Private Access plug-in, the script enables NetScaler features to support smart access tags sending improvements and redirection to a new Deny Page when access to a resource is restricted. For details about smart tags, see Support for smart access tags.

   The Secure Private Access plug-in features persisted in the /nsconfig/rc.netscaler file allow to keep them enabled after NetScaler is restarted.

   

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.

Add a virtual server:

• tcpProfileName: nstcp_default_XA_XD_profile
• deploymentType: ICA_STOREFRONT (available only with the add vpn vserver command)
• icaOnly: OFF
• dtls: OFF

Update a virtual server:

• tcpProfileName: nstcp_default_XA_XD_profile
• icaOnly: OFF

Examples:

To add a virtual server:

add vpn vserver _SecureAccess_Gateway SSL 999.999.999.999 443 -Listenpolicy NONE -tcpProfileName nstcp_default_XA_XD_profile -deploymentType ICA_STOREFRONT -vserverFqdn gateway.mydomain.com -authnProfile auth_prof_name -icaOnly OFF - dtls: 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 action

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. Path to Store /Citrix/MyStoreWeb is optional.
• ClientChoices: OFF
• ntDomain: mydomain.com - used for SSO (optional)
• 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>.

To bind the Secure Private Access plug-in to the VPN virtual server.

bind vpn vserver spaonprem -appController "https://spa.example.corp"

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:

• Configuring the Secure Ticket Authority on NetScaler Gateway
• FAQ: Citrix Secure Gateway/ NetScaler Gateway Secure Ticket Authority

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.

Configure Secure Private Access toggles

The following table lists the toggles that must be used to support smart access tags for on-premises deployments:

Note:

• To disable the toggles that do not have separate disable commands, run the same command again. This is applicable only for commands that have “toggle” in the command.
• To verify whether the toggle is on or off run the nsconmsg command.
• To configure smart access tags on NetScaler Gateway, see Configure contextual tags.

Persist Secure Private Access plug-in settings on NetScaler

To persist the Secure Private Access plug-in settings on NetScaler, do the following:

1. Create or update the file /nsconfig/rc.netscaler.

2. Add the following commands to the file.

   nsapimgr -ys call=ns_vpn_enable_spa_onprem

   nsapimgr -ys call=toggle_vpn_enable_securebrowse_client_mode

   nsapimgr -ys call=toggle_vpn_redirect_to_access_restricted_page_on_deny

   nsapimgr -ys call=toggle_vpn_use_cdn_for_access_restricted_page

3. Save the file.

The Secure Private Access plug-in settings are automatically applied when NetScaler is restarted.

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>

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.
• We recommend that you set ICA Proxy to OFF in the Secure Private Access enabled VPN virtual server.
• 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. For details on the ports, see Communication 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.