Adaptive Authentication service

Citrix Cloud customers can use Citrix Workspace to provide Adaptive Authentication to Citrix DaaS. Adaptive Authentication is a Citrix Cloud service that enables advanced authentication for customers and users logging in to Citrix Workspace. Adaptive Authentication service is a Citrix managed and Citrix Cloud hosted ADC that provides all the advanced authentication capabilities such as the following:

Multifactor authentication: Multifactor authentication enhances the security of an application by requiring users to provide multiple proofs of identity to gain access. Customers can configure various combinations of factors in the multifactor authentication mechanism based on the business requirement. For details, see Sample authentication configurations.

Device posture scans: Users can be authenticated based on the device posture. Device posture scan, also known as endpoint analysis scan, checks if the device is compliant. For example, if the device is running the latest OS version, service packs, and registry keys are set. Security compliance involves scans to check if an antivirus is installed or the firewall is turned on and so on. The device posture can also check if the device is managed or unmanaged, corporate owned, or BYOL.

Conditional authentication: Based on the user’s parameters, such as network location, device posture, user group, time of the day, conditional authentication can be enabled. You can use one of these parameters or a combination of these parameters for doing conditional authentication. Example of a device posture-based authentication: You can do a device posture scan to check if the device is a corporate managed or BYOD. If the device is a corporate managed device, you can challenge the user with the simple AD (user name and password). If the device is a BYOD, you can challenge the user with the AD plus RADIUS authentication.

Contextual access to Citrix DaaS: Adaptive Authentication enables contextual access to Citrix DaaS. Adaptive Authentication surfaces all the policy information about the user to Citrix DaaS. Admins can use this information in their policy configurations to control the users actions that can be performed on Citrix DaaS. User action, for example, can be enabling or disabling clipboard access, and client drive mapping printer redirection.

Contextual access to Secure Internet Access and other Citrix Cloud services through Adaptive Authentication is planned in the upcoming releases.

Logon page customization: Adaptive Authentication helps the user to highly customize the Citrix Cloud logon page.

Adaptive Authentication capabilities

The following are the capabilities supported in Citrix Workspace with Adaptive Authentication.

  • LDAP (Active Directory)
  • Directory Support for AD, Azure AD, Okta
  • RADIUS support (Duo, Symantec)
  • AD + token built-in MFA
  • SAML 2.0
  • OAuth, OIDC support
  • Client Certificate authentication
  • Device posture assessment (Endpoint analysis)
  • Integration with third-party authentication providers
  • Push notification through the app
  • reCAPTCHA
  • Conditional/policy driven authentication
  • Authentication policies for SmartAccess (Contextual access)
  • Logon page customization
  • Self service password reset

Prerequisites

  • Reserve an FQDN for your Adaptive Authentication instance. For example, aauth.xyz.com, assuming xyz.com is your company domain. This FQDN is referred as the Adaptive Authentication service FQDN in this document and is used when provisioning the instance. Map the FQDN with the IdP virtual server public IP address. This IP address is obtained after provisioning in the Upload Certificate step.
  • Procure a certificate for aauth.xyz.com. Certificates must contain the SAN attribute. Else the certificates are not accepted.

  • Adaptive Authentication UI does not support uploading of certificate bundles. To link an intermediate certificate, see Configure intermediate certificates.

  • Choose your connectivity type for the on premises AD/RADIUS connectivity. The following two options are available. If you do not want data center reachability, use the connector connectivity type.

  • Configure network time protocol (NTP) server to avoid time skews. For details, see How to synchronize system clock with servers on the network.

Points to note

  • Citrix recommends not to run clear config for any Adaptive Authentication instance or modify any configuration with the prefix AA (example, AAuthAutoConfig) including certificates. This disrupts Adaptive Authentication management and user access is impacted. The only way to recover is through reprovisioning.
  • Do not add SNIP or any additional routes on the Adaptive Authentication instance.
  • The nFactor configuration that is required for the Citrix Workspace or the Citrix Secure Private Access service is the only configuration customers are supposed to create directly on the instances. Currently there are no checks or warnings in the Citrix ADC that prevents admins from making these changes.
  • Do not upgrade the Adaptive Authentication instances to random RTM builds. All upgrades are managed by Citrix Cloud.
  • Only Windows based cloud connector is supported. Connector appliance is not supported in this release.
  • If you are an existing Citrix Cloud customer and have already configured Azure AD (or other authentication methods), to switch to Adaptive Authentication (for example, device posture check), you must configure Adaptive Authentication as your authentication method and configure the authentication policies in the Adaptive Authentication instance. For details, see Connect Citrix Cloud to Azure AD.
  • In the current release, the external ADM agent is not allowed and therefore Citrix Analytics (CAS) is not supported.
  • For RADIUS server deployment, add all connector private IP addresses as the RADIUS clients in the RADIUS server.
  • Citrix Application Delivery Management service collects the backup for your Adaptive Authentication instance. To extract the backup from ADM, onboard the ADM service. For details, see Config backup and restore. Citrix does not take the backups explicitly from the Adaptive Authentication service. Customers must take the backup of their configurations from the Application Delivery Management service if necessary.

