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.
If you plan to selectively enumerate virtual apps and desktops based on network location, then user management has to be performed for those delivery groups using Citrix Studio policies instead of workspace. When creating a delivery group, in the users setting, either choose Restrict use of this Delivery Group to the following users or Allow any authenticated users to use this Delivery Group. This enables the Access Policy tab under Delivery Group to configure adaptive access.
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
- Conditional/policy driven authentication
- Authentication policies for SmartAccess (Contextual access)
- Logon page customization
- Self service password reset
- Reserve an FQDN for your Adaptive Authentication instance. For example,
xyz.comis 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.
- Citrix Cloud Connector - For details, see Citrix Cloud Connector.
- Azure VNet peering - For details, see Set up connectivity to on-premises authentication servers using Azure VNet peering.
- 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.
- User authentication fails if the customer ID is not in all lowercase. You can convert your ID to all lowercase and set it on the ADC instance by using the command
set cloud parameter -customerID <all_lowercase_customerid>.
- 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.
- For RADIUS server deployment, add all connector private IP addresses as the RADIUS clients in the RADIUS server.
- Do not add your LDAP or RADIUS servers as a service or a server.
- In the current release, the external ADM agent is not allowed and therefore Citrix Analytics (CAS) is not supported.
- 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.
Log in using your credentials and select a customer.
After you are successfully authenticated, you are redirected to the Adaptive Authentication user interface.
- 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.
Step 1: Provision Adaptive Authentication
Perform the following steps:
- On the Adaptive Authentication UI, click Provision.
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.
- Ensure that you have an Azure subscription account to set up the connectivity.
- The customer VNet that is being peered must already have an Azure VPN gateway provisioned. For details, see https://docs.microsoft.com/en-us/azure/vpn-gateway/tutorial-site-to-site-portal.
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.
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.
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.
- In the Console access screen, enter the user name and password.
- Click Next.
Note: Users created from the Console access screen are provided with “SuperUser” privileges that have the shell access.
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.
- In the Upload Certificate screen, enter the FQDN that you have reserved for Adaptive Authentication.
- Select the certificate type.
- Upload the certificate and the key.
Install your intermediate certificate on the Adaptive Authentication instance and link it with the server certificate.
- Log in to the Adaptive Authentication instance.
- 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.
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.
- Set up an IP addresses through which the Adaptive Authentication management console can be accessed.
- 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.
- 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.
Specify a set of resource locations (connectors) through which AD or RADIUS servers can be reached.
Admins can choose the connectors through which backend AD and RADIUS servers must be reached. To enable this feature, customers can set up a mapping between their backend AD/RADIUS server subnets such that if the authentication traffic falls under a specific subnet, then that traffic is directed to the specific resource location. However, If a resource location is not mapped to a subnet, then admins can specify to use the wildcard resource location for those subnets.
Previously, adaptive authentication traffic for on-premises AD/RADIUS was directed to any available resource location using the round robin method. This caused issues for customers with multiple resource location.
- On the Adaptive Authentication UI, click Manage Connectivity.
- Enter the subnet details and select the respective resource location. Note: If you clear the Use any available resource location for remaining subnets check box, only the traffic directed towards the configured subnets is tunneled.
- Click Add, and then click Save Changes.
- Only RFC1918 IP address subnets are allowed.
- The number of subnet-resource location mapping per customer is limited to 10.
- Multiple subnets can be mapped to a single resource location.
- Duplicate entries are not allowed for the same subnet.
- To update the subnet entry, delete the existing entry and then update.
- if you rename or remove the resource location, make sure to remove the entry from Adaptive Authentication instance as well.
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 18.104.22.168 and Secondary: 22.214.171.124, then;
primary.domain.com can be mapped to 126.96.36.199
secondary.domain.com can be mapped to 188.8.131.52
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.
- 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.
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.
- Switch to a different authentication method other than Citrix Gateway.
In Citrix Cloud > Identity and Access Management, click the ellipsis button corresponding to Citrix Gateway and then click Disconnect.
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.
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:
- Navigate to Security > AAA - Application Traffic > Virtual Servers.
- Unbind the OAuth policy.
- Navigate to Security > AAA - Application Traffic > Policies > Authentication > Advanced Policies > OAuth IDP.
- Delete the OAuth policy and profile.
Navigate to Citrix Cloud > Identity and Access Management. In the Authentication tab, in Adaptive Authentication, click the ellipsis menu and select Manage.
- Click See Details.
- In the Upload Certificate screen, do the following:
- Add the Adaptive Authentication FQDN.
- Remove the certificates and key files and upload it again.
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.
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.
- Access your Adaptive Authentication instance and log in with your credentials.
- Navigate to Security > AAA - Application Traffic > Virtual Servers. You must see that the OAuth IdP profile created.
- Navigate to Citrix Cloud > Identity and Access Management. Adaptive authentication is in the Connected status.
Enable the Adaptive Authentication method again by clicking Enable (step 3) in the adaptive authentication home page.
This step enables the authentication method as Adaptive Authentication in your workspace configuration.
- Click the workspace link on step 3 after clicking Enable. You must see that the authentication method is changed to Adaptive Authentication.
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.
- 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:
Switch to a different authentication method from Adaptive Authentication.
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.
In the Upload Certificate screen, modify the FQDN.
Click Save Changes.
If you edit an FQDN, you must also upload the certificate again.
Enable the Adaptive Authentication method again by clicking Enable (step 3) in the Adaptive Authentication home page.
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
Schedule upgrade of your Adaptive Authentication instances
For the current site or deployment, you can select the maintenance window for upgrade.
Do not upgrade the Adaptive Authentication instances to random RTM builds. All upgrades are managed by Citrix Cloud.
- On the Adaptive Authentication UI, in the Provision Adaptive Authentication instances section, click the ellipsis button.
- Click Schedule upgrades.
- Select the day and time for the 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).
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:
- On the Adaptive Authentication UI, in the Provision Adaptive Authentication instances section, click the ellipsis button.
Before deprovisioning, you must disconnect Citrix Gateway from the Workspace Configuration.
- Enter the customer ID to deprovision the Adaptive Authentication instances.
Enable secure access to the gateway
- On the Adaptive Authentication UI, in the Provision Adaptive Authentication instances section, click the ellipsis button.
Click Secure access to the gateway.
- In Keys should expire in, select an expiration duration for the new SSH key.
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
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.
- Click Done.
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.
On the Connect Adaptive Authentication UI, click Provision, and then click Azure 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.
New-AzureADServicePrincipal -AppId $App_IDWhere
$App_IDis an SPN Application ID shared by Citrix.
- 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.
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.
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.
- Select Use Azure VPN Gateway to connect your on-premises networks to Azure.
- 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.
- Click Done.
Continue with the configuration, see Step 1: Provision Adaptive Authentication.
- 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.
Other related configurations
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.
- Navigate to System > User Administration > Users, and create the user. For details, see Configure user accounts.
- Save the configuration.
- 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.
Custom workspace URL or vanity URL
For the custom workspace URL or vanity URL, configure a new OAuthIDP profile with the same client ID, secret, and audience as your current one but with a redirect URL of https://your.company.com/core/login-cip. In this example,
your.company.com is the custom workspace URL corresponding to your domain. For example,
nssvctesting.net is the domain and custom workspace URL is
Create a new OAuthIDP policy and bind it to the authentication and authorization virtual server.
Both OAuthIDP policies can co-exist and a user can access Workspace using the default Workspace URL or the custom workspace URL or both.
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.
- On the Application Delivery Management tile, click Manage.
- Navigate to Infrastructure > Instances and access the backups.
If you do not see the service onboarded, onboard the Application Delivery Management service. For details, see Getting started.
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.
Enable logging of adaptive authentication logs
Make sure that you enable the log levels to capture the adaptive authentication logs.
Enable logs using CLI:
- Log in to the Adaptive Authentication instance CLI.
- Using PuTTY, enter the management credentials.
- Run the command
set audit syslogParams logLevel ALL
Enable logs using GUI:
- Log in to the Adaptive Authentication instance using a browser.
- Navigate to Configuration > System > Auditing.
- In the Auditing page, under Settings, click Change Auditing syslog Settings.
- In Log Levels, select ALL.
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
show cloudtunnel vservercommand. This command must list both (TCP and UDP) cloud tunnel virtual server with the state “UP.”
[NS_AAUTH_TUNNEL] Waiting for outbound from connectorFor 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.0and
[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(184.108.40.206, 220.127.116.11)||CLIENT.IP.DST.EQ(18.104.22.168))" <!--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.
- Validate the Bind DN details.
- Use test connectivity to confirm the error.
- Validate the errors using
Log in to the Adaptive Authentication instance by using the CLI.
shell cd /tmp cat aaad.debug <!--NeedCopy-->
Common LDAP errors:
- Server time out – No response from the connector for the LDAP query.
- Other LDAP errors, see https://support.citrix.com/article/CTX138663.
- Connector IP address must be added as the RADIUS client source IP address in the RADIUS server configuration.
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.logfiles 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.
EPA related issues
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 objectdisplays 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.jsfile and set trustAlways to 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
- Technical support bundle: For details, see How to collect the technical support bundle from SDX and VPX appliances for insight analysis.
- Trace files. For details, see How to record a packet trace on Citrix ADC.
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.
Authentication configuration must be done on the primary nodes only.
Multifactor authentication with conditional authentication
- Dual factor authentication with LDAP and RADIUS using dual factor schema (taking user input only once)
- Authentication log on method according to user’s departments (Employee, Partner, Vendor) in organization with drop-down menu to select the department
- Authentication log on method according user domains with drop-down menu
- Configure email ID (or user name) input as first factor with conditional access based on group extraction with email ID at first factor and provide different logon type for each group
- Multifactor authentication using Certificate authentication for users with user certificates and Native OTP registration for non-cert users
- Different authentication type with conditional authentication according to user host name inputs
- Dual factor authentication with Native OTP authentication
- Google Re-CAPTCHA
Third-party integration with multifactor authentication
- Configure Azure AD as SAML IdP (Configure next factor as LDAP policy - NO_AUTH to complete OAuth trust)
- Conditional authentication with First factor as SAML and then custom login to certificate or LDAP based on SAML attributes
- First factor as webauth login followed by LDAP
Device posture scans (EPA)
- Device posture check for version check followed by customized login for compliant (RADIUS) and non-compliant users(LDAP)
- LDAP authentication followed by mandatory device posture scan
- Device posture check before and after AD authentication - Pre and Post-EPA as a factor
- Device Certificate as an EPA factor
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.
authadminpassword: As part of provisioning, Citrix creates an initial user called
authadminand 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
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.
- 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.
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.
Adaptive Authentication is a high availability (active-standby) service.
In this article
- Adaptive Authentication capabilities
- Points to note
- How to configure the Adaptive Authentication service
- Step 1: Provision Adaptive Authentication
- Step 2: Configure Adaptive Authentication policies
- Step 3: Enable Adaptive Authentication for Workspace
- Migrate your authentication method to Adaptive Authentication
- Edit an FQDN
- Advanced configuration options
- Set up connectivity to on-premises authentication servers using Azure VNet peering
- Other related configurations
- Config backup and restore
- Sample authentication configurations
- Shared security responsibilities
- Service quality