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: [email protected] to [email protected] – 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.

11 thoughts on “NetScaler nFactor Authentication”

  1. Hello Jake,

    Great article on nFactor! I have a question for you and hope you can help!

    I am looking to implement a NetScaler Unified Gateway with 2-factor authentication with minimal cost. The client needs a software- and a hardware OTP token as the second factor OTP token.

    To minimize CAPEX and OPEX I would like to use nFactor authentication feature of the NetScaler in combination with a software OTP token (for example Google Authenticator) and a hardware token.

    What I wasn’t able to find in the documentation is whether hardware OTP tokens are supported with the nFactor authentication feature and if that is the case, which one’s are.

    For example one of these hardware tokens:

    See also:

    Hope you can help!


    Kind regards,


  2. Hello Jake,

    Great article on nFactor! I have a question about it and hope you can help!

    I am looking to implement a NetScaler Unified Gateway with 2-factor authentication with minimal cost. The client needs a software- and a hardware OTP token as the second factor OTP token.

    To minimize CAPEX and OPEX I would like to use nFactor authentication feature of the NetScaler in combination with a software OTP token (for example Google Authenticator) and a hardware token. Hardware OTP token in specific use cases where use of a smartphone is not allowed.

    What I wasn’t able to find in the documentation is whether hardware OTP tokens are supported with the nFactor authentication feature and if that is the case, which one’s are.

    For example one of these hardware tokens:

    Hope you can help!


    Kind regards,


  3. Hi Damir,

    I believe there are 2 questions here – the first is if those HID ActiveID OTP tokens will work with nFactor. While I don’t have any experience with those specific tokens, if they support RADIUS (the most common method for the NetScaler communicating with other MFA appliances) or another protocol that the NetScaler supports, then they will absolutely work with nFactor. If you are also using the native NS OTP with say Google Authenticator, then you can us AD groups to determine which users should be using which MFA credential.

    As for if the HID tokens will work with OTP, it may be possible if they support RFC6238 and you are able to see the key of each token.

    Hope this helps!

  4. Jacob,

    Some nice information presented here.

    What we are looking for (in a similar vein) is only single factor but pass through, i.e.

    User goes to SAML SP who then redirects to our IDP, IDP generates the SAML response and logs on to the SP.
    We want the domain user on a domain machine to ‘pass through’ the IDP automatically and return to the SP.
    ie. can we use user certificate / radius or other method to bypass the login window?

    Regards and thanks


  5. Hey Jacob,

    I was looking to implement nFactor authentication to an existing Citrix Gateway. I was looking to hit a page where the users enter just the username. AD group extraction would take place and IF the users were a member of the security group, they would get username and PIN + RSA token box for login. If the users were NOT a member of the security group, they would get a standard LDAP (username/password) for login. I’ve got it set so far where I get the main ‘Enter username’, and the group extraction works providing a PIN + RSA login as well as the non Security Group members receiving just a username/password for login. The problem I have is that after I enter my credentials, I get looped back to the ‘enter username’ or the first page the users see prior to extraction. So I never get passed into StoreFront. I login to my Citrix Gateway where I have the AAA Authentication vServer Authentication profile bound.

    I think somewhere the ‘NEXT’ in one of the policy labels is what’s causing my problem but am not sure.

    • Hi Pete,

      This is very much a doable scenario with nFactor. If you have a non-auth LDAP bind for the group extraction, then you must also have an auth LDAP bind to process the password. Take a look at the aaad.debug stream to see what is happening, it may provide a clue.

      Also, depending on the exact scenario, you may need a no_auth PL to process credentials.

      If you have not already, take a look at the nFactor visualizer – it’s in 13.0 if you are running that build.


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.