How to configure the Adaptive Authentication service

Access the Adaptive Authentication user interface

You can access the Adaptive Authentication user interface by one of the following methods.

  • Manually type the URL https://adaptive-authentication.cloud.com.
  • Login using your credentials and select a customer.

    After you are successfully authenticated, you are redirected to the Adaptive Authentication user interface.

OR

  • Navigate to Citrix Cloud > Identity and Access Management.
  • In the Authentication tab, in Adaptive Authentication, click the ellipsis menu and select Manage.

The Adaptive Authentication user interface appears.

The following figure illustrates the steps involved in configuring Adaptive Authentication.

Provisioning the main page

Step 1: Provision Adaptive Authentication

Perform the following steps:

  1. On the Adaptive Authentication UI, click Provision.
  2. Select the preferred connection for Adaptive Authentication.

    • Citrix Cloud Connector: For this connection type, you must set up a connector in your on premises network. Citrix recommends that you deploy at least two Citrix Cloud Connectors in your environment to set up connection to the Citrix Gateway hosted on Azure. You must allow your Citrix Cloud Connector to access the domain/URL you have reserved for the Adaptive Authentication instance. For example, allow https://aauth.xyz.com/*.

      For details on Citrix Cloud Connector, see Citrix Cloud Connector.

    • Azure VNet peering - You must set up the connectivity between the servers using Azure’s VNet peering.

    Connection type

    To add a Citrix Cloud Connector as your preferred connection:

    Perform the following steps.

    • Select the Citrix Cloud Connector option, and then select the end user agreement check box.
    • Click Provision. Provisioning might take up to 30 minutes to set up.

    Note:

    For connector connectivity type, make sure that your Adaptive Authentication FQDN is reachable from the connector virtual machine after provisioning.

    To set up Azure VNet peering:

    If you select Azure VNet peering as your connection, you must add a subnet CIDR block that must be used to provision the Adaptive Authentication instance. You must also ensure that the CIDR block does not overlap with your organization’s other network ranges.

    For details, see Set up connectivity to on-premises authentication servers using Azure VNet peering.

  3. Set up credentials to access the instances that you have enabled for Adaptive Authentication. You need the management console access for creating policies for authentication, conditional access, and so on.

    1. In the Console access screen, enter the user name and password.
    2. Click Next.

    Note: Users created from the Console access screen are provided with “SuperUser” privileges that have the shell access.

    Console access

  4. Add the Adaptive Authentication service FQDN and upload the certificate-key pair. You must enter the Adaptive Authentication service FQDN of your choice for the publicly accessible authentication server.

    1. In the Upload Certificate screen, enter the FQDN that you have reserved for Adaptive Authentication.
    2. Select the certificate type.
    3. Upload the certificate and the key.

    Note:

    • Install your intermediate certificate on the Adaptive Authentication instance and link it with the server certificate.

      1. Log in to the Adaptive Authentication instance.
      2. Navigate to Traffic Management > SSL. For details, see Configure intermediate certificates.
    • Only public certificates are accepted. Certificates signed by private or unknown CAs are not accepted.
    • Certificate configuration must be done using the Adaptive Authentication UI only. Do not change it directly on the instance as this might result in inconsistencies.

    Add FQDN

  5. Upload the certificate and the key.

    The Adaptive Authentication instance now is connected to the Identity and Access Management service. The Adaptive Authentication method status is displayed as Connected.

    Adaptive Authentication connected on IDAM

  6. Set up an IP addresses through which the Adaptive Authentication management console can be accessed.
    1. In the Allowed IP addresses screen, for each instance, enter a public IP address as the management IP address. To restrict the access to the management IP address, you can add multiple IP addresses that are allowed to access the management console.
    2. To add multiple IP addresses, you must click Add, enter the IP address, and then click Done. This must be done for every IP address. If you do not click the Done button, the IP addresses are not added to the database but are only added in the user interface.

    Allowed IP addresses

