Citrix Web Interface 5.4 Integration

Introduction

This document outlines the necessary steps to integrate PINsafe authentication into the Citrix 5.4 web interface. If the Single Channel Image for authentication is to be used a NAT is not required to the PINsafe server as the Image is proxied through the Web Interface server.

Baseline

PINsafe 3.5

Citrix Web Interface build 5.4

Prerequisites

This installation guide assumes that a Presentation Server site has been configured with Explicit authentication enabled. The customised files provided are based on build 4.5.1.8215 of the Citrix web interface, if you have a later version please contact your PINsafe reseller for an update.

The following files are required to complete the installation:

  • PINsafeClient.dll – PINsafe authentication client library.
  • login.aspx – Customised login page.
  • pinsafe_image.aspx – Serves single channel images from PINsafe to users.
  • login.js – Customised login page client script.
  • loginButtons.inc – Customised login form buttons.
  • loginMainForm.inc – Customised login form.
  • loginView.aspxf – Customised login logic constants.
  • login.aspxf – Customised login logic.
  • web.config.PINsafe – Additional configuration entries for PINsafe integration.

The files can be downloaded from here.

An alternative solution, which includes buttons for TURing image and message request, can be found here. This solution includes two additional files: pinsafe_message.aspx and pinsafe_ping.aspx.

Note: The default Citrix Install path is: C:InetpubwwwrootCitrixXenApp

PINsafe uses .NET so is not dependent on the OS being 32 bit or 64 bit.

NOTE: you cannot use a virtual IP as the RADIUS address, as this will not work.

NOTE: the files with the extension “.add” cannot simply be copied into the appropriate directories. They are text files containing notes as to how you should modify the corresponding files to implement PINsafe customisation. See the notes below for more details.

Architecture

The Citrix Web Interface makes authentication requests against the Swivel server by RADIUS.

Swivel Configuration

Configuring the RADIUS server

On the Swivel Administration console configure the RADIUS Server and NAS, see RADIUS Configuration

Enabling Session creation with username

To allow the TURing image, PINpad and other single channel images, under Server/Single Channel set Allow session request by username to Yes.

Setting up Swivel Dual Channel Transports

See Transport Configuration

Citrix Web Interface Configuration

Edit the Radius_secret.txt

On the Citrix Web Interface server

Edit the radius_secret.txt file so that it has the same shared secret as has been entered on the Swivel server.

Edit the Web.config file

On the Citrix Web Interface Server:

Edit the web.config file.

Note: the setting <add key=”RADIUS_NAS_IDENTIFIER” value=”” /> is present in the file and needs to be changed to

<add key="RADIUS_NAS_IDENTIFIER" value="citrix_wi" />

Note: It is recommended that you use the same value as the identifier in the NAS entry in the PINsafe admin console.

If the Web Interface server has multiple network interfaces, the value of RADIUS_NAS_IP_ADDRESS may need to be set to the IP address used by the NAS. This is the IP address of the Web Interface server, NOT the PINsafe server.

Make sure that the following entry is included, if it is not there already:

<add key="RADIUS_SECRET_PATH" value="/radius_secret.txt" />

To allow access to the TURing image from the login page, locate the following line:

<add key="AUTH:UNPROTECTED_PAGES" ...

The value attribute on this entry is a list of URLs that can be accessed without authentication. Add the following to the end of this list (before the closing quote):

,/auth/pinsafe_image.aspx

If you are using the alternative integration, you will need to include the other files:

,/auth/pinsafe_image.aspx,/auth/pinsafe_message.aspx,/auth/pinsafe_ping.aspx

Citrix Web Interface RADIUS Configuration

On the Citrix Web Interface server:

Launch the Access Management Console on the Web Interface 5.x server and select the appropriate site. Under Common Tasks, select Configure Authentication methods > explicit.

Click Properties > Two-factor authentication, then select Radius from the dropdown list.

_images/Citrix_Web_Interface_5.0_RADIUS_config4.jfif

Configure the PINSAFE server as RADIUS server. If you have more than one PINsafe server, you may need to configure all of them in the preferred order. NOTE: you cannot use a virtual IP as the RADIUS address, as this will not work.

Additional Configuration Options

The above modifications will allow authentication to the Web Interface using some of the PINsafe authentication mechanisms such as SMS, mobile Phone applet, and Taskbar. Additional configuration options including the single channel TURing image are listed below.

see Citrix Web Interface 5.X additional login page options

Changing the OTC label

To change the label for the PINsafe one-time code field from the default of “PASSCODE:”, locate the file C:Program FilesCitrixWeb Interface5.4.0Languagesaccessplatform_strings.properties. (If the language is not English, locate the appropriate file for the appropriate language, if it exists). Edit this file, and locate the line containing “Passcode=PASSCODE:”. Replace the second word PASSCODE with OTC, or an appropriate text.

Configuring Single Channel: Modifying the Web Interface Files

The required files (see prerequisites) are of two types: those NOT ending in “.add” need to be copied to the following locations below the root of the Citrix web interface site. Those ending in “.add” contain instructions describing how to modify the corresponding file without the “.add” extension. Where an existing file is being replaced or modified, ensure you make a backup copy so that the integration can be removed at a later date. Move any backup copy files to a separate location. Do NOT rename the file and leave it in place within the same directory. The below files contained within the zip file should extract to the relevant locations.

