NetScaler – The ultimate Upgrade Guide

Reading Time: 3 minutes


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.


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.


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

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):

#or more simple if you don’t have to difference on Browser-Types:

#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.


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


  1. Not sure how common issue it is, but it seems to me that some of the fresh installs of VPX builds (hypervisor images) miss the “logon” folder in the file system which naturally causes all sorts of problems. Might be worth mentioning in your article? Could be that Citrix has sorted out this for all the releases that are available for download already though?

  2. We’ve just upgraded from 12.1.x to
    No problems so far :

    But for the ADC web gui :
    The leftsite “menu bar” (Fav.till..Auth) the “spacing” in the CSS is very…very large, so the menu is not as lined up as the 12.1 Gui interface. When you dive deeper in the menu it get worse

    It is very annoying.
    Anyone who also notice this… ?


  3. hi, after upgrade from 12.1 to 13.0 i get after login to the gateway, the plugin installer..sorry for my question, but for what is the gateway plugin needed? before i had just citrix workspace installed and i could launch a desktop…

    1. Hi Sebastian,
      the gateway plugin is for a full SSLVPN tunnel. The popup to download the plugin installer instead showing your ICA Desktops could be an issue with your used expressions of your linked session policies to your Gateway. Are you able to share the expressions?

Leave a Reply

Your email address will not be published. Required fields are marked *