Step 2: Configure Adaptive Authentication policies

After the provisioning, you can access the Adaptive Authentication management IP address directly. However, accessing the instance using the IP address is not trusted and many browsers block the access with warnings. Citrix recommends that you access the Adaptive Authentication management console with FQDN to avoid any security barriers. You must reserve the FQDN for the Adaptive Authentication management console and map it with the primary and secondary management IP address.

For example, if your AA instance IP is 20.1.1.1 and Secondary: 20.2.2.2, then;

  • primary.domain.com can be mapped to 20.1.1.1

  • secondary.domain.com can be mapped to 20.2.2.2

After accessing the Adaptive Authentication instance, you can then configure the authentication flow use cases as per your requirement. For various use cases, see Sample authentication configurations.

To access the Adaptive authentication management console using the FQDN, see Configure SSL for ADC Admin UI access.

Configure Adaptive Authentication policies

Important:

  • In a high availability setup, as part of the synchronization process, the certificates are also synchronized. So ensure that you use the wildcard certificate.
  • If you need unique certificate for each node, upload the certificate files and keys in any folder that doesn’t get synchronized (for example, create a separate folder (nosync_cert) in the nsconfig/SSL directory) and then upload the certificate uniquely on each node.
  • To enable single sign on to applications, ensure that you enable the Send Password option in the OAuth IdP profile.

Step 3: Enable Adaptive Authentication for Workspace

After provisioning is complete, you can enable authentication for Workspace by clicking Enable in the Enable Adaptive Authentication for Workspace section.

Enable Adaptive Authentication for Workspace

Note:

With this step, the Adaptive Authentication configuration is completed.

Migrate your authentication method to Adaptive Authentication

Customers already using Adaptive Authentication with authentication method as Citrix Gateway must migrate Adaptive Authentication and then remove the OAuth configuration from the Adaptive Authentication instance.

  1. Switch to a different authentication method other than Citrix Gateway.
  2. In Citrix Cloud > Identity and Access Management, click the ellipsis button corresponding to Citrix Gateway and then click Disconnect.

    Disconnect gateway

  3. Select I understand the impact on the subscriber experience, and then click Confirm.

    When you click Confirm, the workspace login to end users is impacted and adaptive authentication is not used for authentication until adaptive authentication is enabled again.

  4. In the Adaptive Authentication instance management console, remove the OAuth related configuration.

    By using the CLI:

    unbind authentication vs <authvsName> -policy <oauthIdpPolName>
    rm authentication oauthIdpPolicy <oauthIdpPolName>
    rm authentication oauthIdpProfile <oauthIdpProfName>
    <!--NeedCopy-->
    

    By using the GUI:

    1. Navigate to Security > AAA - Application Traffic > Virtual Servers.
    2. Unbind the OAuth policy.
    3. Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Policies > OAuth IDP.
    4. Delete the OAuth policy and profile.
  5. Navigate to Citrix Cloud > Identity and Access Management. In the Authentication tab, in Adaptive Authentication, click the ellipsis menu and select Manage.

    OR access https://adaptive-authentication.cloud.com

  6. Click See Details.
  7. In the Upload Certificate screen, do the following:
    • Add the Adaptive Authentication FQDN.
    • Remove the certificates and key files and upload it again.

    Edit FQDN

    Important:

    If you edit an FQDN or the certificate-key pair directly without migrating to Adaptive Authentication, connection to Identity and Access Management fails and the following errors are displayed. You must migrate to the Adaptive Authentication method to fix these errors.

    • ADC command failed with an error. A policy is already bound to the specified priority.
    • ADC command failed with an error. Cannot unbind a policy that is not bound.
  8. Click Save Changes.

    At this point, Identity and Access Management displays Adaptive Authentication as Connected and the Adaptive Authentication instance has the OAuth profile auto configured.

    You can validate this from the GUI.

    1. Access your Adaptive Authentication instance and log in with your credentials.
    2. Navigate to Security > AAA - Application Traffic > Virtual Servers. You must see that the OAuth IdP profile created.
    3. Navigate to Citrix Cloud > Identity and Access Management. Adaptive authentication is in the Connected status.
  9. Enable the Adaptive Authentication method again by clicking Enable (step 3) in the adaptive authentication home page.

    Enable authentication

    This step enables the authentication method as Adaptive Authentication in your workspace configuration.

  10. Click the workspace link on step 3 after clicking Enable. You must see that the authentication method is changed to Adaptive Authentication.

