NetScaler nFactor Authentication

In case you hadn’t noticed, lots of web services have been changing how they do authentication lately…maybe you’ve heard of some of them:



…or Microsoft


What is really going on here? The forms are applying some intelligence based on who you are or what company you work for. For example, if you work for a company that uses federated authentication for Office 365, you will be redirected back to your company’s IdP. How does Microsoft do that? They take a look at your email domain when you type it in – using a policy or rule to filter based on the first ‘step’ or ‘factor’ of authentication.

Enter NetScaler nFactor Authentication

If you have a NetScaler that is running 11.0 or later (11.1 is recommended due to some additional enhancements) you have the ability to use NetScaler’s nFactor Authentication framework to achieve the same kind of things that you see above.

Do you want to prompt a user for a token code because they have higher permissions in the organization or have access to sensitive data without prompting everyone else? nFactor can do that.

Do you want to use certificate based authentication and token-based 2 factor authentication and SAML all on the same vServer? nFactor can do that.

Do you want your authentication form to be more responsive to users and help by providing better feedback and messaging in the form? nFactor can do that.

Even the new native OTP capability in NetScaler 12 is built with nFactor technology.

Some Notes and Terminology

First and foremost: nFactor is built on web technology – similar to how SAML web forms work. That means that each ‘factor’ is meant to be displayed in a web browser or frame – things that don’t natively support this may not work. The most common scenario here is Citrix Receiver – it does not (currently) support this type of authentication, but that does not mean that you cannot use nFactor authentication on a gateway vServer – it is possible, see this link for details.

Next, I hear many folks ask “how do I do xyz with nFactor”? Since nFactor is a framework, there are probably 47 different ways to do any one configuration, so I feel it is best to understand the nFactor framework and how to configure it, then figure out how to do xyz.

AAA vServer: The authentication virtual server is where the configuration starts

Policy Label: Think of this as a “container” for different factors or authentication steps

Login Schema: This is the xml file used to build the page that is viewed by the user – there are several built in schemas, and there is a LOT of customization possible. In later builds of NetScaler, a schema editor is built in allowing you to modify form fields, assistance text, etc. The default location for built-in schema files is /flash/nsconfig/loginschema/LoginSchema

(Advanced) Authentication Policy: These policies can be anything from traditional LDAP or RADIUS authentication policies (“legacy” policies) to special ‘no_auth’ policies that allow you to do some computation or manipulation of the authentication flow without involving the user

Next Factor: This is a pointer to a next ‘factor’ in the flow of authentication, this will be pointing to a ‘Policy Label’

NO_AUTHN: This is a special advanced authentication action meaning that we are not performing a traditional authentication, instead we are applying some expression against a previous set of credentials for example

noSchema: This is a special Login Schema that implies that there is no schema, or nothing is being displayed to the user. The purpose of noSchema is to allow a ‘processing factor’ to allow the NetScaler to do some work on a previous authentication step without showing anything to the user

Each of these items gets put into a “container” to build either a place for users to enter information or a place for the NetScaler to do some work on the string input by the user – like modify the domain name, or look at group membership, etc. It looks something like this (in a 1-to-1 format…there can be MANY expressions to make the flow get VERY complex):

Remember that both AAA vServers and Policy Labels are bind points for schemas, authentication policies, and pointers to the next factor.

Common nFactor Use Cases

  • Using a single vServer for both single and dual factor authentication using policy to determine if users should use dual factor
  • Configuring a domain drop down (or domain radio buttons) that look like they belong on the page and survive reboots without extra script configuration 
  • Provide users with helpful texts for authentication success\failures, or username format (For example: Enter username as ‘username@domain’)
  • Modifying usernames from sAMAccountName to UPN
  • Modifying domain of a negotiated internal username to switch from internal domain to public domain (Example: johnDoe@company.local to – useful for Office365 federation)

Several other scenarios are outlined in the eDocs here.

  • Getting two passwords up-front, pass-through in next factor. Read
  • Group extraction followed by certificate or LDAP authentication, based on group membership. Read
  • SAML followed by LDAP or certificate authentication, based on attributes extracted during SAML. Read
  • SAML in first factor, followed by group extraction, and then LDAP or certificate authentication, based on groups extracted. Read
  • Prefilling user name from certificate. Read
  • Certificate authentication followed by group extraction for 401 enabled traffic management virtual servers. Read
  • Username and 2 passwords with group extraction in third factor. Read
  • Certificate fallback to LDAP in same cascade; one virtual server for both certificate and LDAP authentication. Read
  • LDAP in first factor and WebAuth in second factor. Read
  • Domain drop down in first factor, then different policy evaluations based on group. Read

Getting Started

