Note: According to RFC6176 from Internet Engineering Task Force (ITEF), TLS servers must not support SSLv2. The NetScaler appliance does not support SSLv2 from release 12.1.

This article describes the following scenario:

1. First factor is configured for LDAP Authentication

2. Second Factor is configured for Web Authentication

These steps are described in detail in the following sections. The first section briefly introduces the entities that are encountered in this article, and in general for nFactor authentication. The next section pictographically demonstrates the flow. The following sections have example "LoginSchema" that can be used to realize the logon form, and the relevant configuration.

Entities used in nFactor

LoginSchema

Login Schema is an XML construct that is aimed at providing sufficient information to the UI tier so that it can generate user interface based on the information that is sent in this XML blob. Put another way, LoginSchema is a logical representation of logon form in XML medium.

It can be added as below:
add authentication loginSchema <name> -authenticationSchema <XML-Blob> -userExpression <Expression> ­-passwordExpression <Expression>

where authenticationSchema is a well-structured XML that defines the way login form is rendered. UserExpression is used to extract username from login attempt. Likewise passwordExpression is used to extract password.

Authentication Policylabel

Authentication Policy label is a collection of authentication policies for a particular factor. It is recommended that these are pseudo-homogenous policies, which means, the credentials received from user apply to all the policies in the cascade. However, there are exceptions to this when a fallback option is configured or feedback mechanism is intended.

Authentication policy labels constitute secondary/user-defined factors. With nFactor, there is no single "secondary" cascade. There could be "N" secondary factors based on configuration. There could be as many policy labels as desired and the number of factors for a given authentication is defined by the longest sequence of policylabels beginning with the virtual server cascade.

When we bind an authentication policy to authentication virtual server, we specify nextFactor, which represents a policylabel/factor that would be taken if the policy succeeds. Likewise, when policies are bound to policylabels, nextFactor specifies the next policylabel to continue if the policy succeeds.

It can be added as below:
add authentication policylabel <name> -loginSchema <loginSchemaName>
Where, loginSchemaName will be the login schema that we want to associate with this authentication factor.

We can bind authentication policies to this label.
bind authentication policylabel <name> -policy WebAuth –priority 10 –nextfactor <nextFactorLabelName>

Sequence Diagram

nFactor Flow Presentation

The setup can also be created through nFactor Visualizer present in ADC version 13.0 and above.




Description

1. User accesses the web site (<NetScaler Load Balancer FQDN>\WebAuthSite.html), a  request is sent to the NetScaler for the website.

2. As the Load Balancer is configured with authentication, it redirects user to authentication virtual server for authentication.

3. NetScaler responds with HTTP 302 with Location /logon/logonpoint/tmindex.html.

4. Client requests for /logon/logonpoint/tmindex.html.

5. NetScaler evaluates the Login schema (means to generate different authentication forms. More about login schema in the following section) settings and responds back to the client with the Authentication form.

   

6. User enters the user name, password and clicks on the Log on button to authenticate.

7. NetScaler constructs LDAP request and sends the request to the LDAP server for verification. Depending on the results from the LDAP server the NetScaler logic will perform appropriate action.

   1. If the LDAP authentication fails, user is sent an appropriate message that describes the reason along with original login form. 

      

   2. If the LDAP authentication succeeds, then the NetScaler will verify the Next Factor settings. For this use case second factor does not have schema (pass-through). Passthrough factor implies that NetScaler will not prompt user for credentials but continue with previously obtained credentials. In this case, those are the ones obtained from first factor. So, NetScaler will evaluate the second factor for authentication policies.

8. If the second factor authentication policy evaluates to true, NetScaler crafts the Web authentication request and sends the request to back end Web authentication server, and takes appropriate action depending upon the response from server.

   1. If the authentication succeed then the NetScaler will examine if any more Factors are defined. As in this case we have only configured second Factor, hence NetScaler completes authentication.

   2. If the authentication fails, then NetScaler will send authentication failure to the user along with original authentication page.

9. On successful authentication NetScaler sends HTTP 200K with Set-Cookie NSC_TMAS and NSC_TMAA to the client.

Login form that users see can be rendered by the following xml blob. Labels and other fields can be customized as highlighted. Following is the example used for this specific representation of logon form:
Note: You can download the XML file from this article's attachment.