Note:

New users must follow the same steps excluding the step to remove the OAuth related configuration.

Edit an FQDN

You cannot edit an FQDN if Adaptive Authentication is selected as the authentication method in the Workspace configuration. You must switch to a different authentication method to edit the FQDN. However, you can edit the certificate if necessary.

Important:

  • Before modifying the FQDN, ensure that the new FQDN is mapped to the IdP virtual server public IP address.
  • Existing users who are connected to Citrix Gateway using OAuth policies must migrate your authentication method to Adaptive Authentication. For details, see Migrate your authentication method to Adaptive Authentication.

To edit an FQDN, perform the following:

  1. Switch to a different authentication method from Adaptive Authentication.

    Switch authentication method

  2. Select I understand the impact on the subscriber experience, and then click Confirm.

    When you click Confirm, the workspace login to end users is impacted and Adaptive Authentication is not used for authentication until Adaptive Authentication is enabled again. Therefore, it is recommended that you modify the FQDN during a maintenance window.

  3. In the Upload Certificate screen, modify the FQDN.

    Edit FQDN

  4. Click Save Changes.

    Important:

    If you edit an FQDN, you must also upload the certificate again.

  5. Enable the Adaptive Authentication method again by clicking Enable (step 3) in the Adaptive Authentication home page.

    Enable authentication

  6. Click Refresh.

Advanced configuration options

By using the Adaptive Authentication GUI, you can also set up the following.

  • Schedule upgrade of your Adaptive Authentication instances
  • Deprovision your Adaptive Authentication instances
  • Enable secure access to the gateway

Advanced options

Schedule upgrade of your Adaptive Authentication instances

For the current site or deployment, you can select the maintenance window for upgrade.

Important:

Do not upgrade the Adaptive Authentication instances to random RTM builds. All upgrades are managed by Citrix Cloud.

  1. On the Adaptive Authentication UI, in the Provision Adaptive Authentication instances section, click the ellipsis button.
  2. Click Schedule upgrades.
  3. Select the day and time for the upgrade.

Schedule upgrade

Deprovision your Adaptive Authentication instances

Customers can deprovision the Adaptive Authentication instances in the following cases and as per the suggestion from Citrix support.

  • The Adaptive Authentication instances are not accessible (especially after a scheduled upgrade), though this scenario might not occur.
  • If the customer has to switch from VNet peering mode to connector mode or conversely.
  • If the customer selected a wrong subnet at the time of provisioning VNet peering mode (the subnet conflicts with other subnets in their data center or Azure VNet).

Note:

Deprovisioning also deletes the config backup of the instances. Therefore you must download the backup files and save it before you deprovision your Adaptive Authentication instances.

Perform the following to deprovision an Adaptive Authentication instance:

  1. On the Adaptive Authentication UI, in the Provision Adaptive Authentication instances section, click the ellipsis button.
  2. Click Deprovision.

    Note:

    Before deprovisioning, you must disconnect Citrix Gateway from the Workspace Configuration.

  3. Enter the customer ID to deprovision the Adaptive Authentication instances.

Deprovision

Enable secure access to the gateway

  1. On the Adaptive Authentication UI, in the Provision Adaptive Authentication instances section, click the ellipsis button.
  2. Click Secure access to the gateway.

    Secure access

  3. In Keys should expire in, select an expiration duration for the new SSH key.
  4. Click Generate and Download keys. Copy or download the SSH private key for later use as it is not displayed after the page is closed. This key can be used to log in to the Adaptive Authentication instances with the user name authadmin.

    You can click Generate and Download keys to create a new key pair if the earlier key pair expires. However, only one key pair can be active.

  5. Click Done.

Important:

  • If you are using PuTTY on Windows to connect to Adaptive Authentication instances, you must convert the downloaded private key to PEM. For details, see https://www.puttygen.com/convert-pem-to-ppk.

  • It is recommended to use the following command to connect to the Adaptive Authentication instances via the terminal from the MAC or PowerShell/Command prompt from Windows (version 10). ssh -i <path-to-private-key> authadmin@<ip address of ADC>
  • If you want the AD users to access the Adaptive Authentication GUI, you must add them as new administrators to the LDAP group. For details, see https://support.citrix.com/article/CTX123782. For all other configurations, Citrix recommends that you use the Adaptive Authentication GUI and not the CLI commands.

Set up connectivity to on-premises authentication servers using Azure VNet peering

