Solution for Citrix Optimal Gateway Routing

Introduction

On the heels of a very well written DevCentral article by Steve Lyons, Smart Card Authentication to Citrix StoreFront Using F5 Access Policy Manager, where he documented how to configure F5 BIG-IP APM to provide SSO Smart Card Authentication to Citrix StoreFront I figured it was time to publish another APM/Citrix related article for the community. A customer of mine was going to be replacing Citrix ADCs (NetScalers) with F5 APM throughout their enterprise to provide SSO SmartCard authentication to StoreFront along with ICA traffic proxying. There is a freely available iApp available for your APM that will help with this configuration.

However, this iApp solution is only appliable if you are authenticating to StoreFront AND proxying your ICA traffic through the same F5 APM. And of course, this was not the configuration my customer was looking to implement. The existing Citrix ADC based implementation was configured to take advantage of something Citrix calls Optimal Gateway Routing (OGR); sometimes referred to as Optimal HDX Routing.

Table of Contents

• What is OGR
• The F5 Problem
• The F5 Solution
• Configuration Steps
  • F5 APM SF-GW Configuration
    • iRule - Create STA Resolution Halt
    • iRule - Create Citrix Logged Out
  • F5 APM ICA-GW Configuration
    • iRule - Extract Citrix STA
    • iRule - Resolve Citrix STA

What is OGR?

OGR for Citrix Storefront is a design whereby a Citrix web client is directed to an ICA Proxy Gateway (ICA-GW) anywhere in the world that is closest to the app/desktop hosting environment (XenApp and XenDesktop servers) which may not be on the same Citrix StoreFront ADC (NetScaler) Gateway (SF-GW) which has authenticated the user. This is in contrast to being directed to a single ADC Gateway device that hosts SF-GW and ICA-GW. In a Citrix ADC deployment, the ICA-GW (not the SF-GW) is responsible for validating/resolving the STA ticket provided by a Secure Ticket Authority (STA) server. Since the ICA-GW is responsible for this validation, it allows OGR to function and send ICA traffic to a different ICA-GW than what was used to download the ICA file from StoreFront.

Figure 1: Suboptimal Gateway Routing

 

Figure 2: Optimal Gateway Routing

The F5 Problem(link back to Top of page)

The F5 Access Policy Manager (APM) can be used to simultaneously replace a Citrix ADC for both the StoreFront Authentication process as well as the ICA Proxy process. In contrast to how Citrix ADC processes a downloaded ICA file, the F5 APM Citrix VDI plugin is designed to validate/resolve the STA ticket with the STA server upon download of the ICA proxy file from the StoreFront server. The validation details are stored locally in the APM SF-GW access session table. This session table is not shared amongst APM devices in the enterprise. So, if the ICA file then directs the client to a different APM device (ICA-GW) by virtue of the ICA file entry:

SSLProxyHost=[ICA-Proxy-FQDN]:443

than what was used to download the ICA file (APM SF-GW), the APM ICA-GW will NOT have knowledge of the already validated/resolved STA ticket. The APM Citrix VDI plugin does not perform validation/resolution of the STA ticket upon launching the ICA file. The APM ICA-GW will then terminate the app/desktop session.

The F5 Solution(link back to Top of page)

In order to support Citrix Optimal Gateway Routing in a distributed gateway environment, the following configuration can be used.

The APM SF-GW is responsible for authentication, proxying StoreFront application/desktop enumeration, and app/desktop ICA file retrieval.

When a client requests an app, StoreFront will create an ICA file based on information it has retrieved from the DDCs and STA servers, send it to the APM SF-GW, which will then send the ICA file to the client. An iRule attached to the virtual server on the APM SF-GW will prevent STA validation upon download.

The client can then launch the ICA file which contains a line:

SSLProxyHost=[ICA-Proxy-FQDN]:443

directing the connection to an APM ICA-GW. The APM reads the ICA request, pulls out the STA server shortname referenced in the payload:

Address=;40;STA12345678;0123456789ABCDEF0123456789ABCD

which is the same STA server that StoreFront connected to, and matches that to a URL for the STA server using a pre-configured datagroup. Then APM ICA-GW connects to the STA server in order to validate the STA ticket included in the ICA payload. STA validation variables are stored in an APM access session table. 

Now that the STA ticket has been validated, the APM will proxy the ICA traffic to the app server.