<?xml version="1.0" encoding="UTF-8"?>
<AuthenticateResponse  xmlns="http://citrix.com/authentication/response/1" >
<Status >success </Status>
<Result >more-info</Result>
<StateContext/>
<AuthenticationRequirements>
<PostBack> /nf/auth/doAuthentication.do</PostBack >
<CancelPostBack>/Citrix/Authentication/ExplicitForms/CancelAuthenticate</CancelPostBack>
<CancelButtonText>Cancel</CancelButtonText>
<Requirements>
<Requirement><Credential><ID>login</ID><SaveID>ExplicitForms-Username</SaveID><Type>username</Type></Credential><Label><Text>Enter Login Name:</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><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></InitialValue><Constraint>.+</Constraint></Text></Input></Requirement>
<Requirement><Credential><Type>none</Type></Credential><Label><Text>Please submit LDAP Credntials to continue Login ...</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>
</AuthenticateResponse>

All the customizable portions of the logon form are highlighted. Administrators can modify these values to suit their needs.

Configuration Through Visualizer:

6. By clicking on add policy Add Policy for LDAP for the first factor


For more information on creating LDAP Authentication see, Configuring LDAP Authentication
 

7. By clicking on green + sign add the Second factor

9. Following steps 4 and 5 add LSCHEMA_INT for pass-through schema and Web Auth Policy as shown below: 




For more information on WebAuth Policy see, Web Authentication Policies

11. Select the nFactor Flow just created and bind it to a AAA Virtual Server by clicking on Bind to Authentication Server and the Create

1. Select the nFactor Flow and Click on Show Bindings
2. Select the Authentication VServer and Click Unbind

Policies for this use case

Traffic Management:
add lb vserver LB-NFactor SSL 10.217.217.240 443 -persistenceType NONE -cltTimeout 180 -AuthenticationHost ION63.xmdfa.nsi-test.com -Authentication ON -authnVsName auth-NFactor

Authentication Virtual Server:
add authentication vserver auth-NFactor SSL 10.217.217.251 443 -AuthenticationDomain xmdfa.nsi-test.com
bind authentication vserver auth-NFactor -policy LDAP-loginSchema-pol -priority 1 -gotoPriorityExpression END
bind authentication vserver auth-NFactor -policy LDAPXMDFA-AdvPolicy -priority 2 -nextFactor WebAuth-Pol-Label -gotoPriorityExpression NEXT

LDAP Policy:
add authentication ldapAction XMADDFAIP -serverIP 10.217.217.5 -serverPort 636 -ldapBase "dc=xmdfa,dc=nsi-test,dc=com" -ldapBindDn administrator@xmdfa.nsi-test.com -ldapBindDnPassword e16dca9ac052375bb87fa4dd41e62f9fc85d96e52c3ebb5a7e7227ffd1424e46 -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName cn -secType SSL -ssoNameAttribute sAMAccountName -passwdChange ENABLED -defaultAuthenticationGroup ch.etit.hedani.net_SSODomainSet -Attribute1 mail
add authentication Policy LDAP-XMDFA -rule true -action XMADDFAIP

Web Auth policy:
add authentication webAuthAction webAuthXMDFA -serverIP 10.217.217.5 -serverPort 80 -fullReqExpr q{"GET / HTTP/" + http.req.version.major + "." + http.req.version.minor.sub(1) + "\r\nAccept:*/*\r\nhost:nsi-dc1-2008.nsi-test.com\r\n" + "Authorization:" + "\"Basic \"+ (HTTP.REQ.USER.NAME.append(\":\").APPEND(http.req.user.passwd).B64ENCODE)\r\n\r\n"} -scheme http -successRule "http.res.status.eq(200)"
 add authentication webAuthPolicy WebAuthXMDA-pol1 -rule ns_true -action webAuthXMDFA
add authentication Policy WebAuth2-Advance -rule true -action webAuthXMDFA
add authentication policylabel WebAuthNoschema -loginSchema No-Schema-Passthrough
bind authentication policylabel WebAuth-Pol-Label -policyName WebAuth2-Advance -priority 2 -gotoPriorityExpression NEXT

The preceding configuration describes adding a Traffic Management virtual server for resource access, adding Authentication virtual server for securing Traffic Management virtual server, and relevant policies for this use-case. The portions highlighted in Yellow are to be replaced with appropriate authentication policies by the administrators. The GOTO Priority expression by default is NEXT, so that we fall down to the next policy if it fails.

Important ns.log messages

