NetScaler – The ultimate Upgrade Guide

Reading Time: 3 minutes

Overview

As there are many changes in latest firmware builds of Citrix ADC and I was running in problems after upgrading from older 11.1 / 12.0 / 12.1 to newer 13.0 / 13.1 releases, I decided to list common issues, which you should consider when planning upgrades. The order is listed according to the frequency of the problems that occur in my day-to-day routine.

I will update this post, if there are any additions.

Issues

Issue: Broken Single sign-on (SSO) to Citrix StoreFront and other Backend TCP-Apps

This Issue affects broken SSO to Citrix StoreFront, Microsoft Exchange (ActiveSync or Outlook Anywhere) and other TCP services, when accessed via full SSL VPN

• From Citrix ADC feature release 12.1 build 60.16 and above, feature release 13.0 build 64.35 and above and feature release 13.1 build 4.43 and above, the following SSO types are disabled globally
  • Basic authentication
  • Digest Access authentication
  • NTLM without Negotiate NTLM2 Key or Negotiate Sign

• StoreFront SSO configuration is impacted (disabled) only for 13.0 build 64.35. The configuration will not be impacted in the future 13.0 builds.

Issue: “Error: Not a privileged User.” when using AAA to protect Webservices

This Issue affects Users trying to access Webservices after successful authentication to an AAA vServer

• From Citrix ADC feature release 13.0 build 41.20 and above and feature release 13.1 build 4.43 and above, the Default Authorization Action in Global Session Settings changed from ALLOW to DENY

Issue: Classic Policy and expressions are deprecated

This Issue affects the deprecation of classic policies / expressions and the removing of certain based features and functionalities

• Classic policy and expressions are deprecated (discouraged from use and NOT removed) starting with 12.0 build 56.20. The policy and expressions continue to work in all places the same way they used to work throughout all builds of release 13.0. However, from Citrix ADC 13.1 release onwards, certain Classic policy based features and functionalities have been removed.

Issue: “Cannot complete your request” or “Citrix gateway plug-in for java is not supported” when using HTTP Header “Referer”

This Issue affects Users after authentication to Citrix Gateway getting an instant “Cannot complete your request” message

• From Citrix ADC feature release 13.0 build 7x and above and feature release 13.1 build 4.43 and above, using the “REQ.HTTP.HEADER Referer EXISTS” expression in session policies were NOT being hit at all, leading to the mentioned error message.

Solutions

Solution: Broken Single sign-on (SSO) to Citrix StoreFront and other Backend TCP-Apps

Create a Citrix Gateway Traffic Policy that enables SSO for StoreFront and TCP services via full SSL VPN:

add vpn trafficAction StoreFrontSSO http -SSO ON
add vpn trafficPolicy StoreFrontSSO true StoreFrontSSO

#or for full SSL VPN:
add vpn trafficPolicy StoreFrontSSO "HTTP.REQ.METHOD.EQ(post) || HTTP.REQ.METHOD.EQ(get) && false" StoreFrontSSO
bind VPN vServer *YOUR Gateway vServer* -policy StoreFrontSSO -priority 100 -gotoPriorityExpression END -type REQUEST

Create a AAA-TM Traffic Policy / Session Policy that enables SSO for Microsoft Exchange (ActiveSync and Outlook Anywhere):

add tm trafficaction TrafficAction_SSO -SSO ON
add tm trafficpolicy TrafficPolicy_SSO true TrafficAction_SSO
bind lb vserver *YOUR Exchange LB vServer* -policy TrafficPolicy_SSO -priority 100


#or for scenarios based on session policy configuration:
add tmsessionaction TrafficSessionAction_SSO -SSO ON
add tmsession policy TrafficSessionPolicy <rule> TrafficSessionAction_SSO
add tm trafficaction TrafficAction_SSO -SSO ON
add tm trafficpolicy TrafficPolicy_SSO <same rule as session Policy> TrafficAction_SSO

Solution: “Error: Not a privileged User.” when using AAA to protect Webservices

You are able to reset the new defaults back to ALLOW, but it’s recommended to use Authorization Policies. You can bind or filter these policies to AAA User / Groups or LB vServer.

add authorization policy auth_allow_all true ALLOW

Solution: Classic Policy and expressions are deprecated

Using the nspepi Tool to Convert Classic Expressions to Advanced Expressions, see https://support.citrix.com/article/CTX131024

From Citrix ADC feature release 13.0 build 67 and above, nFactor is supported in ADC Standard Edition licensing:

• When creating an AAA vServer, Non Addressable is the only option to use
• Standard Edition does not support an addition of new login schemas in nFactor configuration
  • You are able to use the default login schemas and overwrite existing XML files with your preferred ones
• Authentication Policy types like OAuth, Native / Email / Push OTP, KBA and SSPR aren’t supported in Standard Edition

Solution:“Cannot complete your request” when using HTTP Header “Referer”

Citrix Product documentation was using the Referer Header for years to difference between Citrix Gateway Plug-In for Windows / Mac and Citrix Workspace App for the Web (= Browser)

I highly recommend using the following Header which I did a research about on my own – see Blogpost

#Citrix Workspace App for the Web (=Browser):
HTTP.REQ.HEADER("User-Agent").CONTAINS("Edg")||HTTP.REQ.HEADER("User-Agent").CONTAINS("Chrome")||HTTP.REQ.HEADER("User-Agent").CONTAINS("Firefox")

#or more simple if you don’t have to difference on Browser-Types:
HTTP.REQ.HEADER("User-Agent").CONTAINS("CitrixReceiver").NOT

#Citrix Gateway Plugin-In for Windows and Mac:
HTTP.REQ.HEADER("User-Agent").CONTAINS("NAC/1.0 plugin")

I sent feedback about Citrix’ article and luckily, they updated the page and deleted all kind of Referer. It was confusing, as in CTX316442 they mention to delete the Referer.

Summary

I hope these hints will help you enjoying your Citrix ADC Upgrade-Ride. Please feel free to comment your experiences with other Upgrade-Issues.