Configuration Steps(link back to Top of page)

Assumptions:

1.    Citrix StoreFront and DDCs are configured for external client access utilizing HDX routing which requires the configuration of Secure Ticket Authority (STA) servers similar to the following:

 
Figure 3: StoreFront server, “Citrix StoreFront” applet -> Stores -> “Manage Netscaler Gateways” -> Edit

 

Figure 4: StoreFront server, “Citrix StoreFront” -> “Configure Store Settings” -> “Optimal HDX routing”

F5 APM SF-GW Configuration(link back to Top of page)

Creating a StoreFront AD Authentication Access Policy

1. Navigate to Access ›› Profiles / Policies : Access Profiles (Per-Session Policies) and click Create
2. General Properties
3. Name: sta_resolver_ap
4. Profile Type: All
5. Customization Type: Modern
6. Configurations
7. Logout URI Include: /Citrix/UDF_storeWeb/Authentication/Logoff
8. Note: replace UDF_storeWeb with the appropriate StoreFront related Store name for your Storefront environment
9. Language Settings
10. Configure your desired Language settings and click Finished

When you are returned to the previous page displaying all access profiles, select Edit from the newly created policy to open the Visual Policy Editor (VPE)

1. Between Start and Deny, select the +
2. From the Logon tab, click the “Logon Page” radio button and click Add Item. Accept the Logon Page Agent default settings. Click Save
3. Click the “+” (plus sign) to the right of the Logon Page object
4. From the Authentication tab, select your preferred method of authentication. This should match up with the authentication method the StoreFront is expecting to consume. For the purpose of this article, we are using “AD Auth”. The configuration of the AD server is beyond the scope of this article. Click Add Item. Complete the Authentication configuration per AAA guidelines. Click Save.
5. Click the “+” (plus sign) to the right of the Authentication object
6. Select the Assignment tab. Select the SSO Credential Mapping radio button and click Add Item.
7. Leave the defaults and click Save
8. Change the ending for the SSO Credential Mapping fallback to Allow
9. Click Apply Access Policy at the top left

Once complete select Apply Access Policy and your VPE should look like the screenshot below

 

Creating a VDI Profile

• Navigate to Access ›› Connectivity / VPN : VDI / RDP : VDI Profiles and click Create New Profile
• Profile name: citrix_vdi
• Parent Profile: /Common/vdi
• Click OK

 

Create STA Resolution Halt iRule

• Navigate to Local Traffic ›› iRules : iRule List and click Create
• Name: STA_STOP
• Definition:

when RULE_INIT {
  set static::debug_sta_fwd 0
}

when HTTP_RESPONSE {
  if { [HTTP::has_responded] } { 
    log local0. "http has responded"
    return
  }
  if { $tmm_apm_client_type != "citrix-launch" } { 
   #  log local0. "apm client type is NOT citrix launch"
    return
  }
  set content_type [string tolower [HTTP::header Content-Type]]
  if { $content_type contains "application/x-ica" ||
     $content_type contains "application/vnd.citrix.launchdata+xml" } {
    log local0. "content type is ica or citrix"
    set ica_file_response 1
    set contentLength [HTTP::header "Content-Length"]
    HTTP::collect [HTTP::header Content-Length]
  }
  else {
    log local0. "content is not citrix"
  }
}

when HTTP_RESPONSE_DATA {
  if { [info exists ica_file_response] } { 
    log local0. "ica_file_response exists"
    # set session.user.access_mode to local
    ACCESS::session data set "session.user.access_mode" "local"
  if { ![info exists target_apm] } { return }
  }
}

Create Citrix Logged Out iRule

• Navigate to Local Traffic ›› iRules : iRule List and click Create
• Name: storefront_logged_out
• Definition:

when CLIENT_ACCEPTED {
 set citrix_logout 0
}
when ACCESS_ACL_ALLOWED {
 set type [ACCESS::session data get session.client.type]
 if { !($type starts_with "citrix") } {
  set storeWebName "/Citrix/UDF_storeWeb/"
  set http_uri [HTTP::uri]
  if { $http_uri == "/" || ($citrix_logout eq 0 && $http_uri ends_with "login.aspx") } {
   # log local0. "For [HTTP::uri] Redirecting to $storeWebName"
   ACCESS::respond 302 Location "https://[HTTP::host]$storeWebName"
  } elseif { $http_uri contains "Logoff" } {
   set citrix_logout 1
  } elseif { $citrix_logout eq 1 && $http_uri ends_with "login.aspx" } {
   set citrix_logout 0
   ACCESS::respond 200 content "Logged out\r\n" Connection close
   ACCESS::session remove
  }
 }
}

