This article provides information about Delegated Forms Authentication for RSA adaptive authentication on NetScaler Gateway.

Contents

This article is divided into the following sections:

• Acronyms

• DFA Supported Components Versions

• Prerequisites 

• Caveats and Limitation

• Introduction

• DFA Protocol Flow

• DFA Configuration on NetScaler and StoreFront 

• Troubleshooting and Debugging

Acronyms

DFA Supported Components Versions

Prerequisites

The following are the prerequisites:

• RSA Authentication Adapter server is configured according to the requirements.

• RSA StoreFront Connector is configured according to the requirements and functions as expected.

• RSA StoreFront Bridge is installed on the StoreFront server and required configuration changes are performed to enable RBA authentication on the StoreFront site.

Caveats and Limitations

The following are the caveats and limitations:

• Cascading authentication is not supported in conjugation with DFA authentication policy.

• Pre/Post EPA is not supported in conjugation with DFA authentication.

• DFA authentication is supported as primary authentication only.

Introduction

Delegated forms authentication delegates the authentication to any external authentication server, provided it is supported by Citrix Delegated forms server. For example, Risk Based Authentication solution provided by RSA AA.

Risk Based Authentication provides a means of determining the information required from a user and their endpoint device depending on the security posture or fingerprint of the device. When the device first contacts the authentication service, evidence from the device about its characteristics (perhaps its location) is passed to the service, along with user credentials. This information is then used to determine whether the user is authentic, or whether additional information needs to be elicited from the user to confirm their identity.

Note: The preceding diagram depicts simple deployments. You can deploy as per your requirements.

DFA Protocol Flow

The following steps are DFA protocol flow depicting the preceding diagram:

1. To start DFA protocol, the clients have to send specific request. For instance, Secure Hub will send GET /cgi/authenticationrequirements.do.