You must set up this configuration only if you have selected the connectivity type as Azure VNet peering.

Note: If you are using third-party IDPs like Okta, Azure AD, Ping, this step is not required.

  1. On the Connect Adaptive Authentication UI, click Provision, and then click Azure VNet Peering.

    VNet peering

    The Citrix Managed Service Principal field contains the application ID of an Azure Service Principal created by Citrix for your customer. This service principal is required to allow Citrix to add a VNet peering to a VNet in your subscription and tenant.

    To allow this service principal to log in to the customer tenant, the admin at the customer site (global admin of the tenant) must run the following PowerShell commands to add the SPN to the tenant. CloudShell can also be used. Connect-AzureAD New-AzureADServicePrincipal -AppId $App_ID Where $App_ID is an SPN Application ID shared by Citrix.

    Note:

    • The earlier-mentioned command outputs a service principal name that must be used for the role assignments.
    • To allow this service principal to add an Azure VNet peering, the admin at the customer site (not limited to global admin) must add a “Network Contributor” role to the VNet that must be linked to the Citrix Managed VNet.
    • SPN is a unique identifier that is used to associate the Citrix virtual network in Azure. Associating the SPN with VNet enables Citrix virtual network to connect to the customers’ on-premises network through Azure’s VNet.
  2. Create a VNet peering.

    • Enter the tenant ID for which the earlier steps were run and click Fetch.

    This populates the customer-managed VNet resource ID with the candidate VNets for which the network contributor role is added for the SPN. If you do not see your VNet, make sure that the earlier steps are run correctly or repeat the steps.

    Note:

    For details on how to find your tenant ID, see https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant.

  3. Select Use Azure VPN Gateway to connect your on-premises networks to Azure.
  4. In Customer managed VNet Resource ID, select the VNet identified for peering, and click Add. The VNet is added to the table with the status initially as In Progress. Once the peering is completed successfully, the Status changes to Done.
  5. Click Done.
  6. Continue with the configuration, see Step 1: Provision Adaptive Authentication.

    Important:

    • For traffic to flow between the Citrix managed VNet and the on-premises network, firewall and routing rules might be changed on the on premises to direct the traffic to the Citrix Managed VNet.
    • You can add only one VNet peer at a time. Multiple VNet peerings are not allowed currently. You can delete a VNet peering or create one as required.

Provisioning is complete

Change the authadmin password

You can use the following steps to change the password for the authadmin user, both on the instances and in the ADM device profile.

  1. Navigate to System > User Administration > Users, and create the user. For details, see Configure user accounts.
  2. Save the configuration.
  3. In the Citrix Application Delivery Management service, perform the following:
    • Navigate to Networks > Instances > Citrix ADC.
    • Click Profiles and select the profile prefixed with gateway-hosted.
    • Select Change Password and set the password used in step 2.
    • Click Back.
    • Go to Citrix ADC > Select Action > Rediscover.

For more information, see How to change the Citrix ADC MPX and VPX root password.

Config backup and restore

Application Delivery Management service performs backup management for the Adaptive Authentication instances. For details, see Back up and restore Citrix ADC instances.

  1. On the Application Delivery Management tile, click Manage.
  2. Navigate to Infrastructure > Instances and access the backups.

Note:

If you do not see the service onboarded, onboard the Application Delivery Management service. For details, see Getting started.

Troubleshooting

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

  • Provisioning – Issues while provisioning the Adaptive Authentication instance
  • Instance accessibility issue: Instance is provisioned but the admin cannot access it
  • AD/Radius connectivity and authentication issue: Authentication policy is set up for the on premises but it is not working
  • Authentication issues
  • EPA/device posture-related issues
  • Smart tag-related issues
  • Log collection

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 Citrix ADC appliance.

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.

     LDAP:
     [NS_AAUTH_TUNNEL] Entering bitpump for
     Connection1 => Src : 192.168.0.7:28098, Dst : 10.106.103.60:636 , Connection2 => Src : 10.106.103.70:2271, Dst : 10.106.103.80:443"
     RADIUS:
     [NS_AAUTH_UDP_TUNNEL] MUX channel established"
     <!--NeedCopy-->
    

    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 0.0.0.0 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 the Citrix ADC appliance. 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(10.0.0.0,10.255.255.255) || CLIENT.IP.DST.BETWEEN(172.16.0.0,172.31.255.255) || CLIENT.IP.DST.BETWEEN(192.168.0.0, 192.168.255.255) || CLIENT.IP.DST.BETWEEN(13.14.0.0, 13.14.255.255)||CLIENT.IP.DST.EQ(1.2.5.4))"
     <!--NeedCopy-->
    
  • To add a subnet or IP address by using the GUI:

    Navigate to Appexpert > Expressions. Add expression aauth_allow_rfc1918_subnets

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

