nFactor authentication with NetScaler Unified Gateway

nFactor authentication with NetScaler provides a way to configure flexible, agile multi-factor authentication schemas based on factors such as who is connecting and from where users are connecting from or if users fail authentication. This allows NetScaler to provide authentication based on many different use cases and scenarios to provide secure access to backend applications and desktops.

nFactor is supported on NetScaler 11.0 build 62.x and onwards for Traffic Management use cases but 11.1 saw nFactor support added for NetScaler Gatway. Note that nFactor is not currently supported for Citrix Receiver client. With nFactor you can configure many numbers of authentication factors for users connecting based on location, corporate devices, non-corporate devices, employee status, group membership and so on. Take an example where users are connecting from non-corporate devices. You may like users to receive three factors of authentication. For corporate devices connecting in, let’s apply only two factors. If a device has a corporate certificate, extract the username from the certificate and only ask for the password. If the user device does not have a corporate certificate, ask for username, password and a token code.

Another example scenario could be around users from different domains connecting to NetScaler Gateway. Using a domains drop-down box, the selected domain can determine how many factors of authentication a user will now receive. Authentication portals can also be designed based again on the user so for example contractor users can be shown a different logon page than company employees.

Google reCaptcha with LDAP as next factor

nFactor supports local authentication, RADIUS, LDAP, OAuth, TACAS, Certificates, SAML, Negotiate, Web and EPA.

Note: EPA Authentication Policies are only available in NetScaler and above. EPA policies can only be bound to noschema Policy Labels. If you have non-EPA and EPA Authentication Policies attached to the same noschema Policy Label with expressions to filter what machines receive which Authentication Policy, EPA attempts to scan the machine regardless. You have to separate EPA authentication policies in to their own noschema Policy Labels.

Note: If creating an EPA action via the NetScaler GUI, the expression generated is wrong and does not work. The expression should be the following: sys.client_expr(“”)
– This will be fixed in 12.0.51.x.

What do you need to get nFactor working?

  • An AAA vServer (NetScaler Enterprise or Platinum license supports AAA).
  • Authentication Profile – The Authentication Profile bound to a NetScaler Gateway vServer.
  • Login Schema – These are made up of XML files. These files are what makes up the GUI display to users logging on. It is possible to present multiple GUI logon screens to users using a multi-factor approach. A number of these files are located in /nsconfig/loginschema/LoginSchema by default. Additional files can be downloaded from Citrix or created by yourself. Citrix recommend you place Login Schemas you have created in /nsconfig/loginschema/. Login Schema files can be backed up by taking a Full NetScaler backup.
  • Advanced Authentication Policies – Advanced Authentication Policies are composed of policy expressions and actions. An action can be an LDAP server, RADIUS, Certificate etc. This means that if the policy expression i.e. true is matched, the action is imposed on a user. For simplicity, we could bind an Advanced Authentication Policy which has the action of LDAP to an AAA vServer and this basically would present the connecting user (if expression is matched) with an LDAP authentication factor. nFactor can only use Advanced Authentication Policies and not Basic.
  • Basic Authentication Policies – Also composed of policy expressions and actions such as LDAP, Certificate or RADIUS etc. These Basic Policies contain server/profile/action entries that are normally associated with an Advanced Authentication Policy for nFactor use. It is not a requirement to actually create a Basic Policy (the policy section). Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> LDAP -> Servers -> Add as an example of creating an LDAP server entry, which is then used within Advanced Authentication Policies for nFactor.
  • Policy Labels – Treat these as the secondary/user-defined factors of authentication. You can have any amount of Policy Labels/secondary factors of authentication. An Advanced Authentication Policy will link to a Policy Label which defines the next factor of authentication. Policy Labels are associated with a Login Schema. Multiple Authentication Policies can be bound to a Policy Label, and priorities associated.