The majority of the files included in the integration are modifications to existing files. This are stored with the same name as the file they are intended to modify, but with the additional extension of .add. Each file contains instructions as to how the original files should be added. More details are given below:

  1. Copy pinsafe_image.aspx to /auth. This is a new file, not a modification to an existing one.
  2. Edit login.js in /auth/clientscripts. Insert the contents of login.js.add at the start of this file, below the header, as indicated in the file itself.
  3. Edit loginMainForm.inc in /app_data/include. Insert the contents of loginMainForm.inc.add as indicated in this file: locate a particular section of the file and insert a line.
  4. Edit loginstyle.inc in /app_data/include. Insert the contents of loginstyle.inc.add at the bottom of this file, before the footer text, as indicated in the file.
  5. Ensure file permissions are set correctly on the copied files, Authenticated users need read permissions.

Edit the Web.config file

On the Citrix Web Interface Server:

Edit the web.config file.

Find the the comma separated list of URL’s under the <appSettings> key AUTH:UNPROTECTED_PAGES and add Add /auth/pinsafe_image.aspx to the list.

The web.config.PINsafe file contains additional keys that need to be copied into the <appSettings> section of the web.config file. Adjust the key values to reflect your PINsafe installation.

The default settings are:

<add key="PINsafe_SSL" value="false" />

<add key="PINsafe_Server" value="192.168.2.254" />

<add key="PINsafe_Port" value="8080" />

<add key="PINsafe_Context" value="pinsafe" />

<add key="PINsafe_Secret" value="" />

If using a PINsafe virtual or hardware appliance, then the following settings may need to be used.

<add key="PINsafe_SSL" value="true" />

<add key="PINsafe_Server" value="192.168.2.254" />

<add key="PINsafe_Port" value="8080" />

<add key="PINsafe_Context" value="pinsafe" />

<add key="PINsafe_Secret" value="" />

Challenge and Response Authentication with Count Down Timer

Citrix Web Interface can be configured to use Challenge and Response whereby a user enters a username and password, and if that is correct the user is sent an SMS message and will be prompted to enter an OTC. By default the OTC sent is valid for two minutes only, so a count down timer is provided to show how long the user has left.

For information on configuring the PINsafe RADIUS Challenge and response see Challenge and Response How to Guide

The required files can be downloaded here: Challenge and Response with count down files

Extract the files ensuring their correct locations

challenge.inc is copied to app_data/include

challenge.js to auth/clientscripts

Testing

Navigate to the Citrix Web interface login page. The customisation is visible in the addition of a One Time Code field and a Get Code button. Attempting to login with a correct Citrix username and password but no one time code should result in failure. Only when a correct PINsafe one time code is entered in addition to the Citrix credentials should the user be logged in.

Login using Dual channel authentication

_images/Citrix_Xen_App_5.3_Dual.jpg

Login Using Single Channel Graphical Turing Image

_images/Citrix_Xen_App_5.3_Turing.jpg

Troubleshooting

Check the Swivel logs for any error messages, or absence of session starts and RADIUS requests.

If following the installation steps the Citrix web interface fails to display properly edit web.config and set the customErrors mode to Off. This will enable the display of detailed error messages which may assist in troubleshooting.

To verify the Turing image works from the Citrix server, enter the following into a web browser, preferably from the Citrix server, which should display a Turing image if the sever is functioning correctly:

For a Swivel virtual or hardware appliance:

https://<pinsafe_server_ip>:8443/proxy/SCImage?username=<username>

For a software only install see Software Only Installation

Try copying across again the install files checking to ensure that they are not read only. Also check the install files have not been overwritten by the Citrix software.

If the virtual or hardware appliance is using a self signed certificate it may be necessary turn off https connections between the virtual or hardware appliance and the Citrix server.

If a red cross appears, possible causes may be:

  • Self Signed Certificate, either install a valid certificate on the Swivel server or for testing the client can accept the certificate (load Image URL into browser)
  • Swivel server not accessible, check networking and firewalls. Check the Swivel server logs for a session started message.
  • Incorrect Swivel URL, either http, IP/hostname or context (pinsafe or proxy). Right click on the red cross and view the properties

Error Messages

INFO RADIUS: <0> Access-Request(1) LEN=78 192.168.1.1:4175 PACKET DROPPED - MESSAGE AUTHENTICATOR IS INCORRECT

This indicates that the shared secret on the access device and the Swivel NAS setting do not match.

INFO RADIUS: <0> Access-Request(1) LEN=78 192.168.1.1:4175 PACKET DROPPED - Duplicate packet from NAS

When an authentication fails the RADIUS client may retry sending additional authentication requests. Resolve the initial issue causing the failure.

Uninstalling

Copy the backup files made at the start of installation back to their original locations.

On the Citrix Web Interface server:

Launch the Access Management Console on the Web Interface 5.x server and select the appropriate site. Under Common Tasks, select Configure Authentication methods > explicit.

Click Properties > Two-factor authentication, then select Radius from the dropdown list. Remove the Swivel RADIUS entries.

Known Issues and Limitations

Upgrading the Citrix Web Interface will overwrite the Swivel settings and files so the Swivel integration may need to be applied again.

If you need to use userPrincipalName to authenticate to Swivel, you may find that the domain name is removed before sending the username to Swivel. To avoid this, make the following changes:

Locate and edit the file app_codePagesJavacomcitrixwipageutilsTwoFactorAuth.java

Find the following method:

public static String getUserName(UPNCredentials token, boolean fullyQualified)
{
    if (fullyQualified) {
        return token.getShortDomain() + "\\" + token.getShortUserName();
    } else {
        return token.getShortUserName();
    }
}

Replace it with the following:

public static String getUserName(UPNCredentials token, boolean fullyQualified) {
    return token.getUserIdentity();
}

Additional Information

For assistance in the PINsafe installation and configuration please firstly contact your reseller and then email Swivel Secure support at support@swivelsecure.com