2. At that point, NetScaler Gateway verifies for the presence of DFA policy. After such configuration is obtained, NetScaler starts communicating to the DFA server. If no such configuration is obtained, NetScaler redirects user to index.html. 
   To begin DFA protocol NetScaler Gateway sends request for ServerURL (For example, http://<DFA-FQDN>/Citrix/Authentication/dfaserver/start) configured and adds headers X-Citrix-ClientAddress and X-Citrix-KeyExchange with encryption parameters to establish the Citrix PKS encrypted channel.

3. The StoreFront (DFA Server) verifies the encryption parameters presented by NetScaler in the initial request. On successful verification, it establishes context for encryption and responds with XML blob containing the authentication related fields, which are relayed to the DFA client by NetScaler Gateway. Along with this response, StoreFront server also sends its own encryption parameters. NetScaler Gateway uses these parameters along with its own parameters sent earlier to arrive at the same encryption context that is computed at StoreFront server.

4. User enters the credentials and submits them to NetScaler Gateway. It uses the previously computed encryption context to encrypt the critical data when relaying it to the StoreFront (DFA server).

5. DFA server verifies user credentials. After successful verification, it creates a new request and sends the request to RSA StoreFront connector/RSA AA Server. In case of failure, the DFA server responds with appropriate status.

6. RSA AA verifies the user. If user is already registered, the risk engine responds based upon risk analysis (for more information refer to RSA AA documentation). If the user is unregistered RSA AA server starts user registration process, and continues the authentication process.

7. Registered user is presented with challenges. User selects the option from the displayed challenges and posts the selection to the RSA Server.

8. RSA AA Server responds to the request with appropriate challenge data (for example, Question/SMS/Phone/Email) as configured at RSA AA Server. User responds to the challenge. RSA AA server validates the challenge, and responds with success or failure. 
   DFA server modifies the RSA AA response, adds relevant elements like username, password, results and access mode. These are extracted by NetScaler to be used for Single Sign-On. NetScaler Gateway selects an access mode.

DFA Configuration on NetScaler and StoreFront

Configuration Checklist

This section explains how the secret (or passphrase) needs to be configured in NetScaler and StoreFront’s context. Before you configure them, take extreme care about the following parameters:

• Client id

  • It can be the FQDN of the NetScaler Gateway server that is, netscaler.server.com.
  • It does not necessarily have to be the FQDN (it is a recommendation).
  • It is vital that it is in lowercase and identical to both NetScaler and StoreFront.

• Passphrase/Secret

  • Has to be identical to both NetScaler and StoreFront.

• Server URL

  • For StoreFront 2.6 and 3.0, the URL is always in the format of  http(s)://[your StoreFront fqdn]/Citrix/Authentication/dfaServer/start.
  • For Storefront 3.5 and above, the URL is in the format of http(s)://[your StoreFront FQDN]/Citrix/DelegatedForms/Default/dfaServer/start.
  • Note that the StoreFront URL is case sensitive.
  • If StoreFront is using HTTPS, ensure that you have StoreFront’s server certificate's issuer as trusted CA on NetScaler.

DFA Configuration on StoreFront

1. Install DFA Feature.
   DFA feature is not installed by default. It must be installed through PowerShell console.

   PS C:\Users\administrator.PTD.000> cd 'C:\Program Files\Citrix\Receiver StoreFront\Scripts' PS C:\Program Files\Citrix\Receiver StoreFront\Scripts> & .\ImportModules.ps1 Adding snapins Importing modules Loading 'C:\Program Files\Citrix\Receiver StoreFront\\Admin\Citrix.DeliveryServices.ConfigurationProvider.dll' Loading 'C:\Program Files\Citrix\Receiver StoreFront\\Admin\Citrix.DeliveryServices.ConfigurationProvider.dll' PS C:\Program Files\Citrix\Receiver StoreFront\Scripts> Install-DSDFAServer Id : bf694fbc-ae0a-4d56-8749-c945559e897a ClassType : e1eb3668-9c1c-4ad8-bbae-c08b2682c1bc FrameworkController : Citrix.DeliveryServices.Framework.FileBased.FrameworkController ParentInstance : 8dd182c7-f970-466c-ad4c-27a5980f716c RootInstance : 5d0cdc75-1dee-4df7-8069-7375d79634b3 TenantId : 860e9401-39c8-4f2c-928d-34251102b840 Data : {} ReadOnlyData : {[Name, DelegatedFormsServer], [Cmdlet, Add-DSWebFeature], [Snapin, Citrix.DeliverySer vices.Web.Commands], [Tenant, 860e9401-39c8-4f2c-928d-34251102b840]} ParameterData : {[FeatureClassId, e1eb3668-9c1c-4ad8-bbae-c08b2682c1bc], [ParentInstanceId, 8dd182c7-f 970-466c-ad4c-27a5980f716c], [TenantId, 860e9401-39c8-4f2c-928d-34251102b840]} AdditionalInstanceDependencies : {b1e48ef0-b9e5-4697-af9b-0910062aa2a3} IsDeployed : True FeatureClass : Citrix.DeliveryServices.Framework.Feature.FeatureClass

2. Add Citrix Trusted Client.
   Configure the share secret key (passphrase) between StoreFront and NetScaler. You must have identical passphrase and client id as per what is configured on NetScaler (see section, DFA Configuration on NetScaler).

   PS C:\Program Files\Citrix\Receiver StoreFront\Scripts> Add-DSCitrixPSKTrustedClient -clientId NetScaler .fqdn.com -passphrase secret

3. Set DFA conversation factory.
   Route all the traffic to custom form (for example, RSA StoreFront Bridge). Currently, the only way to verify the conversation factory is by examining the content of web.config file under C:\inetpub\wwwroot\Citrix\Authentication folder.
   Look for ‘ConversationFactory’ and you should see something similar to the following:

   <RSABridge connectorURL=""> <routeTable order="1000"> <routes> <route name="StartRSABridgeAuthentication" url="RSA-Bridge-Forms/Start"> <defaults> <add param="controller" value="ExplicitFormsAuthentication" /> <add param="action" value="AuthenticateStart" /> <add param="postbackAction" value="Authenticate" /> <add param="cancelAction" value="CancelAuthenticate" /> <add param="conversationFactory" value="" /> <add param="changePasswordAction" value="StartChangePassword" /> <add param="changePasswordController" value="ChangePassword" /> <add param="protocol" value="CustomForms" /> </defaults> </route>

   From the PowerShell, set the DFA conversation factory to ‘RSABridgeAuthentication’:

   PS C:\Program Files\Citrix\Receiver StoreFront\Scripts> Set-DSDFAProperty -ConversationFactory RSABridgeAuthentication

DFA Configuration on NetScaler

Create DFA Action from Command Line

You will have to configure a DFA action through SSH:

StoreFront 2.6 and StoreFront 3.0

add dfaaction [dfa action name] –clientID [client id] –passPhrase [passphrase] –serverURL [url to StoreFront DFA]
Example:
> add dfaaction sfdfa_rsa_sample_action -clientID NetScaler .fqdn.com -passPhrase secret –serverURL http://sfdfa.citrix.lab/Citrix/Authentication/dfaServer/start

StoreFront 3.5 and above

> add dfaaction sfdfa_rsa_sample_action -clientID NetScaler .fqdn.com -passPhrase secret –serverURL http://sfdfa.citrix.lab/Citrix/DelegatedForms/Default/dfaServer/start

If you created this successfully, you will see the following (example shown is StoreFront 2.6, 3.5 will have a different URL) :

> show dfaaction sfdfa_rsa_sample_action
1)      Name: sfdfa_rsa_sample_action
        ClientID: NetScaler .fqdn.com
        ServerURL: http://sfdfa.citrix.lab/Citrix/Authentication/dfaServer/start
        Success: 0
        Failures: 0
