Citrix Access Gateway Enterprise Edition 9
From Swivel Knowledgebase Wiki
Contents |
Introduction
This document shows the steps required to integrate PINsafe with the Citrix Access Gateway Enterprise Edition 9.2 and 9.3 (Formerly Netscaler VPN). for versions 8.x to 9.1 refer to Citrix Access Gateway Enterprise Edition 8.
It covers the following steps.
- Configuring PINsafe to accept authentication requests from the CAGEE
- Modifying the CAGEE login pages
- Configuring the CAGEE to authenticate via PINsafe
This gives the basics of the integration, with html and javascript skills the integration can be customised as required.
To use the Single Channel Image such as the TURing Image, the PINsafe server must be made accessible. The client requests the images from the PINsafe server, and is usually configured using Network Address Translation, often with a proxy server. The PINsafe appliance is configured with a proxy port to allow an additional layer of protection.
Prerequisites
Access Gateway Enterprise Edition firmware version 9.2 or 9.3
An administrative logon account for the Access Gateway
A Secure Shell (SSH) programme (eg putty) and an SSH-based file transfer application such as WinSCP
A Unicode-aware text file editor such as TextPad or WordPad
PINsafe 3.x
PINsafe server must be accessible by client when using Single Channel Images, such as the Turing Image, this is usually implemented by a NAT to the PINsafe server. Ensure that only the required ports are allowed access.
CAGEE pages to modify and/or PINsafe files for version 9.2 or version 9.3
Baseline
PINsafe 3.5
Citrix Access Gateway Enterprise Edition Version 9.2
and also PINsafe 3.8
Citrix Access Gateway Enterprise Edition Version 9.3
Architecture
The Citrix Advanced Access Gateway Enterprise Edition makes authentication requests against the PINsafe server by RADIUS.
You can create different logon realms / pages called Virtual Servers, these can have different authentication servers/policies, SSL certificates and resources attached to them. However, the downside is they ALL use the same index.html/login.js/en.xml files, so you cannot have multiple landing pages with/without the pinsafe modifications.
PINsafe Configuration
Configuring the RADIUS mode and Host IP
Configure the RADIUS settings using the RADIUS configuration page in the PINsafe Administration console. In our example (see diagram below) the RADIUS Mode is set to ‘Enabled’ and the HOST IP (the PINsafe server) is set to 0.0.0.0. (leaving the field empty has the same result), or to be the actual address of the PINsafe server (the physical IP address, but not the virtual IP if using a PINsafe HA Pair). This means that the server will answer all RADIUS requests received by the server regardless of the IP address that they were sent to.
Note: for appliances, the PINsafe VIP should not be used as the server IP address, see VIP on PINsafe Appliances
Setting up the NAS
Set up the NAS using the Network Access Servers page in the PINsafe Administration console. Enter a name for the CAGEE. The IP address has been set to the IP of the VPN appliance, and the secret ‘secret’ assigned that will be used on both the PINsafe server and VPN RADIUS configuration.
You can specify an EAP protocol if required, others CHAP, PAP and MSCHAP will be supported. All users will be able to authenticate via this NAS unless to restrict authentication to a specific repository group.
Enabling Session creation with username
The PINsafe server can be configured so that it returns an image stream containing a TURing image by presenting the username via the XML API or the SCIMage servlet. It is this mechanism that is used to return the TURing image to the VPN sign in page.
Go to the ‘Single Channel’ Admin page and set ‘Allow Session creation with Username:’ to YES.
To test your configuration you can use the following URL using a valid PINsafe username:
Appliance
https://PINsafe_server_IP:8443/proxy/SCImage?username=testuser
Software install
https://PINsafe_server_IP:8080/pinsafe/SCImage?username=testuser
For further information see Single Channel How To Guide
Setting up PINsafe Dual Channel Transports
Citrix Access Gateway Enterprise Edition Configuration
The basis of the integration is to create new versions of the login pages. These pages are on the CAGEE and can be accessed via SSH. There are two approaches, firstly to overwrite the relevant files with those provided by Swivel Secure. The other is to actually modify those on the appliance. The latter approach has the advantage the modified pages will always be based on the latest version of the CAGEE files. The main requirement for modifying these pages is to include a TURing image and the button required to request that image. The same approach could also be used to include a button/image for SMS on-demand. If the single Channel TURing image is not to be used, then the login page does not need to be modified, unless other functions are required such as the Get Security String Index. Note: TURing Images, SMS Confirmed image and Get Security String Index Images require the PINsafe server to be accessible from the internet, usually with a NAT.
Login Page Customisation
SSH onto the appliance using an admin account. Once onto the box you need to type shell to get access to the command line.
>Last login: Wed Sep 10 19:12:45 2008 Done > shell Last login: Wed Sep 10 21:13:35 2008
Navigate to the location of the pages to be modified, and make a local backup copy of them
>cd /netscaler/ns_gui/vpn >cp index.html index.html.bak >cp login.js login.js.bak
In version 9.2, you will also need to modify any resource language files you use. After the above commands, do the following:
>cd resources >cp *.xml *.xml.bak
Note that the files in /netscaler/ns_gui/vpn are re-written when the server is rebooted therefore make sure so save these files elsewhere regularly to prevent work in progress being lost during development. How to manage these pages is covered later.
The index.html file now needs to be edited (or replaced). The tool vi can be used to do this but an application such as WinSCP will make this easier. The required files can be found in the prerequisites.
A pinsafe.js file that is a modification of the existing login.js file is required. Make a copy of login.js called pinsafe.js The sUrl setting needs to be changed to reflect the IP address and port number of the relevant PINsafe server.
For an Appliance this will normally be similar to:
sUrl="https://turing.swivelsecure.com:8443/proxy/SCImage?username=";
For a software only install this will be similar to:
sUrl="http://support.swivelsecure.com:8080/pinsafe/SCImage?username=";
Modify the language resource files, which can be found in the resources sub-folder of the vpn folder. If you are only using the English language, then edit en.xml and search for
<String id="Password2">
Replace the value for id="Password2" with "OTC:". Also, insert a new string for id="Password1" with a value of "AD Password". You should therefore have 2 lines as follows:
<String id="Password1">AD Password</String> <String id="Password2">OTC:</String>
(Note that Password1 has no colon at the end, whereas Password2 has a colon).
If you will be using languages other than English, you will also need to edit any other language files you use, replacing the value for Password2 with the appropriate label for OTC (One-time code) and inserting a new string for Password1 with the label for AD (Active Directory) password.
Because all files in /netscaler/ns_gui are overwritten upon a restart or power cycle, a script must be created that runs at startup to copy the modified files back to this location. The nsafter.sh or rc.netscaler shell scripts can be created or modified to accomplish this. For example via ssh:
> shell # mkdir /var/mods # cp /netscaler/ns_gui/vpn/index.html /var/mods/index.html.mod # cp /netscaler/ns_gui/vpn/pinsafe.js /var/mods/pinsafe.js.mod # touch /nsconfig/rc.netscaler # echo cp /var/mods/index.html.mod /netscaler/ns_gui/vpn/index.html >> /nsconfig/rc.netscaler # echo cp /var/mods/pinsafe.js.mod /netscaler/ns_gui/vpn/pinsafe.js >> /nsconfig/rc.netscaler # cp /netscaler/ns_gui/vpn/resources/en.xml /var/mods/en.xml.mod # echo cp /var/mods/en.xml.mod /netscaler/ns_gui/vpn/resources/en.xml >> /nsconfig/rc.netscaler
Citrix Advanced Access Gateway Enterprise Edition RADIUS Configuration
The CAGEE needs to be configured to use the PINsafe server as a RADIUS authentication server. Where a VIP is being used on the PINsafe server then configure the RADIUS request to be made against each of the PINsafe servers together with the use of Session Sharing.
PINsafe can be configured as the only authentication server or as an additional authentication server, usually this would be together with AD. The required steps are pretty much the same for both scenarios.
Create a new Authentication policy (under the Netscaler->System->Authentication menu). The policy must specify RADIUS and then the PINsafe server must be added as a RADIUS server.
To setup a simple policy click on Add to bring up the Create Authentication Policy enter a Name: policy name, Authentication Type: RADIUS, Server: PINsafe server, under Named Expressions select True Value then click on Add Expression so ns_true appears, then Create.
On the SSL-> Virtual Server menu, the created policy must be activated. If just PINsafe authentication is required then you ensure that only the PINsafe policy is active. If you require AD and PINsafe authentication then you need to make active the PINsafe policy as the secondary. Save the settings.
Additional Configuration Options
Challenge and Response
Citrix Access Gateway Enterprise Edition 9.2 supports RADIUS Challenge and Response
Image Request button displayed when needed
The following code allows the Single Channel Image request button to be only shown when required.
function ns_showpinsafe()
{
var pspwc = ns_getcookie("pwcount");
if ( pspwc == 2 )
{
document.write('<td>');
document.write('<input type="button" id="btnTuring" value="Get Image" ');
document.write('onclick="showTuring();" class="CTX_CaxtonButton" ');
document.write('onmouseover="this.className=');
document.write("'CTX_CaxtonButton_Hover';");
document.write('" onmouseout="this.className=');
document.write("'CTX_CaxtonButton';");
document.write('" />');
document.write('</td>');
}
}
Testing
Browse to the login page and check that a Turing image appears and the One time Code can be entered to login.
For SMS or Mobile Phone Apps do not click on the Get Image button, but enter the OTC
If the incorrect credentials are used then the login should fail
Where the TURing image is not used, then the Get Image page modification can be omitted
Troubleshooting
Check the PINsafe logs for Turing images and RADIUS requests.
Image from PINsafe server absent
The CAGEE Netscaler checks each password/OTC in turn, so if the AD password is checked first and is incorrect then the secondary authentication will not be tested.
Known Issues and Limitations
The CAGEE caches the javascript so when you make modifications on the CAGEE they are not reflected on the log-in page as rendered. A way round this is to change the name of the .js file and edit the index.html file to use this new .js file. see [1]
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
