Product Documentation
ADC
14.1-Current Release 13.1
View PDF

Authentication virtual server

September 27, 2025
Contributed by: 
C

The traffic management virtual server (load balancing or content switching) redirects all authentication requests to the authentication virtual server. This virtual server processes the associated authentication policies and accordingly provides access to the application.

Note: You cannot bind traffic management policies to authentication, authorization, and auditing virtual servers.

Set up authentication virtual server

The steps involved in setting up an authentication virtual server are;

  1. Enable the authentication, authorization, and auditing feature.

    enable ns feature AAA
<!--NeedCopy-->

  2. Configure an authentication virtual server. It must be of type SSL and make sure to bind the SSL certificate-key pair to the virtual server.

    add authentication vserver <name> SSL <ipaddress> <port>

bind ssl certkey <auth-vserver-name> <certkey>
<!--NeedCopy-->

  3. Specify the FQDN of the domain for the authentication virtual server.

    set authentication vserver <name> -authenticationDomain <FQDN>
<!--NeedCopy-->

  4. Associate the authentication virtual server to the relevant traffic management virtual server.

    Points to Note:

    • The FQDN of the traffic management virtual server must be in the same domain as the FQDN of the authentication virtual server for the domain session cookie to function correctly. On the traffic management virtual server:
      • Enable authentication.
      • Specify the FQDN of the authentication virtual server as the authentication host of the traffic management virtual server.
      • [Optional] Specify the authentication domain on the traffic management virtual server.
      • If you do not configure the authentication domain, the appliance assigns an FQDN that consists of the FQDN of the authentication virtual server without the host name portion. For example, if the domain name of the authentication virtual server is tm.xyz.bar.com, the appliance assigns xyz.bar.com as the authentication domain.

        • For load balancing:

           set lb vserver <name> -authentication ON -authenticationhost <FQDN> [-authenticationdomain <authdomain>]
 <!--NeedCopy-->

          Note:

          When authentication is enabled, an unauthenticated POST request to the load balancing virtual server has a POST body limited to 4096 bytes. If the request exceeds this limit, the POST body is truncated to the allowed size after authentication. This truncation might cause the POST request to fail on the backend server. To increase the default size limit, contact Citrix Support.

        • For content switching:

           set cs vserver <name> <protocol> <IPAddress> <port>
 <!--NeedCopy-->
    • If you have to set a domain wide cookie for an authentication domain, you must enable authentication profile on a load balancing virtual server.

  5. Verify that both the virtual servers are UP and configured correctly.

    show authentication vserver <name>
<!--NeedCopy-->

Note:

To use the authentication virtual server in a non-default partition, run the following command in the shell:

nsapimgr_wr.sh -ys call=toggle_vpn_httpd_partition_support
<!--NeedCopy-->

When you enable the authentication virtual server in a non-default partition, NetScaler Gateway generates an info log in /var/log/ns.log. The following is an example of a sample info log file:

Jun 21 12:25:56 <local0.info> x.x.x.x  06/21/2023:11:25:56 GMT  0-PPE-0 : default SSLVPN Message 837 0 :  "vpn httpd partition support value is changed from 0 to 1"

Jun 21 12:25:56 <local0.info> x.x.x.x  06/21/2023:11:25:56 GMT  0-PPE-1 : default SSLVPN Message 1090 0 :  "vpn httpd partition support value is changed from 0 to 1"

Jun 21 12:25:56 <local0.info> x.x.x.x  06/21/2023:11:25:56 GMT  0-PPE-2 : default SSLVPN Message 676 0 :  "vpn httpd partition support value is changed from 0 to 1"
<!--NeedCopy-->

Run the same command again to disable the authentication virtual server in a non-default partition. This feature is disabled by default.

To set up an authentication virtual server by using the GUI

  1. Enable the authentication, authorization, and auditing feature.

    Navigate to System > Settings, click Configure Basic features, and enable Authentication, Authorization and Auditing.

  2. Configure the authentication virtual server.

    Navigate to Security > AAA - Application Traffic > Virtual Servers, and configure as required.

  3. Configure the traffic management virtual server for authentication.

    • For load balancing:

      Navigate to Traffic Management > Load Balancing > Virtual Servers, and configure the virtual server as required.

    • For content switching:

      Navigate to Traffic Management > Content Switching > Virtual Servers, and configure the virtual server as required.

    • Verify the authentication setup.

      Navigate to Security > AAA - Application Traffic > Virtual Servers, and check the details of the relevant authentication virtual server.

Configure the authentication virtual server