The AAA vServer is where the initial nFactor configuration is done by binding an advanced authentication policy and a login schema – even if you are deploying nFactor for NetScaler Gateway, the configuration is held by a AAA vServer and applied via an authentication policy. Also, as this uses the full Authentication Engine, NetScaler Enterprise is the required license to use nFactor authentication.

You need to determine the workflow for user authentication and the different scenarios you will be supporting. Then, determine the first thing that users are going to see when they are trying to login – for example, are you going to start with just a single field for username? Or maybe username and password, then prompt for a second factor? This first step will be applied to the vServer directly.

For this example, we are going to go through the vendor scenario – the idea is that all of the employees of the company will be authenticated against an internal identity database (Active Directory), but I also have some 3rd party vendors that I want to give access but I don’t want to manage their identity. In this workflow, here are the steps to be taken:

  1. User presented with logon page with username only
  2. Perform AD lookup to see if user exists (or is\is not member of a specific group, etc)
    1. If exists: User goes to next logon page with username and password fields, enters password (username is pre-populated from previous)
    2. If not exists: User is sent to 3rd party IdP for federated logon

Request Servers (Legacy Servers)

First, we’re going to create 2 LDAP actions – you may already have these configured, but if not, they are fairly basic with one exception: create one that has the authentication checkbox unchecked. 

The purpose of this kind of policy is to see if the user even exists in our directory.

Next, you also need to configure a SAML server – in this case, I am using OktaPreview. For instructions on setting up the SAML configuration on NetScaler to work with Okta, see this post. If users fail the initial user lookup (or are not in the specified group) they will be sent to Okta to login.

At this point, you should have 2 ldap server definitions and 1 SAML definition.

Advanced Authentication Policies

We will create 4 advanced authentication policies:

  1. A policy to lookup the user in the directory without authentication
  2. A policy to ensure that the user returned from the previous (#1) policy has a length greater than zero (user exists)
  3. A policy to authenticate the user
  4. A policy to forward the user for SAML authentication in the event the user from policy #2 does not exist

Advanced Policy #1:

Action Type: LDAP

Action: (LDAP Request Server created previously that is not authenticating)

Expression: true

Advanced Policy #2:

Action Type: NO_AUTHN


Advanced Policy #3:

Action Type: LDAP

Action: (LDAP Request Server created previously that is authenticating)

Expression: true

Advanced Policy #4:

Action Type: SAML

Action: (SAML Request Server created previously)


Login Schema Profiles

We will create 2 login schemas for this example: one that is a simple username only login, then one that contains a pre-populated username field and an empty password field. First we will create the username only schema – note: we will not need to set User Expression or Password Expression in these schemas.

Login Schema #1

Next is the schema that will show the user the password field after their user has been found in active directory:

Login Schema #2

Note: Be sure to ‘select’ the schema layout when you are using the editor before saving.

We will also be using a noschema policy, but there should already be one configured by default (LSCHEMA_INT)

Policy Labels

Think of a Policy Label as an authentication factor or an authentication container – the first of these containers being the AAA vServer. According to the workflow, the first thing we want to do is take the username and see if it exists in active directory using a non-auth LDAP server, all of which will be configured on the vServer directly. The next “factor” or container will be to check if the username that is returned is not null (without showing anything to the user). After that, if the user does exist, we will prompt for a password using the pre-filled username schema #2 created above. If the user does NOT exist, we will have the SAML server policy bound that will send the user to Okta for 3rd party authentication.

Policy Label #1

Login Schema: noSchema

Priority: 100

Advanced Policy: (Advanced Policy #2)

Next Factor: (Policy Label #2)

Policy Label #2

Login Schema: (Login Schema #2)

Priority: 100

Advanced Policy (Advanced Policy #3)

Next Factor: (None)

Authentication vServer

Next, we will configure the AAA vServer – if you are integrating this with NetScaler Gateway, you will simply need to create an Authentication Profile and bind it to the Gateway vServer (if that is the case, the AAA vServer can be non-addressable).

The first thing to do is make sure there are no basic authentication policies bound to the vServer – if there are, remove them. Next, we will bind the username only login schema created earlier. Next, we will bind the following advanced auth policies:

  1. Advanced Policy #1; Priority 100; GoToExpression NEXT; NextFactor: (Policy Label #1)
  2. Advanced Policy #4; Priority 110; GoToExpression NEXT; NextFactor: (None)


This may seem like a lot of configuration especially if you are used to the traditional configuration of authentication on the NetScaler: “Primary and Secondary”. But hopefully you can see that the nFactor authentication framework enables numerous workflows that were previously not possible.

2 thoughts on “NetScaler nFactor Authentication

Leave a Reply