CAC/PIV/SIPR Token with NetScaler Gateway and StoreFront

NOTE: Citrix has now published a full deployment guide around smart cards.  I would strongly recommend referring to that guide as it contains a wealth of information.

This guide covers configuring a NetScaler Gateway (NSG), formerly known as Access Gateway Enterprise Edition (AGEE), for CAC authentication to StoreFront (SF).  It also applies to PIV cards and SIPR tokens.  There is an assumption that the reader is already slightly familiar with both NSG and SF and that both products are already installed in the environment.

Storefront

Enable Authentication Method

1. In the StoreFront Console, navigate to Citrix StoreFront->Authentication.
   
2. In the Actions pane, click Add/Remove Methods.
   
3. Check Pass-through from NetScaler Gateway. (NSG was formerly known as Access Gateway Enterprise Edition, AGEE) Click OK.
   
4. In the Actions pane, click Configure Delegated Authentication.
   
5. Make sure Fully delegate credential validation to NetScaler Gateway is checked. Click OK.
   

Add the NetScaler Gateway

1. In the StoreFront Console, navigate to Citrix StoreFront->NetScaler Gateway.
   
2. In the Actions pane, click Add NetScaler Gateway Appliance.
   
3. Enter the information for the environment’s NetScaler Gateway. Take note that this example uses a separate callback vserver. This is because the client certificate setting on the NetScaler will be set to Mandatory. To Use the same vserver it would need to be set to Optional. NOTE: The NSG URL cannot be the same as the Storefront URL. They must be different! Click Next.
   
4. At the Secure Ticket Authority (STA) windows, click Add and add the STAs for the environment. Set the remainder of the settings as appropriate for the environment. Click Create.
   

Enable Remote Access for Store

1. In the StoreFront Console, navigate to Citrix StoreFront->Stores.
   
2. Select to existing store that is to be configured. In the Actions pane click Enable Remote Access.
   
3. In the Enable Remote Access window set the Remote Access type to No VPN tunnel. Check the appropriate NSG to use for the Store (new NSGs can also be added here using the Add button). If more than one NSGs were added, select the Default appliance to use for the store. Click OK.
   

Configuring the NetScaler Gateway

Creating a new virtual server

If there is an existing virtual server to edit, this section can be skipped. Proceed to the Tweaking the Virtual Server section.

1. Log into the NetScaler’s web management GUI. All locations given assume the deployment type was set to NetScaler ADC when logging in.
   
2. Navigate to the NetScaler Gateway node. This is when under the Configuration section/tab.
   
3. Click Configure NetScaler Gateway for Enterprise Store.
   
4. In the window that pops-up, click Create New NetScaler Gateway at the upper right.
   
5. Enter a name and IP address for the virtual server. Click Continue.
   
6. Select the Certificate to use as the server certificate for this virtual server. Click Continue.
   
7. Set the Primary Authentication to Certificate. If there is an existing certificate authentication profile on the NetScaler for CAC/PIV, select it. If not, select Configure New. The User Name Field needs to be SubjectAltName:PrincipalName. Click Continue.
   
8. Set the Enterprise Store Settings to XenApp/XenDesktop. Set the Deployment Type to StoreFront. Enter the StoreFront server and store information. Make sure to use the same STA as in StoreFront. More STAs can be added later. Click Done.
   
9. The pop-up window can now be closed and you will be returned to the NS web management gui (assuming this is still the next window in the background).

Tweaking the Virtual Server

1. Navigate to NetScaler Gateway->Virtual Servers. Double-click the virtual server to open it.
2. Under the Certificates tab, use the triangle to the right of the Add button to add each CA required to validate the CAC/PIV cards. All CAs up to and including the root are required. Do not click OK yet!
   
3. Still under the Certificates tab click SSL Parameters button. In the Others section check Client Authentication and set Client Certificate to Mandatory. (This causes the requirement for a separate callback URL) Click OK to close the SSL Parameters windows. Do not click OK at the virtual server window yet!
   
4. Under the Policies tab there should be two Session Policies. One will start “PL_WB”. This is for the Receiver for Web. Since Receiver for Web does not yet support smart card authentication, right-click it and unbind the policy. Double-click the policy that starts “PL_OS”. This is for Native Receivers (OS = Operating System).
   
5. In the Session Policy, switch the expression rules to Match All Expressions. Do not click OK yet.
6. On the Request Profile line, click the Modify button. Make sure the following are set under each tab. Others may also already be set from the wizard.
   1. Network Configuration tab
      1. Alter nothing!!!
   2. Client Experience tab
      1. Clientless Access – Override Global – Allow
      2. Plug-In Type – Override Global – Java
      3. SSON to Web Apps – Override Global – Checked (Credential Index no longer needs to be secondary as with Web Interface setups)
   3. Security tab
      1. Default Authorization Action – Override Global – Allow
   4. Published Applications tab
      1. ICA Proxy – Override Global – On
      2. WI Address – Override Global – Base url of SF server (https://FQDN); not path to store also
      3. SSON Domain – Uncheck Override Global and leave blank.
      4. Account Services Address – Override Global – Base url of SF server (https://FQDN)
7. Click OK to close the Session Profile window. Click OK to close the Session Policy window. Do not click OK at the virtual server window yet!
8. Under the Published Applications tab add any additional STAs that might be needed for the environment. Click OK to close the virtual server window.

Creating the Callback Virtual Server

The callback is used for SSON purposes. Since the virtual server for StoreFront has client certificate set to mandatory, a callback to this URL by StoreFront will be rejected by the NSG as it does not present a client certificate.

1. Navigate to NetScaler Gateway->Virtual Servers. Click the Add button.
2. Enter a Name and IP for the callback virtual server. Under the Certificates tab, add a server certificate. Click Create when done.

Troubleshooting

• There is an Application log for StoreFront in the Event Viewer. Check there for error messages.
  
• Make sure all the proper CAs are added to the NSG virtual server to authenticate the CAC/PIV card in use. The entire chain needs to be added.
• Make sure all the proper CAs are installed on the client end device if using Windows. OSX and Linux may have the same requirement. Mobile devices do not.
• Watch the ns.log file on the NetScaler when a client attempts to connect. It can indicate issues such as missing CA certificates. “tail -f /var/log/ns.log” in an SSH session will watch it in real-time.
• Middleware is not needed on the StoreFront server.