Deployment Guide: Citrix Secure Private Access On-Premises

Audience

This document is intended for architects, network designers, technical professionals, partners, and consultants interested in implementing the Citrix Secure Private Access On-Premises solution. It is also designed for network administrators, Citrix administrators, managed service providers, or anyone looking to deploy this solution.

Solution Overview

CitrixSecure Private Access本地是一个customer-managed零及信任rk Access (ZTNA) solution that provides VPN less access to Internal web and SaaS applications with least privilege principle, single sign-on (SSO), Multifactor Authentication and Device posture assessment, application-level security controls and app protection features along with a seamless end-user experience. The solution leverages the StoreFront on-premises and Citrix Workspace app to enable a seamless and secure access experience to access web and SaaS apps within Citrix Enterprise Browser. This solution also leverages the NetScaler Gateway to enforce authentication and authorization controls.

Citrix Secure Private Access On-Premises solution enhances an organization’s overall security and compliance posture with the ability to easily deliver Zero Trust access to browser-based (internal web apps and SaaS apps) using the StoreFront on-premises portal as a unified access portal to web and SaaS apps, along with virtual apps, and desktops as an integrated part of Citrix Workspace.

Citrix Secure Private Access combines elements of NetScaler Gateway and StoreFront to deliver an integrated experience for end users and administrators.

Use Cases

Citrix Secure Private Access (SPA) On-Premises solution with Citrix Virtual Apps and Desktops (CVAD) On-Premises provides a unified and secure end-user experience to both virtualized resources and browser-based apps (web apps and SaaS apps) with consistent security.

SPA On-Premises solution is designed to address the following use cases by using a customer-managed solution.

Use case #1:Secure access for Employees & Contractors to internal web and SaaS apps from managed or unmanaged devices without publishing a browser or using VPN.

Use case #2:Provide comprehensive last mile Zero Trust enforcement with admin configurable browser security controls for internal web and SaaS apps from managed or unmanaged devices without publishing a browser or using VPN.

Use case #3:Accelerate Merger & Acquisitions (M & A) user access across multiple identity providers, ensure consistent security, and provide seamless end-user access across multiple user groups.

Requirements

This article provides step-by-step guidance to deploy Secure Private Access with StoreFront and NetScaler Gateway. Citrix Enterprise Browser (incl. in Citrix Workspace app) is the client software used to securely interact with your SaaS or internal web apps.
Global App Config Service (GACS) is a requirement for browser management of Citrix Enterprise Browser.
This guide assumes the reader has a basic understanding of the following Citrix and NetScaler offerings and general Windows administrative experience:

• Citrix Virtual Apps and Desktops
• StoreFront
• NetScaler Gateway
• Global App Configuration service

Versions:

• Citrix Workspace app
  • Windows– 2303 and above
  • macOS– 2304 and above
• Citrix Virtual Apps and Desktops – Supported LTSR and current versions
• StoreFront – LTSR 2203 or non-LTSR 2212 and above
• NetScaler Gateway – 12.1 and above

Refer to the following documentation for more details as needed:

• Citrix Virtual Apps and Desktops
  • System requirements
  • Technical Overview
• StoreFront
  • System requirements
  • Plan your StoreFront deployment
• NetScaler Gateway
  • Before Getting Started
  • Common Citrix Gateway deployments
• Global App Configuration service (GACS)
  • Manage Citrix Enterprise Browser through Global App Configuration service

Technical Overview

Access to internal web apps is possible from any location with any device at any time through NetScaler Gateway with Citrix Enterprise Browser (incl. in Citrix Workspace app) installed. The same applies to SaaS apps, with the difference that the access can be direct or indirect through NetScaler Gateway.