Done

Notes:

• Client id and passphrase have to match the ones configured in StoreFront. They are case sensitive.

• Server URL

  • For StoreFront 2.6 and 3.0, the URL is always in the format of  http(s)://[your StoreFront fqdn]/Citrix/Authentication/dfaServer/start.
  • For Storefront 3.5 and above, the URL is in the format of http(s)://[your StoreFront FQDN]/Citrix/DelegatedForms/Default/dfaServer/start.
  • Note that the StoreFront URL is case sensitive.
  • If the server URL is HTTPS, ensure that you have the issuer of the StoreFront’s server certificate to be installed as trusted root CA on NetScaler .
  • Recommended deployment is HTTPS. However, you can start with HTTP for initial testing.
  • Ensure that the DNS is configured on the NetScaler Gateway and resolution works as expected.
  • Server URL should be reachable by NetScaler Gateway. The easiest way to test this is through the following:

    curl <server url> curl http://sfdfa.citrix.lab

Create DFA Action from GUI

Alternatively, you can also use the NetScaler web console:

Create DFA Policy from Command Line

Create a DFA policy and bind the action to it:

add dfaPolicy [dfa policy name] –rule [how the policy should be matched] –action [action to execute]
Example:
> add dfaPolicy sfdfa_rsa_sample_policy -rule ns_true -action sfdfa_rsa_sample_action

After successfully creating it, you will see the following:

> show dfaPolicy sfdfa_rsa_sample_policy
1)      Name: sfdfa_rsa_sample_policy     Rule: ns_true
        Request action: dfa_rsa_sample_action
Done

Create DFA Policy from GUI

Alternatively, you can also use the NetScaler web console:

Bind with a VPN virtual server from Command Line

Bind it with a VPN virtual server:

bind vpn vserver [dfa vserver name] -policy [dfa policy]
 Example:
> bind vpn vserver sfdfa_vserver -policy sfdfa_rsa_sample_policy

If it is successful, you will see the following:

> show vpn vserver sfdfa_vserver
        dfa_vserver (10.x.x.x.x:443) - SSL    Type: CONTENT
        State: UP  Nodegroup: ???
        Down state flush: ENABLED
        Disable Primary Vserver On Down : DISABLED
        Appflow logging: DISABLED
        Authentication : ON
        Device Certificate Check: OFF
        Advanced EPA: OFF
        CGInfra Homepage Redirect : ENABLED
        Current AAA Users: 0
        Icaonlylicense : OFF    IcaProxySessionMigration : OFF
        DoubleHop : DISABLED
        Max Login Attempts: 0    Failed Login Timeout 0
        IcmpResponse: PASSIVE
        TD: 0
 
1)      VPN Session Policy Name: AppController2-Policy  Priority: 0
 
1)      Primary DFA policy name: sfdfa_rsa_sample_policy  Priority: 0

Note: The DFA policy has to be primary.

Bind with a VPN virtual server from GUI

Alternatively, you can also use the NetScaler web console.

Troubleshooting and Debugging

DFA involves multiple components and this makes troubleshooting and debugging tricky. Sometimes you might have to troubleshoot each component. This section focuses on NetScaler Gateway and partially on StoreFront (DFA server).

NetScaler Debugging

The following are the debugging steps for NetScaler:

• Enable verbose (all) logging levels using the following commands:

  Set audit syslogparms –loglevel all
  Set audit nslogparms –loglevel all

• Enable knob to log debug information related to DFA in ns.log:

  nsapimgr -ys call=enable_dfa_debug

  Search for the string DFA.

• In case of issues with CitrixPKS communication, disable the encryption by running the following command:

  nsapimgr –ys call=enable_dfa_citrixnone

  The following are counters related to DFA which helps in identifying the failures:

  aaa_tot_dfa_sinfo_down
  aaa_tot_dfa_encrypt_success
  aaa_tot_dfa_send_newiv_owner
  aaa_tot_dfa_ctlen_ins_fail
  aaa_tot_dfa_enc_body_mangle_fail
  aaa_cur_dfa_temp_session
  aaa_tot_dfa_full_session
  aaa_cur_dfa_full_session
  aaa_tot_dfa_success_resp
  aaa_tot_dfa_auth_resp_parse_fail
  aaa_tot_dfa_auth_resp_fail
  aaa_tot_dfa_auth_resp_uname_extracted
  aaa_tot_dfa_auth_resp_groups_extracted
  aaa_tot_dfa_auth_resp_passwd_extracted  

• Verify if DFA action ServerURL is misconfigured.

• Verify for shared screen related issues.

StoreFront Debugging

The following are the debugging steps for StoreFront:

• Verify if the RBA authentication is enabled on the site.

• In case of errors examine the event logs on the machine.

• Verify the DFA server configuration and also verify if the client id and passphase configured on NetScaler and StoreFront are the same.