Note on Login Schemas – There is a bug where no schema files exist in NSv11.1 build 47.14. This seems to be resolved in build 48.10. If you do not have schema files you can manually copy them from a working NetScaler version or download schema files from Citrix. Login Schema files can be modified, take a copy of an existing schema file and place the file in the /nsconfig/loginschema/ directory and edit using a basic text editor. Citrix recommend using this directory to store modified login schema files so that changes are preserved even after reboots.

Another option is to modify the file within the NetScaler GUI by selecting a schema file and clicking on Edit.


Make required modifications and click Save.

Sample Scenario

  1. Users with a corporate user certificate are only asked for a password. The user’s username is extracted from the certificate.
    1. If user does not have a certificate, user is asked for username.
    2. User presents username, group extraction is performed.
  2. If users are in Azure Multi-Factor security group, user is presented with password only box, then Azure MFA is used as second factor.
    1. If user is not in Azure Multi-Factor security group, user is presented with RADIUS login schema, asking for password and token code. Username is prefilled from previous factor.

This post assumes you already have NetScaler Unified Gateway configured.

To get started create an AAA vServer. Navigate to Security -> AAA -> Application Traffic -> Virtual Servers -> Add. Set the address as Non Addressable.

Bind a certificate to the AAA vServer. It does not matter which certificate you use.

Create an Authentication Profile and bind the AAA vServer you just created to this new profile. Specify any Authentication Host name of your choice.

Edit the Unified Gateway vServer and under Authentication Profile choose the profile you have just created. Make sure no other authentication policies are attached to Unified Gateway. All authentication policies going forward will be configured on the AAA vServer.

If you browse to the NetScaler Unified Gateway URL you will likely get a Cannot complete your request message without any further configuration.

To fix, navigate to Traffic Management -> Content Switching -> Policies and edit the existing CSW policy.


Append || HTTP.REQ.URL.CONTAINS(“nf/auth”) to the expression. Click OK.


The first factor of authentication is client certificates, so we need to create an LDAP server that accepts User Principal Names as a logon username attribute. This is because the username is extracted from the certificate in UPN format. Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> LDAP -> Servers -> Add.

Configure each field as you normally would. Using a load balanced address for LDAP is recommended. Under Server Logon Name Attribute specify userPrincipalName.

Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> Cert -> Profiles -> Add.

Check Two Factor and under User Name Field make sure SubjectAltName:PrincipalName is selected.

You have to create Advanced Authentication Policies for both the CERT and LDAP actions you have just created. The Authentication Policies are then attached to the AAA vServer. Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Advanced Policies -> Authentication Policies -> Add.

For LDAP, choose the LDAP action you have just created. With an expression of true, click Create.

Also for CERT, choose the certificate action, use an expression of true and click Create.

To extract the username from a client certificate you can use a Login Schema. Mentioned at the beginning, Login Schemas are XML files which control the look and feel for each factor. Citrix have created XML schemas for many use cases including certificate username extraction. I have copied the schemas I need to separate files and made some slight adjustments. The certificate username extraction XML file I am using is pasted below. The schema is called CertExtract.xml.

Username Certificate Extraction XML code:


<?xml version=”1.0″ encoding=”UTF-8″?>

<AuthenticateResponse xmlns=”″>



<StateContext />



<Requirements><Requirement><Credential><ID>login</ID><SaveID>ExplicitForms-Username</SaveID><Type>username</Type></Credential><Label><Text>Username</Text><Type>plain</Type></Label><Input><AssistiveText>Please supply either domain\username or user@fully.qualified.domain</AssistiveText><Text><Secret>false</Secret><ReadOnly>true</ReadOnly><InitialValue>${HTTP.REQ.USER.NAME}</InitialValue><Constraint>.+</Constraint></Text></Input></Requirement><Requirement><Credential><ID>passwd</ID><SaveID>ExplicitForms-Password</SaveID><Type>password</Type></Credential><Label><Text>Password:</Text><Type>plain</Type></Label><Input><Text><Secret>true</Secret><ReadOnly>false</ReadOnly><InitialValue/><Constraint>.+</Constraint></Text></Input></Requirement>

<Requirement><Credential><Type>none</Type></Credential><Label><Text>Please enter your password</Text><Type>confirmation</Type></Label><Input /></Requirement>