To configure authentication, authorization, and auditing, first configure an authentication virtual server to handle authentication traffic. Next, bind an SSL certificate-key pair to the virtual server to enable it to handle SSL connections. For additional information about configuring SSL and creating a certificate-key pair, see SSL certificates.

Configure an authentication virtual server by using the CLI

To configure an authentication virtual server and verify the configuration, at the command prompt type the following commands in the same order:

add authentication vserver <name> ssl <ipaddress>

show authentication vserver <name>

bind ssl certkey <certkeyName>

show authentication vserver <name>

set authentication vserver <name>

show authentication vserver <name>
<!--NeedCopy-->

Example:

add authentication vserver Auth-Vserver-2 SSL 10.102.29.77 443 Done

show authentication vserver Auth-Vserver-2 Auth-Vserver-2 (10.102.29.77:443) - SSL Type: CONTENT State: DOWN[Certkey not bound] Client Idle Timeout: 180 sec Down state flush: DISABLED Disable Primary Vserver On Down : DISABLED Authentication : ON Current AAA Users: 0 Done

bind ssl certkey Auth-Vserver-2 Auth-Cert-1 Done

show authentication vserver Auth-Vserver-2 Auth-Vserver-2 (10.102.29.77:443) - SSL Type: CONTENT State: UP Client Idle Timeout: 180 sec Down state flush: DISABLED Disable Primary Vserver On Down : DISABLED Authentication : ON Current AAA Users: 0 Done

set authentication vserver Auth-Vserver-2

show authentication vserver Auth-Vserver-2 Auth-Vserver-2 (10.102.29.77:443) - SSL Type: CONTENT State: DOWN[Certkey not bound] Client Idle Timeout: 180 sec Down state flush: DISABLED Disable Primary Vserver On Down : DISABLED Authentication : ON Current AAA Users: 0 Done
<!--NeedCopy-->

Note

The Authentication Domain parameter is deprecated. Use Authentication Profile for setting domain wide cookies.

Configure an authentication virtual server by using the GUI

  1. Navigate to Security > AAA - Application Traffic > Virtual Servers.

  2. In the details pane, do one of the following:

    • To create a new authentication virtual server, click Add.
    • To modify an existing authentication virtual server, select the virtual server, and then click Edit. The Configuration dialog opens with the Basic Settings area expanded.

  3. Specify values for the parameters as follows (asterisk indicates a required parameter):

    • Name*—name (Cannot be changed for a previously created virtual server)
    • IP Address Type*—IP address type of the authentication virtual server
    • IP Address*—IP address of the authentication virtual server
    • Port*—TCP port on which the virtual server accepts connections.
    • Failed login timeout—failedLoginTimeout (Seconds allowed before login fails, and user must start login process again.)
    • Max login attempts—maxLoginAttempts (Number of login attempts allowed before user is locked out)

    Note:

    The authentication virtual server uses only the SSL protocol and port 443, so those options are grayed out. Any options that are not mentioned can be ignored.

  4. Click Continue to display the Certificates area.

  5. In the Certificates area, configure any SSL certificates you want to use with this virtual server.

    • To configure a CA certificate, click the arrow on the right of CA Certificate to display the CA Cert Key dialog box, select the certificate you want to bind to this virtual server, and click Save.
    • To configure a server certificate, click the arrow on the right of Server Certificate, and follow the same process as for the CA certificate.
  6. Click Continue to display the Advanced Authentication Policies area.
  7. If you want to bind an advanced authentication policy to the virtual server, click the arrow on the right side of the line to display the Authentication Policy dialog box, choose the policy that you want to bind to the server, set the priority, and then click OK.
  8. Click Continue to display the Basic Authentication Policies area.
  9. If you want to create a basic authentication policy and bind it to the virtual server, click the plus sign to display the Policies dialog box, and follow the prompts to configure the policy and bind it to this virtual server.
  10. Click Continue to display the 401-Based Virtual Servers area.

  11. In the 401-Based Virtual Servers area, configure any load balancing or content switching virtual servers that you want to bind to this virtual server.

    • To bind a load balancing virtual server, click the arrow to the right of load balancing virtual server to display the Load Balancing Virtual Servers dialog box, and follow the prompts.
    • To bind a content switching virtual server, click the arrow to the right of content switching virtual server to display the Content Switching Virtual Servers dialog box, and follow the same process as to bind an LB virtual server.
  12. If you want to create or configure a group, in the Groups area click the arrow to display the Groups dialog box, and follow the prompts.
  13. Review your settings, and when you are finished, click Done. The dialog box closes. If you created a new authentication virtual server, it now appears in the Configuration window list.

Traffic management virtual server