LDAP:

  • 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.

     shell
     cd /tmp
     cat aaad.debug
     <!--NeedCopy-->
    

Common LDAP errors:

Radius:

  • 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 the var/log ns.log files to locate the error for OAuth failures.

    • 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 Citrix ADC and your client machine.

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

      Update the client on the Citrix ADC.

      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 Citrix ADC 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 https://support.citrix.com/article/CTX209148.

  • 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.

Sample authentication configurations

Customers can configure an authentication policy of their choice and bind it to the authentication virtual server. Authentication profile bindings are not required for the authentication virtual server. Only the authentication policies can be configured. The following are some of the use cases.

Important:

Authentication configuration must be done on the primary nodes only.

Multifactor authentication with conditional authentication

Third-party integration with multifactor authentication

Device posture scans (EPA)

Miscellaneous scenarios

Shared security responsibilities

Actions needed from customers

Following are some of the actions from the customers as part of security best practices.

  • Credentials for accessing the Adaptive Authentication UI: Customer is responsible for creating and maintaining the credentials for accessing the Adaptive Authentication UI. If the customer is working with Citrix Support to resolve an issue, the customer might need to share these credentials with support personnel.
  • Change the authadmin password: As part of provisioning, Citrix creates an initial user called authadmin and the corresponding device profile in the Citrix Application Delivery Management service and Adaptive Authentication instances. Customers must change the password of this user in the primary node and in the device profile of ADM. Log on to your Citrix Gateway, change the user name and password. For details, see Change authadmin password.

  • Remote CLI access security: Citrix provides remote CLI access for customers. However, customers are responsible for maintaining the security of the instance during runtime.

  • SSL private keys: As the Citrix ADC is under customer control, Citrix does not have any access to the file system. Customers must ensure that they safeguard the certificates and keys that they are hosting on the Citrix ADC instance.

  • Data backup: Back up the configuration, certificates, keys, portal customizations, and any other file system modifications.

  • Disk images of the ADC instances: Maintain and manage the Citrix ADC disk space and disk clean-up. Customer is responsible for running these tasks safely and securely.
  • Upgrade: Schedule upgrade of the Adaptive Authentication instances. For details, see Schedule upgrade of your Adaptive Authentication instances.

Actions needed from both the customer and Citrix

  • Disaster recovery: In supported Azure regions, the Citrix ADC high availability instances are provisioned in separate availability zones to safeguard against data loss. In the event of Azure data loss, Citrix recovers as many resources in the Citrix-managed Azure subscription as possible.

    In the event of the loss of an entire Azure region, the customer is responsible for rebuilding their customer-managed virtual network in a new region and creating a new VNet peering.

  • Secure access via the public management IP address:

    Secure the access to the management interfaces by assigned public IP addresses and allow outbound connectivity to the Internet.

Limitations

  • Authentication through load balancing virtual server is not supported.
  • Certificate bundle upload is not supported.
  • RADIUS authentication is impacted for a few minutes if the connector serving the RADIUS request goes down. User must reauthenticate in this case.
  • Currently, the Adaptive Authentication instance can send the on premises traffic request to any connector in any resource location. Data center connectivity might fail if data centers are disjoint. If needed, all of the on premises connectivity traffic can be sent to one resource location using the following command:

    set cloudtunnel parameter -resourceLocation <RL>

    To revert to default settings, use the following command:

    set cloudtunnel parameter -resourceLocation 00000000-0000-0000-0000-000000000000

  • DNS tunneling is not supported. Static records must be added on the Citrix ADC appliance for the FQDNs used in authentication policies/profiles (LDAP/RADIUS) for authentication servers in the customer’s on premises data center. For details on adding DNS static records, see Create address records for a domain name.

  • Test Network connectivity in the LDAP profile might show an incorrect result as “Server is reachable” even if the connectivity to the LDAP server is not established. Error messages such as “port is not open”, or “server is not LDAP” might be displayed to indicate the failure. Citrix recommends collecting the traces in this scenario and troubleshooting further.
  • For EPA scans to work on macOS, you must bind the default ECC curves to the authentication and authorization virtual server by selecting the ECC Curve option as ALL.

Service quality

Adaptive Authentication is a high availability (active-standby) service.