Citrix Enterprise Browser and Citrix Workspace app talk to NetScaler Gateway using a TLS-encrypted connection. NetScaler Gateway provides zero trust-based access by assessing the user’s device, strong nFactor user authentication, app authorization, and single sign-on (SSO).
Citrix Enterprise Browser uses the Citrix Secure Browse protocol to allow access to internal domain names(for example,https://website.company.local)without needing a public-facing DNS name.
Citrix Secure Private Access with Citrix Enterprise Browser allows the configuration of additional security control for web apps like Watermarking, copy/paste-, up/download-, and print restrictions. These restrictions are configured in a file called “policy.json”.

Configuration process

IMPORTANT

A config tool is available to quickly onboard apps and policies for the apps and also configure NetScaler Gateway and StoreFront settings.
However, note the following before using the tool.

• Read thePublish a web applicationandCreate and publish the policy filesections to ensure that you have the complete understanding of the configuration requirements for the on-premises solution configuration.
• This tool can only be used as a complement to the existing procedures documented in this topic and does not replace the configuration that must be performed manually.

For complete details about the tool, seeConfigure apps and policies using the Secure Private Access config tool.

Step 1 – Publish a web application

Initial publishing of a new web app uses a Windows PowerShell cmdlet installed with Citrix Virtual Apps and Desktops. As soon as the web app is created, future editing can be done using the Citrix Studio console.

• Open a Windows PowerShell on a machine with the PowerShell SDK installed.
• Run the following command to load the Citrix cmdlets:
  Add-PSSnapIn citrix*
• Define the necessary variables for the web app:
  Before running the commands, replace the placeholders marked with angle brackets. (< >)

$deliveryGroupName = "" $appURL = "" $appName = "" $appIconFilePath = "" $appDescription = "KEYWORDS:SPAENABLED" 

Example

$deliveryGroupName = "CVAD-On-Prem" $appURL = "https://finance.training.local" $appName = "Finance-Portal" $appIconFilePath = "C:\temp\Icon\finance.ico" $appDescription = "KEYWORDS:SPAENABLED" 

• Run the following commands to publish the new web app:

$deliveryGroupUid = (Get-BrokerDesktopGroup -Name $deliveryGroupName).Uid New-BrokerApplication -ApplicationType PublishedContent -CommandLineExecutable $appURL -Name $appName -DesktopGroup $deliveryGroupUid -Description $appDescription 

• (Optional)Run the following commands to change the icon on the web app:

$encodedIconData = [convert]::ToBase64String((Get-Content $appIconFilePath -Encoding byte)) New-BrokerIcon -EncodedIconData $encodedIconData $UidEncode = Get-BrokerIcon | Select-Object Uid $testUid = $UidEncode[-1].Uid $IconUid = [int]$testUid Set-BrokerApplication -name $appName -IconUid $IconUid 

• Run the following command to verify the web app:

Get-BrokerApplication -ApplicationType PublishedContent | Format-Table @{Label="Type"; Expression={$_.ApplicationType}},Name,@{Label="URL"; Expression={$_.CommandLineExecutable}},@{Label="Delivery group"; Expression={(Get-BrokerDesktopGroup -Uid $_.AssociatedDesktopGroupUids[0]).Name}},Description 

Example output

Type	Name	URL	Delivery group	Description
PublishedContent	Finance-Portal	https://finance.training.local	CVAD-On-Prem	KEYWORDS:SPAENABLED
PublishedContent	Doctor	https://doctor.training.local	CVAD-On-Prem	KEYWORDS:SPAENABLED

• InCitrix Studio, under theApplicationssection, you see the new web application.
  未来所有的changes are done in the Citrix Studio console.

Note

For more information on how to publish content, clickhere.
For more information on how to change the default icon, clickhere.

Step 2 – Create and publish the policy file

The policy file namedpolicy.jsondefines each published web app’s routing and security controls.
For example, should an Office 365 SaaS app have security controls enabled and routed through your data center, or should the traffic go direct?

Note: If you know the policy file structure and values, continue withComplete policy.json file example.

Policy file structure

The policy file is in JSON format and contains the following sections:

• policies
  The policies section defines security controls and traffic routing for all published SaaS/web apps. For non-published websites, a catch-all policy is defined.
  Note: If the web app consists of different domain names, you must specify all to apply the security controls correctly.

The following table lists the available access policy options and their values:

Note

The valueenabledstands forALLOWanddisabledforBLOCK.

Anti-key loggingandanti-screen capturingrequire the installation of the App protection feature that comes with the Citrix Workspace app.

Template

"policies": [{ "name": "", "patterns": ["/*", "/*"], "policy": { "watermark_v1": "disabled", "clipboard_v1": "disabled", "printing_v1": "disabled", "download_v1": "disabled", "upload_v1": "disabled", "keylogging_v1": "disabled", "screencapture_v1": "disabled", "proxytraffic_v1": "secureBrowse", "browser_v1": "embeddedBrowser" } }, { "patterns": ["*/*"], "policy": { "proxytraffic_v1": "direct", } } ] 

• system
  The system section defines the NetScaler Gateway address to which the traffic is routed.

Template

"system": { "secureBrowseAddress": "https://" } 

Complete policy.json file example

{ "policies": [{ "name": "Finance-Portal", "patterns": ["*.finance.training.local/*"], "policy": { "watermark_v1": "enabled", "clipboard_v1": "enabled", "printing_v1": "disabled", "download_v1": "disabled", "upload_v1": "disabled", "keylogging_v1": "disabled", "screencapture_v1": "disabled", "proxytraffic_v1": "secureBrowse", "browser_v1": "embeddedBrowser" } }, { "name": "Doctor", "patterns": ["*.doctor.training.local/*"], "policy": { "watermark_v1": "disabled", "clipboard_v1": "disabled", "printing_v1": "enabled", "download_v1": "enabled", "upload_v1": "enabled", "keylogging_v1": "disabled", "screencapture_v1": "disabled", "proxytraffic_v1": "secureBrowse", "browser_v1": "embeddedBrowser" } }, { "patterns": ["*/*"], "policy": { "proxytraffic_v1": "direct" } } ], "system": { "secureBrowseAddress": "https://citrix.training.com" } } 

Policy file location

Thepolicy.jsonfile must be placed on each StoreFront server at
C:\inetpub\wwwroot\Citrix\\Resources\SecureBrowser.

Note: The folder structure “Resources” and “SecureBrowser” must be created first.

Example

In this example, we use the default StoreFront store called “Store”.

mkdir C:\inetpub\wwwroot\Citrix\Store\Resources mkdir C:\inetpub\wwwroot\Citrix\Store\Resources\SecureBrowser 

Place thepolicy.jsonfile into the “SecureBrowser” directory.

Verify policy file download

• Open an installed web browser on your StoreFront server.
• Navigate to the following addresshttps:///Citrix//Resources/SecureBrowser/policy.jsonand download the policy file.
  Before running the download, replace the placeholders marked with angle brackets. (< >)
  Example:https://xa02.training.local/Citrix/Store/Resources/SecureBrowser/policy.json
• The file should download successfully.

Note

Follow the steps below if an IIS 404.7 error page shows up, indicatingRequest Filteringis blocking the download.

• OpenInternet Information Services (IIS) Manager.
• Navigate to the previously createdSecureBrowserfolder.
• In theFeature Viewsection, double-clickRequest Filtering.
• In theActionpane, clickAllow File Name Extension.
• Enter “.json” and clickOK.
• Test the download again.

For more information on how to configure Request Filtering, clickhere.

StoreFront store web.config

To make the new policy details available for the Citrix Workspace app and Citrix Enterprise Browser, we must modify theweb.configfile in the StoreFront store directory.
(For example, C:\inetpub\wwwroot\Citrix\Store\web.config)

• Create a backup of the currentweb.configfile atC:\inetpub\wwwroot\Citrix\\
  Example:copy C:\inetpub\wwwroot\Citrix\Store\web.config C:\inetpub\wwwroot\Citrix\Store\web.config.orig
• Open notepad, insert the following code and save the file asModifyWebConf.ps1to correctly edit theweb.configfile.

function Editwebconf { param ( [parameter(Mandatory = $true)][String]$Global:webconfigfile ) # Read in the contents of the file $content = Get-Content $Global:webconfigfile # Define the multi-line string you want to replace $oldText = '' # Define the new string you want to replace it with $newText = '           ' # Iterate through each line in the content and replace the old text with the new text for ($i = 0; $i -lt $content.Count; $i++) { if ($content[$i] -match '') { Write-Host "web.config has already been modified" exit } if ($content[$i] -match $oldText) { $content[$i] = $content[$i] -replace $oldText, $newText } } # Write the modified content back to the file Set-Content $Global:webconfigfile $content Write-Host "$newText" } Editwebconf 

• Open a Windows PowerShell.
• Switch to the directory ofModifyWebConf.ps1.
• Run the following command.\ModifyWebConf.ps1.
• When prompted for theGlobal:webconfigfile:, insert the full path, including the file name to your web.conf file.
  Example:C:\inetpub\wwwroot\Citrix\Store\web.config

Output

p C: \ temp \ ModifyWebConf >。ps1 cmdlet Editwebconfat command pipeline position 1 Supply values for the following parameters: Global:webconfigfile: C:\inetpub\wwwroot\Citrix\Store\web.config             

Step 3 – On-Premises NetScaler Gateway configuration

The NetScaler Gateway configuration includes four essential steps:

• Enable clientless access
• Configure web address encoding
• Enable Secure Browse
• 排除在clientless域被重写access mode

Note

Clientless access only works whenICA Onlyis set tofalseon the NetScaler Gateway virtual server.(Default setting on new deployments)

For clientless access to work with StoreFront, specify a Callback URL within your StoreFront configuration.

Access to published web apps is only possible using the Citrix Workspace app and Citrix Enterprise Browser.

Enable clientless access

Clientless access is required for Citrix Enterprise Browser to connect to web apps.

There are two options to enable clientless access:

• Globally – all users
• Session policy – selected group or users

Citrix recommends enabling it per session policy to allow better control of clientless access.

Clientless access Globally

Globally enabled clientless access applies to all configured NetScaler Gateway virtual servers.

You can either enable it using the NetScaler GUI or CLI.

• NetScaler GUI

  1. On the Configuration tab, expandCitrix Gatewayand then clickGlobal Settings.
  2. In the Global Settings page, clickChange global settings.
  3. On theClient Experiencetab, selectOnforClientless Access.
  4. On thePublished Applicationstab, selectOFFforICA Proxy, and clickOK.

• NetScaler CLI

  1. Run the following command:
     set vpn parameter -clientlessVpnMode On -icaProxy OFF

Clientless access Session policy

Configuring clientless access per session policy allows for narrowing down the setting for users, groups, or Gateway virtual servers. Creating a new session policy/action with the same settings is good for easily switching betweenicaProxyandclientless accessconfiguration.

You can either enable it using the NetScaler GUI or CLI.

• NetScaler GUI

  1. On the Configuration tab, expand Citrix Gateway, expandPolicies, and then clickSession.
  2. In the Session page, switch to theSession Profilestab and open the session profile for the Citrix Workspace app.(for example, AC_OS_192.168.0.100)
  3. On theClient Experiencetab, next toClientless Access, clickOverride Global, selectOn.
  4. On thePublished Applicationstab, next toICA Proxy, clickOverride Global, selectOFF, and clickOK.

• NetScaler CLI
  1. Run the following command:
     Before running the command, replace the placeholders marked with angle brackets. (< >)
     set vpn sessionAction -clientlessVpnMode On -icaProxy OFF

Configure web address encoding

Enabling clientless access allows you to encode the addresses of internal web apps or leave the address as clear text. Clientless access URL encoding is recommended to be set toclear.

There are two options to set clientless access URL encoding:

• Globally – all users
• Session policy – selected group or users

URL encoding Globally

Globally enabled clientless access applies to all configured NetScaler Gateway virtual servers.

You can either enable it using the NetScaler GUI or CLI.

• NetScaler GUI
  1. On the Configuration tab, expandCitrix Gatewayand then clickGlobal Settings.
  2. In the Global Settings page, clickChange global settings.
  3. On theClient Experiencetab, selectClearforClientless Access URL Encoding, and clickOK.

• NetScaler CLI
  1. Run the following command:
     set vpn parameter -clientlessModeUrlEncoding TRANSPARENT

URL encoding Session policy

Configuring clientless access URL encoding per session policy allows for narrowing down the setting for users, groups, or Gateway virtual servers.

You can either enable it using the NetScaler GUI or CLI.

• NetScaler GUI
  1. On the Configuration tab, expand Citrix Gateway, expandPolicies, and then clickSession.
  2. In the Session page, switch to theSession Profilestab and open the session profile for the Citrix Workspace app.(for example, AC_OS_192.168.0.100)
  3. On theClient Experiencetab, next toClientless Access URL Encoding, clickOverride Global, selectClear, and clickOK.

• NetScaler CLI
  1. Run the following command:
     Before running the command, replace the placeholders marked with angle brackets. (< >)
     set vpn sessionAction -clientlessModeUrlEncoding TRANSPARENT

Enable Secure Browse

Citrix Enterprise Browser uses the secure browse mode to access apps without needing a legacy VPN.

There are two options to configure secure browse mode:

• Globally – all users
• Session policy – selected group or users

Secure Browse Globally

启用全局安全浏览适用于所有相依igured NetScaler Gateway virtual servers.

You can either enable it using the NetScaler GUI or CLI.

• NetScaler GUI
  1. On the Configuration tab, expandCitrix Gatewayand then clickGlobal Settings.
  2. In the Global Settings page, clickChange global settings.
  3. On theSecuritytab, selectENABLEDforSecure Browse, and clickOK.

• NetScaler CLI
  1. Run the following command:
     set vpn parameter -secureBrowse ENABLED

Secure Browse Session policy

Configuring Secure Browse per session policy allows for narrowing down the setting for users, groups, or Gateway virtual servers.

You can either enable it using the NetScaler GUI or CLI.

• NetScaler GUI
  1. On the Configuration tab, expand Citrix Gateway, expandPolicies, and then clickSession.
  2. In the Session page, switch to theSession Profilestab and open the session profile for the Citrix Workspace app.(for example, AC_OS_192.168.0.100)
  3. On theSecuritytab, next toSecure Browse, clickOverride Global, selectENABLED, and clickOK.

• NetScaler CLI
  1. Run the following command:
     Before running the command, replace the placeholders marked with angle brackets. (< >)
     set vpn sessionAction -secureBrowse ENABLED

排除在clientless域被重写access mode

After enabling clientless access mode, NetScaler will do server-side rewrites for “/cvpn” requests. ExcludeStoreFront server FQDN(s)orStoreFront Load Balancer FQDNandcitrix.com.

This configuration is only available in the global NetScaler Gateway settings.

You can either configure the exclusion using the NetScaler GUI or CLI.

• NetScaler GUI
  1. On the Configuration tab, expandCitrix Gatewayand then clickGlobal Settings.
  2. In the Global Settings page, clickConfigure Domains for Clientless Access.
  3. SelectExclude Domains, insert theStoreFront server FQDN(s)or theStoreFront Load Balancer FQDN, and click thePlus.
  4. Repeat step 3 forcitrix.com.
  5. ClickOK.

• NetScaler CLI

  1. Run the following command:
     Before running the command, replace the placeholders marked with angle brackets. (< >)

     bind policy patset ns_cvpn_default_bypass_domains  bind policy patset ns_cvpn_default_bypass_domains citrix.com 

Step 4 – Authorizing users to access published web apps

Publishing web apps in CVAD does not allow you to control user access. This has to be done on NetScaler Gateway using Authorization policies. Authorization policies are bound to a user or group.

It is essential to know how the policies are applied:

• User
• Group

User policies always have a higher priority than group-bound policies. Allowing a website at the user level and denying this site at a group level will allow access, whatever of whether the policy priority on the group level is higher.

Multiple policies bound to the same user or group are differentiated by priority. Knowing that the higher priority (low number) matches before the lower priority (high number) is essential. Ensure that allowed policies have a higher priority than denied policies.

We recommend creating a group per published web application to control access permissions.(Zero trust approach)

Default authorization policies

Two authorization policies should be created per default to allow access to the StoreFront server and deny access to all published web apps:

• Allow_StoreFront
• Deny_ALL

Web app authorization policies

Now that we have the default authorization policies, the next step is creating authorization policies for each published web app.

• Allow_
• Allow_

Creating authorization policies

You can either configure the authorization policies using the NetScaler GUI or CLI.

• NetScaler GUI
  1. On the Configuration tab, expandCitrix Gateway, expandPolicies, and clickAuthorization.
  2. On the Authorization page, clickAdd.
  3. Insert an authorization policyName, select theAction, selectAdvanced Policyand create yourExpression.
  4. ClickCreate.

• NetScaler CLI
  1. Run the following command:
     Before running the command, replace the placeholders marked with angle brackets. (< >)
     add authorization policy "HTTP.REQ.HOSTNAME.CONTAINS(\"\")" ALLOW

Example

Default authorization policies:

add authorization policy Allow_StoreFront "HTTP.REQ.HOSTNAME.CONTAINS(\"\")" ALLOW add authorization policy Deny_ALL true DENY 

Web app authorization policies:

add authorization policy Allow_Finance "HTTP.REQ.HOSTNAME.CONTAINS(\"finance.training.local\")" ALLOW add authorization policy Allow_Doctor "HTTP.REQ.HOSTNAME.CONTAINS(\"doctor.training.local\")" ALLOW 

Binding authorization policies

You can either bind the authorization policies using the NetScaler GUI or CLI.

• NetScaler GUI
  1. On the Configuration tab, expandCitrix Gateway, expandUser Administration, and clickAAA GroupsorAAA Groups.
  2. In the AAA Groups or AAA Users page, clickAdd.
  3. Insert a User or GroupNameand clickOK.
  4. InAdvanced SettingsclickAuthorization Policies.
  5. In thePolicy Bindingpage, select a policy to bind, set thePriority, as type selectRequest, and clickBind.
  6. Repeat step 5 for each policy to bind.
  7. ClickDone.

• NetScaler CLI

  1. Run the following command:
     Before running the command, replace the placeholders marked with angle brackets. (< >)

     add aaa group  bind aaa group  -policy  -priority  -gotoPriorityExpression END 

Example

User - Allow access to a specific published web app:

add aaa user testuser01 bind aaa user testuser01 -policy Allow_Doctor -priority 63000 -gotoPriorityExpression END 

Group - Allow access to the published web app, StoreFront, and deny all other requests:

add aaa group Doctor bind aaa group Doctor -policy Allow_Doctor -priority 10 -gotoPriorityExpression END bind aaa group Doctor -policy Allow_StoreFront -priority 999 -gotoPriorityExpression END bind aaa group Doctor -policy Deny_ALL -priority 1000 -gotoPriorityExpression END 

add aaa group Finance bind aaa group Finance -policy Allow_Finance -priority 10 -gotoPriorityExpression END bind aaa group Finance -policy Allow_StoreFront -priority 999 -gotoPriorityExpression END bind aaa group Finance -policy Deny_ALL -priority 1000 -gotoPriorityExpression END 

Testing

• Open and log in to the Citrix Workspace app on an internal or external client

Troubleshooting

成功登录后看到一条错误消息in, refer toNetScaler - No Intranet IP available.

• Launch web app
  Note: The logged-on user can access theDoctorapplication but is denied access toFinance-Portal.

Doctor

Finance-Portal

Troubleshooting

Seeing an error code in the Citrix Enterprise Browser:

• PS1001
• PS1003

Visibility, Monitoring, and Troubleshooting

ADM – Gateway Insight
Gateway Insight provides visibility into the failures encountered by all users, regardless of the access mode, at the time of logging on to NetScaler Gateway. View a list of all available users, number of active users, number of active sessions, and bytes and licenses used by all users at any given time. View the end-point analysis (EPA), authentication, single sign-on (SSO), and application launch failures for a user.

For more information, refer toADM – Gateway Insight documentation.

Citrix Director
Citrix Director’s troubleshooting dashboard provides real-time and historical health monitoring of the Citrix Virtual Apps or Desktops site. This allows seeing failures in real time, providing a better idea of what the end users are experiencing.

For more information, refer toCitrix Virtual Apps and Desktops – Director documentation.

Summary

Citrix Secure Private Access for on-premises allows zero trust-based access to SaaS and internal web apps. This deployment guide covered the specific steps necessary to publish web apps and set security controls. The end result is an integrated solution with true single sign-on for users to access SaaS and internal web apps the same way as virtual apps.

Deployment Troubleshooting

NetScaler - No Intranet IP available

After a successful login to the Citrix Workspace app, the user does not see applications, and the following message is written inns.log.
default SSLVPN Message 659106 0 : "Failed to process setclient for id , user due to "

This is a known issue (CTX461242) and can be solved by settingUse Mapped IPtoNSandUse Intranet IPtoOFFin your session profile for Citrix Workspace app.

NetScaler GUI:

NetScaler CLI:
set vpn sessionAction AC_OS_192.168.0.100 -useMIP NS -useIIP OFF

CEB – PS1001

This error code indicates that the Citrix Workspace app cannot fetch the “policy.json” file from StoreFront.
Review the following sections:

• Policy file location
• StoreFront store web.config
• Step 3 - On-Premises NetScaler Gateway configuration

CEB – PS1003

This error code indicates something is wrong with the “policy.json” file.
Review the sectionComplete policy.json file example.