NetScaler Enhanced Authentication Feedback

Enhanced Authentication Feedback introduced since v10.1 is a NetScaler option disabled by default which provides more information to the end user about the reason for an authentication failure. By default when a user authenticates to as an example NetScaler Gateway and fails, the Incorrect user name or password message returned is the only reason NetScaler will give.

The reason could be entirely different though. A disabled account, expired password, and restricted logon hours are just some of the reasons a failure could indeed occur. This is why the Enhanced Authentication Feedback option could prove useful to you and the end-user. It may reduce support calls and make it easier for the support team to resolve authentication failures because they will get a more granular reason as to the failures.

On the other hand, a security risk is included when enabling this option. Once this option is enabled it will be easier for an attacker to identify if a user account does not exist for example. It is important to highlight this.

To enable, via CLI run command set aaa param -enableEnhancedAuthFeedback or via GUI navigate to NetScaler Gateway -> Global Settings -> Change authentication AAA settings -> Enable Enhanced Authentication Feedback.

1-min

2-min

Error codes and a list of supported reasons are given below:

  • 4001 – Invalid credentials. Catch-all error from previous versions. (Incorrect credentials. Try again.)
  • 4002 – Login not permitted. Catch-all error from previous version. (You do not have permission to log on at this time.)
  • 4003 – Server timeout. (Cannot connect to server. Try connecting again in a few minutes.)
  • 4004 – System error. (Cannot connect. Try connecting again.)
  • 4005 – Socket error talking to authentication server. (Cannot connect. Try connecting again.)
  • 4006 – Bad (format) user passed to nsaaad. (Incorrect user name.)
  • 4007 – Bad (format) password passed to nsaaad. (Incorrect password.)
  • 4008 – Password mismatch (when entering new password). (Passwords do not match.)
  • 4009 – User not found. (User not found.)
  • 4010 – Restricted login hours. (You do not have permission to log on at this time.)
  • 4011 – Account disabled. (Your account is disabled.)
  • 4012 – Password expired. (Your password has expired.)
  • 4013 – No dial-in permission (RADIUS specific). (You do not have permission to log on.)
  • 4014 – Error changing password. (Could not change your password.)
  • 4015 – Account locked. (Your account is temporarily locked.)
  • 4016 – User password complexity requirement not met when changing password. (Could not update your password. The password must meet the length, complexity, and history requirements of the domain.)

Example – User not found.

3-min

Example – Account disabled. 4-min

How can I change the response codes returned by NetScaler?

Remember the point highlighted above. Enabling Enhanced Authentication Feedback will out of the box return a User not found response if you enter a username and LDAP can not find that actual username in Active Directory. This is a security concern. Now, the responses can be changed.

Note: Citrix do not support or assist with this configuration. Perform this modification at your own risk. If you do proceed, make sure to always take a backup before changing a live environment.

For non-RfWebUI themes:

Open up WinSCP or similar. Browse to and edit the following file:

  • NSv11+ – /var/netscaler/logon/themes/default/resources/en.xml
  • NSv10.5 – /netscaler/ns_gui/vpn/resources/en.xml

Note: If you have a custom theme, the default portion will be whatever name you had specified during theme creation.

5-min

Edit the en.xml file and look for the section shown below.  6-min

Change any of the values then save en.xml.7-min

Now as an example, my modified “User not found” text contains some new information!

Note: You might have to wait for a period of time, or warm reboot NetScaler to see the new feedback changes.8-min

For RfWebUI themes:

Open up WinSCP or similar. Browse to and edit the following file:

  • /var/netscaler/logon/LogonPoint/receiver/js/ctxs.core.min.js

Note: You will probably want to open the file using Notepad++ or similar for easier reading. Search the file for errorMessageLabel and edit the reasons as appropriate.


5 Comments

  • Jason

    May 20, 2016

    This is a great site – very informative and helpful! Question about enhanced authentication feedback. I would like to enable this feature but it the fact that it returns user not found is a show stopper. Is there any way to filter out that message ◾4009 – User not found. Is there something we can change in the code to prevent this or rewrite that error message/error code?

    Reply
    • George Spiers

      May 21, 2016

      Sorry, not sure of a way to do that. Would be useful for sure!

      Reply
    • George Spiers

      June 10, 2016

      Post has been updated to include method for changing the error messages.

      Reply
  • Srini

    April 12, 2020

    Hi George, I am using RfWebUI custom theme with AAA nFactor ( adv auth policies). I am trying to edit the error message by following CTX223404, but JSON files mentioned in the article are empty. Can you suggest?

    Reply

Leave a Reply