Troubleshoot authentication, authorization and auditing issues

Troubleshoot authentication issues in NetScaler and NetScaler Gateway with aaad.debug module

Authentication in NetScaler Gateway is handled by the Authentication, authorization, and auditing (AAA) daemon. The raw authentication events that AAA daemon processes can be monitored by viewing the output of the aaad.debug module and serves as a valuable troubleshooting tool. The aaad.debug is a pipe as opposed to a flat file and does not display the results or log them. Therefore, the cat command can be used to view the output of aaad.debug. The process of using nsaaad.debug to troubleshoot an authentication problem is typically referred to as “debugging aaad”.

Debug process using aaad.debug module

This process is useful for troubleshooting authentication issues such as:

  • General authentication errors
  • Username/password failures
  • Authentication policy configuration errors
  • Group extraction discrepancies

Note: This process applies to NetScaler Gateway and NetScaler appliance.

Troubleshooting authentication issues

To troubleshoot authentication with aaad.debug module, complete the following procedure:

  1. Connect to the NetScaler Gateway command line interface with a Secure Shell (SSH) client such as PuTTY.

  2. Run the following command to switch to the shell prompt: shell
  3. Run the following command to change to the /tmp directory: cd /tmp
  4. Run the following command to start the debugging process: cat aaad.debug
  5. Perform the authentication process that requires troubleshooting, such as a user logon attempt.
  6. Monitor the output of the cat aaad.debug command to interpret and troubleshoot the authentication process.
  7. Stop the debugging process by pressing Ctrl+Z.
  8. Run the following command to record the output of aaad.debug to a file: cat aaad.debug | tee /var/tmp/<debuglogname>, where /var/tmp is the required directory path and <debuglogname.log> is the required log name.

The following section provides examples of how aaad.debug module can be used to troubleshoot and interpret an authentication error.

Incorrect password

In the following example, the user enters an incorrect RADIUS password.

process_radius Got RADIUS event
process_radius Received BAD_ACCESS_REJECT for: <username>
process_radius Sending reject.
send_reject_with_code Rejecting with error code 4001

Invalid username

In the following example, the user enters an incorrect LDAP username.

/home/build/rs_121/usr.src/netscaler/aaad/ldap_drv.c[450]: receive_ldap_user_search_event 1-140: Admin authentication(Bind) succeeded, now attempting to search the user testusernew

/home/build/rs_121/usr.src/netscaler/aaad/ldap_drv.c[453]: receive_ldap_user_search_event 1-140: Number of entires in LDAP server response = 0

/home/build/rs_121/usr.src/netscaler/aaad/ldap_drv.c[459]: receive_ldap_user_search_event 1-140: ldap_first_entry returned null, user testusernew not found

/home/build/rs_121/usr.src/netscaler/aaad/naaad.c[4781]: send_reject_with_code 1-140: Not trying cascade again 4009

/home/build/rs_121/usr.src/netscaler/aaad/naaad.c[4783]: send_reject_with_code 1-140: sending reject to kernel for : testusernew

/home/build/rs_121/usr.src/netscaler/aaad/naaad.c[4801]: send_reject_with_code 1-140: Rejecting with error code 4009

Determining group extraction results

In the following example, the group extraction results can be determined. Many issues with AAA group access involve the user not picking up the correct session policies for their assigned group in a NetScaler Gateway appliance. Some common reasons for this include an incorrect spelling of AD or the Radius group name in the appliance and users not being a member of the security group in AD or the Radius server.

start_ldap_auth attempting to auth scottli @


/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[551]: recieve_ldap_user_search_event built group string for scottli of:Domain Admins

aaad.debug module error codes

The following table lists the various aaad.debug module error codes, cause for the error, and the resolution.