<Requirement><Credential><ID>saveCredentials</ID><Type>savecredentials</Type></Credential><Label><Text>Remember my password</Text><Type>plain</Type></Label><Input><CheckBox>

<InitialValue>false</InitialValue></CheckBox></Input></Requirement><Requirement><Credential><ID>loginBtn</ID><Type>none</Type></Credential><Label><Type>none</Type></Label><Input><Button>Log On</Button></Input></Requirement></Requirements></AuthenticationRequirements>


Next bind the XML file to a Login Schema. Navigate to Security -> AAA – Application Traffic -> Login Schema -> Profiles -> Add.

Enter a name and then click the edit/pencil icon.

Select CertExtract.xml. You will be shown a preview of the XML Schema file and how it looks. Using the Edit button you can change some text labels, otherwise click Select.

Click Create.

The Login Schema is attached to a Policy Label. Policy Labels define which XML Login Schema is presented to the user and what types of authentication factors will be used to challenge the authenticating user. You can also link Policy Labels to additional Policy Labels for multiple factored levels of authentication which you will see later. For now, we have to bind the certificate extraction Login Schema and LDAP action to a Policy Label. Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Advanced Policies -> Authentication Policy Labels -> Add.

Choose an appropriate name and under Login Schema select the certificate extraction Login Schema you just created. Click Continue.

Under Policy Binding click Click to select.

Choose the UPN LDAP Authentication Policy. Click Select.

Set Goto Expression to END. This simply means that if LDAP authentication fails, no other factor is considered. We aren’t using any additional factor anyhow so it doesn’t really matter. Click Bind.

The Authentication Policy Label shows as below. Users who connect are prompted for a certificate, if they successfully present one to NetScaler, the username is extracted and inserted in to the Cert-UserNameExtract-LoginSchemaProfile. LDAP is used as the second factor. At this stage we need to bind the certificate authentication policy and next-factor Policy Label to our AAA vServer.

Navigate and edit your AAA vServer. Under Advanced Authentication Policies click No Authentication Policy.

Click Click to select.

Choose the certificate action.

Under Select Next Factor click Click to select.

Choose the Policy Label you just created for username extraction.

Keep Goto Expression as NEXT. Click Bind.

Click Done.

For client certificate authentication to work, we need to tell NetScaler to prompt for a certificate during the server & client SSL handshake. Navigate and edit your Content Switching vServer and click edit on SSL Parameters.

Check Client Authentication setting it to Optional. Optional allows non-corporate devices to fail certificate checking and receive the additional factors. Click OK.

The same must match on your Unified Gateway vServer. Set Client Authentication to Optional.

Bind your internal root CA certificate to the Content Switching Virtual Server. The NetScaler needs to be able to trust and verify the certificates being presented by your client. The user certificate must be scoped for Client Authentication and must include a private key. The Subject Alternate Name must
match the user’s UPN.

Now upon browsing to the Unified Gateway URL, providing you have an appropriate user certificate, you are prompted to select one.

If the certificate is valid the username is extracted from the certificate and you are only asked for a password.

Enter the password and you are authenticated to NetScaler Unified Gateway.

You can also view the Policy Labels from NetScaler and notice the hit counter has increased. This informs you that the Policy Label including it’s authentication policies and Login Schema were used to authenticate this user account.

For those users who fail certificate authentication, we want to present them either with LDAP and Azure Multi-Factor Authentication or LDAP and RADIUS based on group membership. Firstly create an MFA LDAP action. For information on Azure MFA and how it integrates with NetScaler see Change the time out to a value that gives users time to complete the second factor phone prompt.

Create another LDAP server, this is simply for sAMAccountName attributes and will be used alongside RADIUS.

A final LDAP server should be created with Authetication unticked. This server will be used for Group Extraction purposes only. Group Extraction will be used to determine if the user is presented with

