Your Resource for All Things Apps, Ops, and Infrastructure

Integrating Citrix Gateway Applications Within Okta

As workforces continue to operate in a remote world full of virtual workspaces, providing both convenience and security is critical. Authentication services like Okta give users security and ease-of-access. However, not all applications integrate equally, and roadblocks do pop up.

In this tutorial, we’re solving for a persistent and troublesome challenge—integrating Citrix Gateway applications within Okta. There is a known problem with accessing Citrix apps in Okta when the user has not already authenticated through Citrix Gateway.

We’ll walk through how to publish individual Citrix applications directly on the Okta portal, resulting in Citrix applications appearing side-by-side with SaaS applications (like in the image below), regardless of sign-on path.

Graphical user interface, application

Description automatically generated

Before we dive into the tutorial, it’s important to note that access to traditional Citrix published applications requires Citrix ADC, formerly known as NetScaler, and Citrix StoreFront. Another thing to be aware of before we get started is that when using SAML as the authentication method, the single sign-on (using username and password) to the Windows application session breaks. Citrix has created a fix with Federated Authentication Service to create and use a virtual smart card to perform the single sign-on. There is an excellent writeup of that procedure at Carl Stalhood’s website. If you are using SAML authentication, I highly recommend reviewing Carl’s recommendations for fixing the broken sign-on.

Set up SAML Server/Action in Citrix ADC 

First, we must define which features of Okta will be used and how to get a specific application to launch from StoreFront and publish on Okta. On the Okta side, there is a built-in application definition for Citrix Gateway (NetScaler Gateway) that sets up the SAML integration and documents exactly how-to setup the SAML Server/Action in Citrix ADC.  

Publish Okta Tile 

Publishing an Okta tile for a specific application requires the use of a Bookmark App. The URL for the Bookmark App can be accessed in the StoreFront Website Shortcuts. Within the Citrix StoreFront management console, go to “Manager Receiver for Web Sites” to get to the dialog box pictured below. 

Graphical user interface, text, application

Description automatically generated
(source: Citrix)

After adding the URL of the Okta portal site, click “Get shortcuts” to open a special URL on the StoreFront website where you’ll see all application shortcuts available to the user who logged in. 

A screenshot of a computer

Description automatically generated with medium confidence
(source: Citrix) 

Correct URL for Proper Integration 

As you test the Bookmark Apps, you’ll realize that as long as the user has already connected to Citrix Gateway, the Bookmarks work as expected. However, if the user has not already connected and authenticated through the Citrix Gateway, they will see a standard StoreFront page with all of their apps. This is not the desired outcome. 

The problem here is the format of the URL.  Here is an example from my lab: 

(https://citrixgatewayurl.mylab.com/Citrix/StoreWeb/#/launch/AHEAD%20Demo%20Desktop/esdxjjqbMUt1Vl9Pj5c7Wq%2B2TG5f%2B7ZSpgQmNvMbrcNBSEVBRCBBdmlhdGlvbiBEZXNrdG9w) 

URLs have different components including the protocol (https), hostname (citrixgatewayurl.mylab.com), path (/Citrix/StoreWeb/), query (which is not present in this example), and URL fragment which is the part after the hash tag (#). The URL fragment is only client side and is never sent to the server. When the user logs in for the first time and is redirected to the authentication page, this URL fragment is not preserved in the redirection and becomes lost. 

To solve, change the URL in the Okta Bookmark App and replace the # with %23. This makes it URL-safe so that the server knows about it.  

Now when the user gets redirected to the Citrix Gateway authentication page, the following path will be stored in the NSC_TASS cookie: 

(/Citrix/StoreWeb/%23/launch/AHEAD%20Demo%20Desktop/esdxjjqbMUt1Vl9Pj5c7Wq%2B2TG5f%2B7ZSpgQmNvMbrcNBSEVBRCBBdmlhdGlvbiBEZXNrdG9w) 

The final step is to add a responder policy to redirect the user’s browser back to the correct page with the URL fragment and reset the NSC_TASS cookie to its proper value. 

add responder action RES-ACT-CheckTassCookie respondwith q{"HTTP/1.1 302 Moved Temporarily\r\nSet-Cookie: NSC_TASS=" + HTTP.REQ.COOKIE.VALUE("NSC_TASS").BEFORE_REGEX(re/%23/) + ";Path=/;Secure;HttpOnly\r\nLocation:" + HTTP.REQ.COOKIE.VALUE("NSC_TASS").BEFORE_REGEX(re/%23/) + "#" + HTTP.REQ.COOKIE.VALUE("NSC_TASS").AFTER_REGEX(re/%23/) + "\r\n\r\n"}
add responder policy RES-POL-CheckTassCookie "HTTP.REQ.COOKIE.VALUE(\"NSC_TASS\").CONTAINS(\"%23\") && HTTP.REQ.URL.PATH.ENDSWITH(\"Web/\")" RES-ACT-CheckTassCookie

Since the Bookmark App needs to be the same whether this is the first application or any subsequent application, an additional responder policy needs to be created to prevent a ‘Page not Found’ error. 

add responder action RES-ACT-CheckLaunchPath redirect "HTTP.REQ.URL.PATH.BEFORE_STR(\"Web/\") + \"Web/#/launch\" + HTTP.REQ.URL.PATH.AFTER_STR(\"/launch\")" -responseStatusCode 302
add responder policy RES-POL-CheckLaunchPath "HTTP.REQ.URL.PATH.CONTAINS(\"/launch\")" RES-ACT-CheckLaunchPath  

Both of these policies must be bound to the Citrix Gateway. 

bind vpn vserver citrixgatewayvserver -policy RES-POL-CheckTassCookie -priority 100 -gotoPriorityExpression END -type REQUEST 
bind vpn vserver citrixgatewayvserver -policy RES-POL-CheckLaunchPath -priority 110 -gotoPriorityExpression END -type REQUEST

This will result in users having access to Citrix applications within Okta, regardless of sign-on path.  

The responder polices mentioned in this guide can be used for other application dashboards as well (other than Okta).  

Hopefully this helps you in your journey to modern application publishing, regardless of the platform. 

Subscribe to AHEAD i/o for industry insights,

straight to your inbox.