Note: The storeWebName variable value in the iRule must be changed to match your Citrix store name

Configuring an HTTP Profile

• Navigate to Local Traffic ›› Profiles : Services : HTTP and click Create
• Name: storefront_http
• Parent Profile: http
• Request Header Erase: Accept-Encoding
• Request Header Insert: X-Citrix-Via:storefront.itc.demo

Note: X-Citrix-Via is the header name and storefront.itc.demo is the value. The value must match the external FQDN in your environment.

• Redirect Rewrite: All
• Insert X-Forwarded-For: Enabled
• Click Finished

 

Creating a VDI Profile

• Navigate to Access ›› Connectivity / VPN : VDI / RDP : VDI Profiles and click Create New Profile
• Profile name: citrix_vdi
• Parent Profile: /Common/vdi
• Click OK

 

Creating a Client SSL Profile for Storefront Client Access

Navigate to Local Traffic ›› Profiles : SSL : Client and click Create

• Name: storefront_clientssl
• Parent Profile: clientssl
• Certificate Key Chain: Select the External Cert and Key that will be used for this website

Configuring a Storefront Pool

• Navigate to Local Traffic ›› Pools : Pool List
• Name: storefront_pool
• Health Monitors: tcp
• Load Balancing Method: Least Connections (member)
• Address: 10.1.20.6
• Service Port 443
• Click Add and Finished

NOTE: add as many StoreFront servers in your environment to the pool member list

Creating a Virtual Server for Storefront Access

• Navigate to Local Traffic ›› Virtual Servers : Virtual Server List and click Create
• Name: storefront_vs
• Type: Standard
• Destination Address/Mask: 10.1.10.101

• Service Port: 443
• Protocol Profile: tcp
• HTTP Profile (Client): storefront_http
• SSL Profile (Client): storefront_clientssl
• SSL Profile (Server): serverssl

• Source Address Translation: Auto Map (or whatever is appropriate for your environment)

• Access Profile: storefront_ap
• Click the + next to Connectivity Profile to create a new profile.
• Profile Name: proxy_conn
• Parent Profile: /Common/connectivity
• Click Ok

• VDI Profile: citrix_vdi

iRules

• Highlight “STA_STOP” and “storefront_logged_out” and click the double left arrow button to move the iRule to the Enabled box
• Default Pool: storefront_pool
• Default Persistence Profile: cookie
• Fallback Persistence Profile: dest_addr

• Click Finished

This concludes the configuration of the F5 APM SF-GW

There is a minimum requirement of 2 virtual servers on the ICA-GW. The first VS (proxy-vs) will be the listener that client ICA proxy requests are sent to. An iRule attached to this VS will pull out the payload of the ICA proxy request and make a sideband call to another VS (sta-resolver-vs) on the same APM. The sta-resolver-vs VS, via an iRule, will take the payload sent by the proxy-vs sideband call and use the STA server “shortname” in the payload to reference a Datagroup to find the STA server URL. This URL is then populated in the APM session table. The VDI profile will use this URL to contact the STA server to validate the STA ticket. Information received back from the STA server populates the session table. The ICA-GW now has the information it needs to proxy the ICA traffic.

F5 APM ICA-GW Configuration(link back to Top of page)

Creating a STA Ticket Resolver Access Policy

• Navigate to Access ›› Profiles / Policies : Access Profiles (Per-Session Policies) and click Create

General Properties

• Name: sta_resolver_ap
• Profile Type: All
• Customization Type: Modern
• Configure your desired Language settings and click Finished

When returned to the previous page displaying all access profiles, select Edit from the newly created policy

1. Between Start and Deny, select the + and then the “General Purpose” tab
2. Select “Empty” and click Add Item
3. Name: sessionexternal_sta_ticket
4. Click the Branch Rules tab
5. Click the Add Branch Rule button
6. Name: External STA Ticket
7. Click change next to Expression: Empty
8. Click the Advanced tab
9. In the advanced field enter: expr {[mcget {session.external_sta_ticket}] == 1}
10. Click Finished
11. Click Save
12. Click Apply Access Policy at the top left

