HowTO: Troubleshoot authentication failures on Citrix Netscaler using aaad.debug

by | Sep 5, 2023

This article will describe how to troubleshoot authentication issues through ADC or Citrix Gateway via aaad.debug on the appliance shell console.

Use this process/steps to troubleshoot authentication issues such as:

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

**This process applies to both Citrix Gateway and ADC appliances.

Troubleshooting Authentication Issues

To troubleshoot authentication with aaad.debug, use the following steps:

  • Connect to the Netscaler command console using a Secure Shell (SSH) client such as PuTTY.
  • Switch to the shell prompt by entering the following command:  shellaaad.debug shell command
  • Change to the /tmp directory by running this command: cd /tmp
  • Start the debugging process by running this command: cat aaad.debugaaad.debug output
  • Attempt an authentication process that requires troubleshooting, such as a user login attempt.
  • Review the output of the cat aaad.debug command to troubleshoot the authentication process.
  • To stop the debugging process, run this command:  Ctrl+C
  • 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 

Additional Resources

CTX138663 – Error Codes Returned by aaad.debug Module of NetScaler
CTX108876 – How to Configure LDAP Authentication on NetScaler
CTX233027 – [NetScaler Gateway Trace Study] – LDAP Authentication
CTX114335 – How to Configure an LDAP Monitor on NetScaler