aaad.debug module error codes Error message Cause of error Resolution
4001 Incorrect credentials/Password. Try again. Incorrect credentials are supplied Enter the correct credentials
4002 Not Permitted This is a catch all error. Occurs when ldapbind operation fails for reasons other than incorrect user credentials. Make sure bind operation is permitted
4003 Cannot connect to server. Try connecting again in a few minutes. Server times out Increase the LDAP/Radius server timeout value on NetScaler (Authentication > LDAP/Radius > Server > Timeout value). Default timeout value is 3 secs.
4004 System Error NetScaler/NetScaler Gateway internal error or a runtime error in the appliance library Check for the cause of the system error and reslove the same
4005 Socket Error Socket error while talking to the authentication server Make sure that LDAP/RADIUS server or any other authentication servers can listen on the ports mentioned in the authentication action configured on NetScaler. For example, a common error scenario can be that an ldapprofile on NetScaler is configured to use port 636 /SSL, however the same port is not open on the AD.
4006 Incorrect username Bad (format) username passed to nsaaad, like empty username Enter the correct username
4007 Incorrect password Bad (format) password passed to nsaaad Enter the correct password
4008 Passwords do not match Password mismatch Enter the correct password
4009 User not found No such user Login using a valid user present in AD
4010 You do not have permission to log on at this time Restricted log on hours Log on outside the restricted hours
4011 Your AD account is disabled Account disabled Get your AD account enabled
4012 Your password has expired Password expired Reset your password
4013 You do not have permission to log on No dial-in permission (RADIUS specific). This usually happens if a user is not authorized to authenticate at a server. Network access permission setting needs to be changed
4014 Could not change your password Error in changing password. This can happen due to many reasons. One such reason could be trying to change the password using the non-ssl port provided in ldapprofile on NetScaler. Ensure secure port and sec type is used for changing password
4015 Your account is temporarily locked User AD account is locked Get your AD account unlocked
4016 Could not update your password. The password must meet the length, complexity, and history requirements of the domain. User password requirements not met while changing the password Meet the needed requirements while changing the password
4017 NAC process Microsoft Intune Specific. NetScaler Gateway is unable to verify device, either due to API failure or connectivity failure. Ensure Microsoft Intune managed devices are reachable to NetScaler Gateway
4018 NAC Noncompliance Microsoft Intune returns a status saying that this device is not compliant device Ensure Microsoft Intune managed devices are compliant with NetScaler Gateway
4019 NAC Unmanaged Microsoft Intune returns a status saying that this is not a managed device Ensure Microsoft Intune specific configurations are in place
4020 Authentication not Supported This error is seen in case of misconfiguration. For example, auth type is not supported by NetScaler or if the Authentciationprofile config is incorrect on NetScaler appliance or if accounting action (radius) is attempted for authentication. Check the Authentication checkbox for the Authentication server on NetScaler if its unchecked. Use appropriate Authentication action on NetScaler.
4021 User Account Expired The user account has expired Get your user account renewed
4022 User account is locked by NetScaler The user account is locked by NetScaler Unlock the account using unlock aaa user <> command
4023 Max OTP Device limit reached Device limit for receiving OTP reached Either try unregistering the non-required OTP devices or continue with the ones already registered

Localize error messages generated by NetScaler nFactor system

This topic captures information on localizing error messages generated by NetScaler nFactor system. These messages include the extended authentication error strings that are obtained as part of enhanced authentication feedback.

The default error strings that are sent by nFactor subsystem are described in /var/netscaler/logon/LogonPoint/receiver/js/localization/en/ctxs.strings.js for English language. Error strings for other languages are found in corresponding directories in /var/netscaler/logon/LogonPoint/receiver/js/localization/.

You must create a portal theme based on RfWeb UI for localizing error messages.

At the command prompt, type:

add portaltheme custom_error_theme -basetheme RfWebUI

bind authentication vserver av1  -portaltheme custom_error_theme

After these commands are executed, a new directory is created in /var/netscaler/logon/themes/<name>. This directory contains a file named “strings.en.json.” This file is an empty json file to begin with. Administrator can add name-value pairs comprising of old and new error strings.

For example, { “No active policy during authentication”: “No active policy during authentication, Please contact administrator” }

In the preceding example, text on the left side is the existing error message that is sent by nFactor. The text on the right side is the replacement for that. Administrator can add more messages as required.

Enhanced authentication feedback

For obtaining extended error messages during authentication process, enhancedAuthenticationFeedback feature must be enabled.

At the command prompt, type:

set aaa parameter –enableEnhancedAuthFeedback YES
Troubleshoot authentication, authorization and auditing issues