Troubleshoot Adaptive Authentication issues

The issues are categorized based on the different stages in the configuration:

You can troubleshoot the issues using the Adaptive Authentication CLI as well. To connect to the CLI, do the following:

  • Download SSH client like putty/securecrt on your machine.
  • Access the Adaptive Authentication instance using the management IP (primary) address.
  • Login with your credentials.

For details, see Access a NetScaler appliance.

Enable logging of adaptive authentication logs

Make sure that you enable the log levels to capture the adaptive authentication logs.

Enable logs using CLI:

  1. Log in to the Adaptive Authentication instance CLI.
  2. Using PuTTY, enter the management credentials.
  3. Run the command set audit syslogParams logLevel ALL

Enable logs using GUI:

  1. Log in to the Adaptive Authentication instance using a browser.
  2. Navigate to Configuration > System > Auditing.
  3. In the Auditing page, under Settings, click Change Auditing syslog Settings.
  4. In Log Levels, select ALL.

Provisioning issues

  • Unable to access the Adaptive Authentication UI

    Check if the entitlement is enabled for your customer ID/tenant.

  • Stuck in the provisioning page for more than 45 min

    Collect the screenshot of the error, if any, and then contact Citrix Support for assistance.

  • VNet peer is down

    • Check if there are alerts in the Azure Portal corresponding to this peering and take the recommended actions.
    • Delete the peering, add it again from the Adaptive Authentication UI.
  • Deprovisioning is not complete

    Contact Citrix Support for assistance.

Instance accessibility issue

  • Management IP address is not accessible for the instance

    • Check if the client’s public IP address used for access is among the allowed source IP addresses.

    • Validate if there is any proxy changing the client source IP address.

  • Unable to log in to the instance

    Make sure that the admin access is working fine with the credentials you entered during provisioning.

  • End users do not have complete rights

    Make sure while adding the user, you have bound the suitable command policy for access. For more information, see User, user groups, and command policies.

AD or RADIUS connectivity issue

Issue with Azure Vnet peering connectivity type:

  • Check if the customer managed Azure VNet is reachable from the Adaptive Authentication instances.
  • Check if connectivity/reachability from customer managed Azure VNet to AD is working.
  • Ensure that appropriate routes are added to direct traffic from on-premises to Azure VNets.

Windows based Connector:

  • All logs are available in the directory /var/log/ns.log and each log is prefixed with [NS_AAUTH_TUNNEL].
  • ConnectionID from logs can be used to correlate different transactions.
  • Ensure that the private IP address of the connector virtual machine is added as one of the RADIUS clients in the RADIUS server because that IP address is the source IP address for the connector.

    For every authentication request, the tunnel is established between the Adaptive Authentication Instance (NS - AAAD process) and the authentication server. Once the tunnel is established successfully, authentication occurs.

    Make sure that the connector virtual machine can resolve the Adaptive Authentication FQDN.

  • Connector is installed however the on-premises connectivity fails.

    Validate if NSAUTH-TUNNEL is getting established.

    cat ns.log | grep -I “tunnel”

    If the following sample log is not printed in the ns.log file for the authentication request, then there might be an issue while establishing a tunnel or some issue from the connector side.

     [NS_AAUTH_TUNNEL] Entering bitpump for
     Connection1 => Src :, Dst : , Connection2 => Src :, Dst :"
     [NS_AAUTH_UDP_TUNNEL] MUX channel established"

    Check the log details and take actions appropriately.

    Log details Corrective action
    No logs with prefix [NS_AAUTH_TUNNEL] are included in the log file Run the show cloudtunnel vserver command. This command must list both (TCP and UDP) cloud tunnel virtual server with the state “UP.”
    [NS_AAUTH_TUNNEL] Waiting for outbound from connector For this log, if the following response is not received: [NS-AAUTH-TUNNEL] Received connect command from connector and client connection lookupsucceeded" Check if the connector machine is able to reach to the Adaptive Authentication FQDN OR check the connector side firewall for outbound connections to the Adaptive Authentication FQDN
    [NS_AAUTH_TUNNEL] Server is down or couldn't create connection to ip and [NS_AAUTH_TUNNEL] Connect response code 401 is not 200 OK, bailing out" Reach out to Citrix Support.

No response from connector:

  • Make sure that Adaptive Authentication FQDN is reachable from the connector virtual machine.
  • Make sure that you have an intermediate certificate bound and linked to the server certificate on the Adaptive Authentication instance.

Incorrect LDAP/RADIUS settings:

If your AD/RADIUS server IP address is a public IP address, you must add the subnet or the IP addressing the expressions in NetScaler. Do not edit the existing ranges.

  • To add a subnet or IP address by using the CLI:

     set policy expression aauth_allow_rfc1918_subnets "(CLIENT.IP.DST.BETWEEN(, || CLIENT.IP.DST.BETWEEN(, || CLIENT.IP.DST.BETWEEN(, || CLIENT.IP.DST.BETWEEN(,||CLIENT.IP.DST.EQ("
  • To add a subnet or IP address by using the GUI:

    1. Navigate to Appexpert > Expressions.
    2. Add expression aauth_allow_rfc1918_subnets.

If the tunnel is established but still authentication fails, use the following steps to troubleshoot the issue.


  • Validate the Bind DN details.
  • Use test connectivity to confirm the error.
  • Validate the errors using aaad debug.
  • Log in to the Adaptive Authentication instance by using the CLI.

     cd /tmp
     cat aaad.debug

Common LDAP errors:


  • Connector IP address must be added as the RADIUS client source IP address in the RADIUS server configuration.

Authentication issues

  • Post assertion errors for OAuth

    • Make sure that all the claims are provided by AD. You need 7 claims for this to be successful.

    • Validate the logs in /var/log/ns.log to locate the error for OAuth failures.

     cat /var/log/ns.log
    • Validate the OAuth profile parameters.
  • Azure AD authentication stuck at post assertion

    Add AD authentication as the next factor with authentication set to off. This is to get all the required claims for successful authentication.

  • Plug-in is already present but the user is getting a prompt to download the plug-in.

    Possible causes: Version mismatch or corrupt files

    • Run developer tools and validate if the plug-in list file contains the same version as that of the NetScaler and your client machine.

    • Make sure that the client version on the NetScaler is the same as on the client machine.

      Update the client on the NetScaler.

      On the Adaptive Authentication instance, navigate to Citrix Gateway > Global Settings > Update client libraries.

      The EPA plug-in libraries page on Citrix Downloads provides you the detailed information.

    • At times, the request can be cached on NetScaler even if the version is updated.

      show cache object displays the cached plug-in details. You can delete it by using the command;

      flush cache object -locator 0x00000023345600000007

    For details on EPA log collection, see

  • Is there a way to revert the EPA settings (Always, Yes, No) after the user has selected an option.

    Currently, EPA settings revert is done manually.

    • On the client machine, navigate to C:\Users<user_name>\AppData\Local\Citrix\AGEE.
    • Open the config.js file and set trustAlways to null - "trustAlways":null

Smart access tag issues

  • After configuring the smart access, applications are not available

    Make sure that the tags are defined on both the Adaptive Authentication instance and the Citrix VDA delivery groups.

    Check that the tags are added on the Workspace delivery group in all capitals.

    You can collect the ns.log and reach out to Citrix Support if this does not work.

General log collection for Adaptive authentication instance

Contact Citrix Support for guidance.

Troubleshoot Adaptive Authentication issues