You will end up with four LDAP servers in total.

  • LDAP-UserGroupExtraction – Used for Group Extraction only and accepts only a username.
  • LDAP-SAN – Used with RADIUS and accepts the sAMAccountName logon attribute.
  • LDAP-MFA – Used with Azure MFA, pointing LDAP requests to an internal MFA server.
  • LDAP-UPN – Used with certificate username extraction and accepts the userPrincipalName logon attribute.

Create Authentication Policies for each LDAP server you created.

UsernameOnly.xml schema will be used to determine who the user is. When a user browses to NetScaler Gateway and fails certificate authentication, they are presented with a username only Login Schema. Once they enter their username, group extraction is performed and next factor is LDAP/MFA or LDAP/RADIUS.

Username Only XML code:


<?xml version=”1.0″ encoding=”UTF-8″?>

<AuthenticateResponse xmlns=”″>









<Requirement><Credential><ID>login</ID><SaveID>ExplicitForms-Username</SaveID><Type>username</Type></Credential><Label><Text>Username</Text><Type>plain</Type></Label><Input><AssistiveText>Please supply either username as saamaccountname</AssistiveText><Text><Secret>false</Secret><ReadOnly>false</ReadOnly><InitialValue></InitialValue><Constraint>.+</Constraint></Text></Input></Requirement>

<Requirement><Credential><Type>none</Type></Credential><Label><Text> Please enter your username</Text><Type>confirmation</Type></Label><Input /></Requirement>

<Requirement><Credential><ID>saveCredentials</ID><Type>savecredentials</Type></Credential><Label><Text>Remember my password</Text><Type>plain</Type></Label><Input><CheckBox><InitialValue>false</InitialValue></CheckBox></Input></Requirement>

<Requirement><Credential><ID>loginBtn</ID><Type>none</Type></Credential><Label><Type>none</Type></Label><Input><Button>Log On</Button></Input></Requirement>




Next navigate to Security -> AAA – Application Traffic -> Login Schema -> Profiles -> Add.

Choose the UsernameOnly.xml Login Schema. Click Select -> Create.

Click Policies tab -> Add.

Specify a name, choose the username only Login Schema you just created. Use an expression of true. Click Create.

Navigate to and edit your AAA vServer. Under Login Schemas click No Login Schema.

Choose the username only Login Schema. Click Select.

Click Done. Now when users fail certificate authentication, they receive the username only Login Schema.

We need to create more Login Schemas. A PasswordOnly.xml Login Schema is used to extract the username from the first username only Login Schema and then ask the user for a password. The entered password is sent to the MFA LDAP server, which contacts Azure and prompts the user to approve the login on their mobile phone as the second factor.

Password Only XML code:

A RADIUS Login Schema is also required for users that are required to authenticate using RADIUS. The username field will be pre-filled with the username obtained from the first Login Schema (username only schema). 



<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>

<AuthenticateResponse xmlns=”″>











<Label><Text>Please log on</Text><Type>heading</Type></Label>




















<Label><Text>Remember my credentials</Text><Type>plain</Type></Label>











For the RADIUS Login Schema, enter number 1 inside the Password Credential Index box. This will allow the LDAP password to be presented to StoreFront for SSO and prevent the RADIUS password from being used. Click OK.

Create a noschema Login Schema. This Login Schema is used after Group Extraction. So, the user is instead directed to the next Policy Label which contains the correct Login Schema based on the users group membership (RADIUS Login Schema or Password Only Login Schema for LDAP/MFA).

In total you should have 6 Login Schema profiles.

As mentioned, the RADIUS Login Schema has a password credential index of 1. Now you need to create a Traffic Policy to ensure this password is used to authenticate with StoreFront. Navigate to NetScaler Gateway -> Policies -> Traffic Policies, Profiles and Form SSO Profiles -> Traffic Profiles -> Add.

Enter a name. In the SSO Password Expression field enter http.REQ.USER.ATTRIBUTE(1). Click Create.

Click on the Traffic Policies tab -> Add.
Enter a name and expression of ns_true. Choose the single profile you just created. Click Create.