Once complete select Apply Access Policy and your VPE should look like the screenshot below

Create a client SSL profile that contains the appropriate certificate, key, and chain. This configuration is beyond the scope of this article.

A server SSL profile is not required as traffic between the ICA-GW and DDC does not use TLS.

Creating a VDI Profile

• Navigate to Access ›› Connectivity / VPN : VDI / RDP : VDI Profiles and click Create New Profile
• Profile name: citrix_vdi
• Parent Profile: /Common/vdi
• Click OK

Create STA ticket Extractor iRule

• Navigate to Local Traffic ›› iRules : iRule List and click Create
• Name: StaTicketExtractor
• Definition: See iRule here: https://devcentral.f5.com/s/articles/Extract-Citrix-Secure-Ticket-Authority-STA

Note: A Virtual Server name (sta-resolver-vs) is referenced in the command ‘set conn [connect "sta-resolver-vs"]’. This VS will be created further in the article. If the VS is created with another name, then the command in this iRule must be changed to match the name of the VS.

Creating a Virtual Server for ICA Proxy

• Navigate to Local Traffic ›› Virtual Servers : Virtual Server List and click Create
• Name: proxy-vs
• Type: Standard
• Destination Address/Mask: 10.1.10.115

Note: This will be the IP address available to external users attempting to access Citrix resources

• Service Port: 443
• Protocol Profile: tcp
• HTTP Profile (Client): http
• SSL Profile (Client): citrix_client_ssl
• SSL Profile (Server): leave blank

• Source Address Translation: Auto Map

• Access Profile: sta_resolv_ap
• Click the + next to Connectivity Profile to create a new profile.
• Profile Name: proxy_conn
• Parent Profile: /Common/connectivity
• Click Ok

• VDI Profile:citrix_vdi

iRules

• Highlight “StaTicketExtractor” and click the double left arrow button to move the iRule to the Enabled box

• Do not select a Default Pool or Persistence Profile
• Click Finished

Create STA Ticket Resolver iRule

• Navigate to Local Traffic ›› iRules : iRule List and click Create
• Name: StaTicketResolver
• Definition: See iRule here: https://devcentral.f5.com/s/articles/Resolve-Citrix-Secure-Ticket-Authority-STA

Create a DataGroup to map STA server shortnames to the URL of the STA server

• Navigate to Local Traffic ›› iRules : Data Group List and click Create
• Name: sta_dg
• Type: string
• Enter as many pairs of String:Value necessary for your environment. The String will be the STA server shortname; typically in the STA12345678 format although this is customizable in the Windows registry. The value is the URL of the STA server in the format: https://[FQDN]/scripts/ctxsta.dll. Check with the Citrix system administrator if the STA servers should be contacted via http or https. This guide was written for HTTPS
• Click Finished

Creating a Virtual Server for STA ticket Resolution

• Navigate to Local Traffic ›› Virtual Servers : Virtual Server List and click Create
• Name: sta-resolver-vs
• Note: This name must match the name referenced in the ‘set conn [connect "sta-resolver-vs"]’ command in the previously created “StaTicketExtractor” iRule
• Type: Standard
• Destination Address/Mask: 1.2.3.4

Note: This can be any dummy IP address

• Service Port: 80
• Protocol Profile: tcp
• HTTP Profile (Client): http
• SSL Profile (Client): leave blank
• SSL Profile (Server): serverssl

• Source Address Translation: Auto Map

• Access Profile: sta_resolv_ap
• Connectivity Profile: proxy_conn
• VDI Profile:citrix_vdi

iRules

• Highlight “StaTicketResolver” and click the double left arrow button to move the iRule to the Enabled box

• Do not select a Default Pool or Persistence Profile
• Click Finished

This concludes the configuration of the F5 APM SF-GW

Conclusion(link back to Top of page)

And that’s it.
When you connect to your StoreFront virtual server on the F5 APM SF-GW, you will be presented with an F5 APM login screen. Login with your AD (or other) credentials. This should SSO you into Storefront where you will be presented with applications assigned to your AD account or groups. When you click on an app or desktop, an ICA file is downloaded and automatically launched by the Citrix Connection Manager (Receiver). The SSLProxyHost line in the ICA file directs your client to the F5 APM ICA-GW defined in the StoreFront configuration. The ICA-GW reads the payload in the request and contacts the STA server for validation, and then your app/desktop should load.