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”.
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:
-
Connect to the NetScaler Gateway command line interface with a Secure Shell (SSH) client such as PuTTY.
- Run the following command to switch to the shell prompt:
shell - Run the following command to change to the /tmp directory:
cd /tmp - Run the following command to start the debugging process:
cat aaad.debug - Perform the authentication process that requires troubleshooting, such as a user logon attempt.
- Monitor the output of the cat aaad.debug command to interpret and troubleshoot the authentication process.
- Stop the debugging process by pressing Ctrl+Z.
- Run the following command to record the output of
aaad.debugto a file:cat aaad.debug | tee /var/tmp/<debuglogname>, where/var/tmpis 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
<!--NeedCopy-->
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
<!--NeedCopy-->
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.
/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[40]:
start_ldap_auth attempting to auth scottli @ 10.12.33.216
/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[291]:
/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
<!--NeedCopy-->
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
<!--NeedCopy-->
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
<!--NeedCopy-->