It has been a while since I last talked about StoreFront and Citrix Gateway integration (2014, eek!) and the focus at that time was looking at Web Interface Gateway integration and addressing how things were changing with StoreFront — things like the fact that you could bind multiple Gateway definitions to a single Store and how Gateway authentication and ICA Proxy were now tied together. Now that most of the customers I interact with are off of Web Interface, I thought it was time to revisit some of the more advanced Gateway integration settings with StoreFront, irrespective of Web Interface, since (shockingly) some things have changed since 2014!
Rules of the Road
We will start with some cardinal rules you should know about how StoreFront identifies Citrix Gateway-sourced traffic. First, StoreFront identifies Citrix Gateway traffic based on the Gateway URL. The URL users are accessing is passed back to StoreFront from Citrix Gateway via the XCitrixVia HTTP header. So, a user authenticates at Citrix Gateway, the Gateway inserts the URL hostname into the XCitrixVia HTTP header and passes the information back to StoreFront along with an attempt to SSO using the “AGBasic” authentication method. StoreFront will only accept authentication traffic from URLs it knows about. That means the “NetScaler Gateway URL” field in the StoreFront configuration pictured below is critical and should match the URL users are using.
If you try to authenticate from a Gateway address not listed in StoreFront, users will be prompted for credentials at StoreFront again (Gateway passthrough will fail) and you will see the below warning in the Citrix Delivery Services event log from the Citrix Authentication Service stating that it could not match a Gateway in its list against the request (note the XCitrixVia header contents with the Gateway address used is listed in the event details, also the XCitrixViaVIP header, which we will talk about next):
Key takeaway: listing the correct Gateway URLs in StoreFront is critical.
In GSLB scenarios where you will have multiple Gateways all behind the same URL, you will need multiple Gateways listed all with the same Gateway URL specified (to match what users are using), but unique Callback URLs. A Callback URL is necessary if you are doing anything with Smart Access policies and we do not want this to be GSLB routed as it has to be directed to the same Gateway that originally authenticated the user, hence the need for unique Callback addresses (one per Gateway). In this scenario, where StoreFront will identify multiple Gateways matching the URL request, it falls back to IP address identification based on what you have specified in the “VServer IP address” field within the Gateway definition, shown below, to correctly identify the single Gateway that originally processed the user’s authentication request and then routes the callback appropriately. (Sidebar: this field used to be labeled “Subnet IP address,” which was confusing as you should always specify the vServer VIP here as that is guaranteed to be unique across Gateways, so we have updated it in newer versions). The vServer IP address of the Gateway accessed is passed back to StoreFront via the XCitrixViaVIP HTTP header.
Note, however, that IP address is a secondary identification method — StoreFront will always attempt to match on URL first and if it cannot, you will see the error previously shown. IP address is used only if multiple configured Gateways match against the URL being accessed.
Key takeaway: in scenarios using Gateway GSLB and Smart Access, a unique Callback URL is required per Gateway and the VServer IP address field must be populated as StoreFront will use this to identify the Gateway uniquely.
So, what’s the problem??
Where this can get a little messy is simply on the number of Gateways that have to be defined – one for every possible Gateway that you want to accept authentication requests from. Let’s say, for example, you have three global Gateways behind a unified GSLB address (something like https://www.nsg.com): one in America, one in Europe, one in Asia. That is three Gateways bound to the Store, each with the same Gateway URL (https://www.nsg.com), unique vServer IP addresses specified, and unique Callback URLs — your list of configured Gateways will look something like:
| Display Name | Gateway URL | VServer IP Address | Callback URL |
| GSLB US | https://www.nsg.com | 1.1.1.1 | https://callback-us.nsg.com |
| GSLB EU | https://www.nsg.com | 2.2.2.2 | https://callback-eu.nsg.com |
| GSLB AP | https://www.nsg.com | 3.3.3.3 | https://callback-ap.nsg.com |
But now, administrators want to be able to test authenticating at each Gateway individually in case of GSLB issues, so you define alternate names for each in DNS and bind a SAN certificate. This means you have to define three additional Gateways for the three regional Gateway URLs, all referencing the same original three GSLB Gateway vServers. You have now doubled the number of Gateway definitions in the Store to look something like the following:
| Display Name | Gateway URL | VServer IP Address | Callback URL |
| GSLB US | https://www.nsg.com | 1.1.1.1 | https://callback-us.nsg.com |
| GSLB EU | https://www.nsg.com | 2.2.2.2 | https://callback-eu.nsg.com |
| GSLB AP | https://www.nsg.com | 3.3.3.3 | https://callback-ap.nsg.com |
| US Gateway | https://us.nsg.com | 1.1.1.1 | https://callback-us.nsg.com |
| EU Gateway | https://eu.nsg.com | 2.2.2.2 | https://callback-eu.nsg.com |
| AP Gateway | https://ap.nsg.com | 3.3.3.3 | https://callback-ap.nsg.com |
Now imagine you have more than three global access points… or you want to do Optimal Gateway Routing (a whole other topic)… Wouldn’t it be simpler if you could specify a GSLB alternate URL and cut your Gateway list in half?
But wait… you can! In StoreFront version 3.9, we added the ability via PowerShell only to specify a GSLB URL that is different from the Gateway URL, like an alternate hostname that StoreFront will accept for that Gateway definition. We actually document this in detail in eDocs, but I do not think it got a lot of press, so want to spend some time on this here. The magical series of commands to add this parameter to an existing Gateway definition is:
$Gateway=Get-STFRoamingGateway -Name “<Display Name>” $Gateway.GslbLocation=“<GSLB Address>” Set-STFRoamingGateway -Gateway $Gateway
Going back to the previous example, this would allow you to have three Gateways defined, instead of six, but actually connect to the Store via four different Gateway addresses: each of the regional URLs (for administrator testing) and the common GSLB URL (for users), with an updated Gateway list looking like:
| Display Name | Gateway URL | VServer IP Address | Callback URL | GSLB URL |
| US Gateway | https://us.nsg.com | 1.1.1.1 | https://callback-us.nsg.com | https://www.nsg.com |
| EU Gateway | https://eu.nsg.com | 2.2.2.2 | https://callback-eu.nsg.com | https://www.nsg.com |
| AP Gateway | https://ap.nsg.com | 3.3.3.3 | https://callback-ap.nsg.com | https://www.nsg.com |
Much simpler, right? And even though the parameter is called “GslbUrl,” it functions just as an alternate hostname for that Gateway definition, so it does not have to be a GSLB address, just another name you want that Gateway to be accessible by. You could even flip the addresses such that the “Gateway URL” is the common address (“https://www.nsg.com”) and the “GSLB URL” is the regional one (“https://us.nsg.com”), which may actually have advantages when it comes to Receiver and the default Gateway for the Store (if unfamiliar with this “default” setting, I covered it in my last article here). eDocs also gives an example with split DNS with external/internal Gateway addresses that should be routed to the same vServer. I am just focusing on the GSLB use case as being the one that is likely to be most common usage of this feature, but there are definitely other creative uses.
Of course, this does come with some caveats:
- You need to have StoreFront version 3.9 or later
- You will not see this alternate “GSLB” Gateway address in the console, but it does show up as part of the Gateway definitions in the web.config files in the Store and Roaming IIS directories (under inetpub\wwwroot\Citrix\<Store name> and inetpub\wwwroot\Citrix\Roaming) and of course is visible in the output of the Get-STFRoamingGateway PoSH command:
- As I alluded to above, you will need to think through the impact this would have on native Receiver and the “default Gateway” setting for the Store. While the above example works well for web browser scenarios, it means that a Default Gateway assigned in the Store used by Receiver will have a regional URL specified instead of the GSLB one, so you may actually want to flip the addresses as shown below just so that the Default Gateway is a GSLB URL and you do not unintentionally route all your native Receiver users through a non-GSLB address.
| Display Name | Gateway URL | VServer IP Address | Callback URL | GSLB URL |
| US Gateway | https://www.nsg.com | 1.1.1.1 | https://callback-us.nsg.com | https://us.nsg.com |
| EU Gateway | https://www.nsg.com | 2.2.2.2 | https://callback-eu.nsg.com | https://eu.nsg.com |
| AP Gateway | https://www.nsg.com | 3.3.3.3 | https://callback-ap.nsg.com | https://ap.nsg.com |
That’s it! I know this has been a long one, but there are really only two things I want you to remember: correctly specifying Gateway URLs is critical for StoreFront and Gateway integration (have I said that enough, yet?) and we have a new PoSH parameter in version 3.9 that makes this simpler in GSLB scenarios by allowing you to assign two Gateway URLs to the same Gateway definition in StoreFront that you should test.
Hope you find this post helpful. Happy StoreFront-ing!