Edit the Unified Gateway vServer, click on the + sign beside Policies.

Choose Traffic and Request. Click Continue.

Select the Traffic Policy. Click Bind.

Now that the Traffic Policy is attached to Unified Gateway, click Done.


Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Basic Policies -> RADIUS -> Servers -> Add.



Enter your RADIUS server details. Click Create.

Create an Authentication Policy for RADIUS.

Choose the RADIUS action you just created with an expression of true.

Create another Authentication Policy for RADIUS with Action Type set to NO_AUTHN. This means authentication will not be performed and instead users will reach the next factor. Use an expression of true.

Create another NO_AUTHN Authentication Policy for LDAP. Use an expression of HTTP.REQ.USER.IS_MEMBER_OF(“MFA Users”). This policy will be evaluated only if the connecting user is a member of the MFA Users group in Active Directory.

In total you will have 8 Authentication Policies.

To finish we need to create some more Policy Labels. Navigate to Security -> AAA – Application Traffic -> Policies -> Authentication -> Advanced Policies -> Authentication Policy Labels -> Add.

Create a Policy Label for Password Only. Choose the Password Only Login Schema. Click Continue.

Under Select Policy click Click to select.

Select the MFA LDAP policy.

Set the Goto Expression to END. Click Bind.

The Password Only Policy Label should look like below. Your username is asked for first, group extraction is performed, if you are part of the MFA Users group you receive the PasswordOnly-MFA-PolicyLabel which challenges you with LDAP and Azure MFA.

Create another Policy Label for RADIUS using the noschema Login Schema. Click Continue.

Bind the RADIUS policy to this Policy Label with a Goto Expression of END.

Create a second RADIUS Policy Label only this time using the RADIUS Username/Password/Passcode Login Schema.

Bind the sAMAccountName LDAP policy to this Policy Label with a Goto Expression of NEXT. For Next Factor, choose the RADIUS noschema Policy Label. This Policy Label contains the RADIUS server action.

Create a Policy Label using the noschema Login Schema. This Policy Label will be used to determine which factors of authentication users will receive based on group membership.

Bind the LDAP-noauthn-Policy to the Policy Label with next factor as PasswordOnly-MFA-PolicyLabel.

Bind the RADIUS-noauthnPolicy to the Policy Label with next factor as RADIUS-PolicyLabel. A higher priority will be used here so that LDAP-noauth-Policy is evaluated first.

We will specify this Policy Label as the next factor to username LDAP group extraction. After username group extraction is performed, the noschema-PolicyLabel Policy Label is evaluated. noauthn policies simply are there to determine if the connecting user based on their group receives Password Only or RADIUS Policy Labels for next factor. If Password Only, that Policy Label presents the Password Only Login Schema and an LDAP policy which authenticates the user with Active Directory and Azure MFA. If user is not a member of the MFA group, they receive the RADIUS Policy Label which asks firstly for LDAP credentials, then links to another Policy Label (using noschema) which asks for the RADIUS token code.

Navigate to your AAA vServer and edit the Advanced Authentication Policies. Click Add Binding.

Add the LDAP-GroupExtraction-Policy Authentication Policy with next factor as noschema-PolicyLabel. You are now ready to test the different authentication schemas.

Watching it all work

Corporate machine has a user certificate, connect to Unified Gateway URL. Username is extracted from certificate. User asked to enter password.

Authentication is successful.

Delete the user certificate.

Add user account to the MFA Users group.

Certificate authentication fails so I am presented with the username only Login Schema. Once my username is entered, group extraction is performed.

NetScaler detects I’m in the MFA Users group so the Password Only Login Schema is presented. Entering my username will authenticate myself with LDAP and then Azure MFA.

Phone receives a push-notification from Authenticator app asking me to approve sign-in.

Authentication is successful.

Now I am removing my user account from the MFA Users group.

As normal, certificate authentication fails and I am asked for my username.

Group Extraction this time determines that I am not an MFA User so presents me with the RADIUS Login Schema.


Leave a Reply

Your email address will not be published. Required fields are marked *