Citrix Web Interface 5.1 Integration¶
Introduction¶
This document outlines the necessary steps to integrate PINsafe authentication into the Citrix 5.1 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.
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: File:Citrix_WI_5.1_Integration.zip
Note: The default Citrix Install path is C:InetpubwwwrootCitrixMetaFrame
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¶
Citrix Web Interface Configuration¶
Copy across the Web Interface Files
On the Citrix Web Interface Server:
The following files need to be copied to the listed locations, below the root of the Citrix web interface site. Where an existing file is being replaced and for modified files, ensure you make a backup copy so that the integration can be removed at a later date.
PINsafeClient.dll to /bin.
login.aspx and pinsafe_image.aspx to /auth.
login.js to /auth/clientscripts.
loginButtons.inc and loginMainForm.inc to /app_data/auth/include.
loginView.cs and login.cs to /app_data/auth/serverscripts.
Ensure file permissions are set correctly on the coped files, Authenticated users need read permissions.
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.
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="" />
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, the select Radius from the dropdown list.
Additional Configuration Options¶
Self Reset¶
This outlines how to add the self reset option to the Citrix Web Interface.
The Citrix Web Interface 5.1 self reset files can be downloaded here: File:Citrix_WI_5.1_SelfReset.zip
Download PINsafeClient.dll and copy to the bin folder overwriting the existing file installed above. Copy reset.aspx and reset.aspx.cs into the auth folder.
Add reset.aspx to the list of unprotected pages in web.config. Locate key=”AUTH:UNPROTECTED_PAGES”, and at the end of the value field, insert “,./reset.aspx”.
Insert a link on the Citrix login page to open the reset page.
Edit app_dataincludeloginMainForm.inc, and insert the following line after the login button row, immediately before the </table> tag.
<tr><td><a href=”./reset.aspx” target=”_blank”>Forgotten my PIN</a></td></tr>
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 Swivel one time code is entered in addition to the Citrix credentials should the user be logged in.
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.
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