Jul 31 18:54:56 <local0.debug> 127.0.0.2 08/01/2015:01:54:56 GMT  0-PPE-2 : default SSLVPN Message 727 0 :  "core 2: ns_get_username_password: loginschema gleaned is LDAP-Auth "
Jul 31 18:54:56 <local0.debug> 127.0.0.2 08/01/2015:01:54:56 GMT  0-PPE-2 : default SSLVPN Message 728 0 :  "aaad_authenticate_req: copying policylabel name auth-NFactor to aaa info, type 33 for auth "
Jul 31 18:54:56 <local0.debug> 127.0.0.2 08/01/2015:01:54:56 GMT  0-PPE-2 : default AAATM Message 729 0 :  "copying next factor WebAuth-Pol-Label in aaa info for administrator "
Jul 31 18:54:56 <local0.debug> 127.0.0.2 08/01/2015:01:54:56 GMT  0-PPE-0 : default AAATM Message 716 0 :  "mp creating session on 0, pck 0, state 8"
Jul 31 18:55:56 <local0.debug> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLLOG SSL_HANDSHAKE_SUCCESS 730 0 :  SPCBId 667 - ClientIP 10.252.113.101 - ClientPort 56655 - VserverServiceIP 10.217.217.251 - VserverServicePort 443 - ClientVersion TLSv1.2 - CipherSuite "AES-256-CBC-SHA SSLv2 Non-Export 256-bit" - Session New
Jul 31 18:55:56 <local0.info> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLVPN Message 731 0 :  "LOGIN: CGI/LOGIN: Continuing auth for user administrator at factor WebAuth-Pol-Label with login schema WebAuth"
Jul 31 18:55:56 <local0.debug> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLVPN Message 732 0 :  "aaad_authenticate_req: copying policylabel name WebAuth-Pol-Label to aaa info, type 65 for auth "
Jul 31 18:55:56 <local0.debug> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default AAATM Message 733 0 :  "Authentication delegated to Packet engine for administrator, trying to find appropriate action with bitmask 1 "
Jul 31 18:55:56 <local0.debug> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default AAATM Message 734 0 :  "Authentication delegated to Packet engine for administrator, chosen action is webAuthXMDFA "
Jul 31 18:55:56 <local0.info> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLVPN Message 735 0 :  "WEBAUTH: AAAD delegated WebAuth to Packet Engine, beginning web authentication"
Jul 31 18:55:56 <local0.debug> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLVPN Message 736 0 :  "WEBAUTH: Primary webauth request being tried, action: webAuthXMDFA "
Jul 31 18:55:56 <local0.debug> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLVPN Message 737 0 :  "WEBAUTH: Successfully sent webauth request, GET / HTTP/1.0^M Accept:*/*^M host:nsi-dc1-2008.nsi-test.com^M Authorization:"Basic "+ (HTTP.REQ.USER.NAME.append(":").APPEND(http.req.user.passwd).B64ENCODE)^M ^M  "
Jul 31 18:55:56 <local0.info> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLVPN Message 738 0 :  "WEBAUTH: Response from server 0x5d9d90a: response type 401 header len 246 contentlen 1293 payload HTTP/1.1 401 Unauthorized^M Content-Type: text/html^M Server: Microsoft-IIS/8.5^M WWW-Authenticate: Basic realm="nsi-dc1-2008.nsi-test.com"^M X-Powered-By: ASP.NET^M Date: Sat, 01 Aug 2015 09:55:55 GMT^M Connection: keep-alive^M Content-Length: 1293^M ^M <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">^M <html xmlns="http://www.w3.org/1999/xhtml">^M <head>^M ^M <title>401 - Unauthorized: Access is denied due to invalid credentials.</title>^M <style type="text/css">^M <!--^M body{margin:0;font-size:.7em;font-family:Verdana, Arial, Helvetica, sans-serif;background:#EEEEEE;}^M fieldset{padding:0 15px 10px 15px;} ^M h1{font-size:2.4em;margin:0;color:#FFF;}^M h2{font-size:1.7em;margin:0;color:#CC0000;} ^M h3{font-si
Jul 31 18:55:56 <local0.debug> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLVPN Message 739 0 :  "WEBAUTH: Evaluating success rule for primary webauth action webAuthXMDFA "
Jul 31 18:55:56 <local0.debug> 127.0.0.2 08/01/2015:01:55:56 GMT  0-PPE-2 : default SSLVPN Message 741 0 :  "WEBAUTH: Primary webauth request being tried, action: webAuthXMDFA "