This article describes how to troubleshoot authentication issues through ADC or Citrix Gateway with 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 both Citrix Gateway and ADC appliance.

Troubleshooting Authentication Issues

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

1. Connect to ADC 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+C.

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 this example, the user entered an incorrect Lightweight Directory Access Protocol (LDAP) password.

Fri Oct 19 17:53:20 2007
/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
Fri Oct 19 17:53:20 2007
/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[291]: recieve_ldap_bind_event 
receive ldap bind event
Fri Oct 19 17:53:20 2007
/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
Fri Oct 19 17:53:22 2007
/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/naaad.c[1198]: send_reject sending reject to
kernel for : scottli

Invalid Username

In this example, the user entered an incorrect username.

/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[40]: start_ldap_auth attempting to
auth scott @ 10.12.33.216 
Fri Oct 19 17:53:30 2007 /usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[291]: recieve_ldap_bind_event
Fri Oct 19 17:53:30 2007 /usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[534]:
recieve_ldap_user_search_event ldap_first_entry returned null, user not found
Fri Oct 19 17:53:30 2007 /usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/naaad.c[1198]: send_reject sending reject to kernel for : scott

Invalid LDAP Bind Attempt

In this example, an invalid set of LDAP bind credentials were defined in the authentication policy.

Fri Oct 19 18:17:16 2007
/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/naaad.c[359]: process_kernel_socket call to
authenticate user :scottli, vsid :527
Fri Oct 19 18:17:16 2007
/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
Fri Oct 19 18:17:18 2007
/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[291]: recieve_ldap_bind_event receive ldap bind event
Fri Oct 19 18:17:18 2007
/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[326]:
recieve_ldap_bind_event ldap_bind with binddn bindpw failed:Invalid credentials 
Fri Oct 19 18:17:18 2007 /usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/naaad.c[1198]: send_reject sending reject to kernel for : scottli

Determining Group Extraction Results

In this example, the group extraction results can be determined. Many issues with AAA group access involves the user not picking up the correct session polices for their assigned group in a Citrix Gateway appliance. Common reasons for this include incorrect spelling of Active Directory/Radius group name in the appliance and users not being a member of the security group in Active Directory/Radius.

Fri Oct 19 18:22:14 2007 /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 
Fri Oct 19 18:22:14 2007 
/usr/home/build/rs_80_48/usr.src/usr.bin/nsaaad/../../netscaler/aaad/ldap_drv.c[291]: 
recieve_ldap_bind_event receive ldap bind event 
Fri Oct 19 18:22:14 2007 /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 

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

Background

Authentication processing in Citrix 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.”