After you have created and configured your authentication virtual server, you next create or configure a traffic management virtual server and associate your authentication virtual server with it. You can use either a load balancing or content switching virtual server for a traffic management virtual server.

Note:

The FQDN of the traffic management virtual server must be in the same domain as the FQDN of the authentication virtual server for the domain session cookie to function correctly.

You configure a traffic management virtual server for authentication, authorization, and auditing by enabling authentication and then assigning the FQDN of the authentication server to the traffic management virtual server. You can also configure the authentication domain on the traffic management virtual server currently. If you do not configure this option, the NetScaler appliance assigns the traffic management virtual server an FQDN that consists of the FQDN of the authentication virtual server without the host name portion. For example, if the domain name of the authentication virtual server is tm.xyz.bar.com, the appliance assigns xyz.bar.com. as the authentication domain.

To configure a traffic management virtual server by using the CLI

At the command prompt, type one of the following sets of commands:

set lb vserver <name> –authentication ON -authenticationhost <FQDN> [-authenticationdomain <authdomain>]
show lb vserver <name>
set cs vserver <name> –authentication ON -authenticationhost <FQDN> [-authenticationdomain <authdomain>]
show cs vserver <name>
<!--NeedCopy-->

Example:

set lb vserver vs-cont-sw -Authentication ON -AuthenticationHost mywiki.index.com Done

show lb vserver vs-cont-sw vs-cont-sw (0.0.0.0:0) - TCP Type: ADDRESS State: DOWN Last state change was at Wed Aug 19 10:03:15 2009 (+410 ms) Time since last state change: 5 days, 20:00:40.290 Effective State: DOWN Client Idle Timeout: 9000 sec Down state flush: ENABLED Disable Primary Vserver On Down : DISABLED No. of Bound Services : 0 (Total) 0 (Active) Configured Method: LEASTCONNECTION Mode: IP Persistence: NONE Connection Failover: DISABLED Authentication: ON Host: mywiki.index.com
Done
<!--NeedCopy-->

To configure a traffic management virtual server by using the GUI

  1. In the navigation pane, do one of the following.

    • Navigate to Traffic Management > Load Balancing > Virtual Servers.
    • Navigate to Traffic Management > Content Switching > Virtual Servers
    • In the details pane, select the virtual server on which you want to enable authentication, and then click Edit.
    • In the Domain text box, type the authentication domain.
    • In the Advanced menu on the right, select Authentication.

    • Choose either Form Based Authentication or 401 Based Authentication, and fill in the Authentication information.

      • For Form Based Authentication, enter the Authentication FQDN (the fully qualified domain name of the authentication server), the Authentication virtual server (the IP address of the authentication virtual server), and the Authentication Profile (the profile to use for authentication).
      • For 401 Based Authentication, enter the Authentication virtual server and the Authentication Profile only.
    • Click OK. A message appears in the status bar, stating that the virtual server has been configured successfully.

Simplified login protocol support for authentication, authorization, and auditing

The login protocol between authentication, authorization, and auditing traffic management virtual servers and authentication, authorization, and auditing virtual servers is simplified to use internal mechanisms as opposed to sending the encrypted data through query parameters. Using this feature, the replay of requests is prevented.

Configure DNS

For the domain session cookie used in the authentication process to function correctly, you must configure DNS to assign both the authentication and the traffic management virtual servers to FQDNs in the same domain. For information about how to the configure DNS address records, see Domain Name System.

Verify authentication virtual server

After you configure authentication and traffic management virtual servers and before you create user accounts, you must verify that both virtual servers are configured correctly and are in the UP state.

Configure a noAuth authentication by using the CLI

At the command prompt, type the following command:

show authentication vserver <name>
<!--NeedCopy-->

Example:

show authentication vserver Auth-Vserver-2
Auth-Vserver-2 (10.102.29.77:443) - SSL Type: CONTENT
State: UP
Client Idle Timeout: 180 sec
Down state flush: DISABLED
Disable Primary Vserver On Down : DISABLED
Authentication : ON
Current AAA Users: 0
Authentication Domain: myCompany.employee.com
Done
<!--NeedCopy-->

Configure a noAuth authentication by using the GUI

  1. Navigate to Security > NetScaler AAA - Application Traffic > Virtual Servers. Note: From NetScaler Gateway, navigate to NetScaler Gateway > Virtual Servers.
  2. Review the information in the AAA Virtual Servers pane to verify that your configuration is correct and your authentication virtual server is accepting traffic. You can select a specific virtual server to view detailed information in the details pane.
Authentication virtual server
September 27, 2025
Contributed by: 
C
September 27, 2025
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.