1

Citrix System Engineer Document Deploying the Embedded Java ICA Client with CSG and Columbia 6.01.36 SE Standards Document

Date Prepared: Monday, March 11, 2002 Prepared by: Mike Fouts, Citrix System Engineer, New Jersey Territory David Kim, Citrix System Engineer, DC/Metro Territory

2

Table of Context

Table of Context..................................................................................................................... 2 1. Introduction.................................................................................................................. 3

1.1 Overview.................................................................................................................................... 3 1.2 Features..................................................................................................................................... 3

2. System Requirements ........................................................................................................ 4 2.1 General Requirements ................................................................................................................. 4 2.2. NFuse 1.61 Installation and Configuration .................................................................................... 5 2.3 CSG Installation and Configuration ............................................................................................... 6 2.4 Project Columbia Installation and Configuration ............................................................................. 6

3. Configuring Columbia and the Embedded Java Client..................................................... 11 3.1 Using Private SSL Certificates ..................................................................................................... 11 3.2 Creation of .cab or .jar files........................................................................................................ 12 3.3 Configuring Embedding of Published Applications......................................................................... 15 3.4 Allowing Users to Select Application Launch Methods ................................................................... 15

4. Client Configuration and Usage .................................................................................... 17 Reference ............................................................................................................................ 21

3

1. Introduction

1.1 Overview This document explains how to embed the Java ICA client with CSG, Nfuse, and Project Columbia. The embedded Java client allows you to publish applications via Nfuse/project Columbia and deliver applications to users with no ICA client download and installation required from the client device. The implementation of CSG coupled with NFuse will offer industry standard SSL communications for the client ICA session. SSL encryption provides server authentication, encryption of data stream, and message integrity checks.

1.2 Features The advantage of the Java client is the speed of ICA client deployment with no workstation client footprint. When connected to a Citrix server, the ICA Java Client provides additional features that make remote computing just like running applications on a local desktop. The ICA Java Client has the following features:

• Video Support

o Resolution up to 65536 X 65536

o 256 color to 24-bit

• Client Clipboard mapping

• Client device mapping

o Client printer mapping

o Client drive mapping

o Client audio mapping

o COM port mapping

• Data Compression

• Data caching

• SpeedScreen Latency Reduction

• Hotkeys

• Shadowing

The Java client however, does not support the following:

• Seamless windows

• Auto-Connect (Limitation of Citrix Secure gateway)

2. System Requirements

2.1 General Requirements Three Windows 2000 servers with SP2:

CSG Gateway Server

• Server Certificate mapped to the FQDN

Secure Ticket Authority

• IIS

NFuse 1.61/Columbia 6.01.36 or greater

o IIS

Note:

Prior to the installation and configuration of Columbia 6.01.36, you must have the following installed and configured properly. These items include:

• NFuse 1.61 or greater

• Citrix Secure Gateway 1.0 or greater

Figure 1. CSG Architecture

Client

CSG Server Certificate

MetaFrame Server Farm

Internet

NFuse Server Certificate (Secure URL)

4

and Certificate Placement

DMZ

STA

Internal Network

5

There is no need for an SSL-enabled ICA client Version 6.20 or higher on the client workstation with the Java Client. In addition to the Java client, 32-bit windows, Macintosh and the Linux platforms are supported. Client software is available for download from the Citrix Download site, http://www.citrix.com/download.

2.2. NFuse 1.61 Installation and Configuration

A default installation of NFuse 1.61 should be completed prior to installing and configuring Columbia and the Java client.

Note:

The “nfuse.conf” text file globally controls NFuse 1.61. This file is located in: C:\Program Files\Citrix\Nfuse Figure 1.1

Figure 2: Nfuse.conf

6

Notes:

When utilizing Project Columbia 6.01.36 with CSG, there should be no entries pertaining to CSG in the nfuse.conf file. CSG configuration should be configured solely in the “config.txt” file of Project Columbia.

Prior to installation of Project Columbia, NFuse 1.61 should be installed and tested for proper functionality.

2.3 CSG Installation and Configuration For the purpose of this document, CSG will need to be configured and functional with NFuse prior to undertaking the configuration steps in this document.

Please reference the CSG Admin Guide for further assistance with the installation and troubleshooting of Citrix Secure Gateway.

2.4 Project Columbia Installation and Configuration Installation

Upon installation and verification of NFuse, you can begin the Columbia installation.

To install Columbia, download and copy the Columbia .zip file and expand it into a temporary directory, i.e. C:\Temp\Columbia

After successful extraction, simply copy the extracted Columbia files to a folder beneath your web root directory, i.e. C:\Inetpub\wwwroot\Columbia

Note:

For the purpose of this document, it is assumed that the web root directory for Project Columbia is: C:\Inetpub\wwwroot\Columbia

Verify that the following directories have been created and copied to your Columbia directory:

\Clients

\Config

\Media Note: Future builds can be downloaded from www.citrix.com/cdn

7

Figure 3. Directory Structure of Project Columbia

Clients

Project Columbia includes the current Java ICA client (6.20.1207) in the following directory: C:\Inetpub\wwwroot\Columbia\Clients

When utilizing the 6.20.1207 embedded Java client, there is no need to download any additional clients to the \Clients directory (Figure 3).

Figure 4. Files in the Project Columbia Client directory

8

Configuration

Project Columbia includes a file named “config.txt”. This file is located in: C:\Inetpub\wwwroot\Columbia\Config

Config.txt is used to set global preferences regarding how Columbia and its features should be implemented. The default config.txt file is listed below:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Citrix NFuse Project Columbia

;

; Please read help.htm before configuring this file.

; For changes to take effect you must restart the World

; Wide Web Publishing Service

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

NFuse_ColumbiaVersion=6.01.036

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Configuring XML Services

;

; NFuse_Farm=Farm 1 name, 0, server1, server2, server3

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Automatic Client Delivery

NFuse_PushWin32WebClient=NULL

NFuse_Win32WebClientVersion=6,20,985,0

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Changing expired passwords

NFuse_ChangePasswordMode=ICA

NFuse_ICAModePasswordChangeServer=default

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; NAT, Proxies and Port Address Translation

;NFuse_InternalNetworks=192.168.

;NFuse_PortMap=10.3.2.1:1494, 206.35.17.10:4001

;NFuse_PortMap=10.3.2.2:1494, 206.35.17.10:4002

;NFuse_PortMap=10.3.2.3:1494, 206.35.17.10:4003

;NFuse_IgnorePortMaps=10., 192.168.

;NFuse_ProxyAddr=206.12.34.56, 192.168.0.1

9

;NFuse_ReverseProxyAddr=192.168.1.1

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Application launch and display options

NFuse_NumberOfColumns=3

NFuse_IconPercent=100

NFuse_EmbedApplications=On

NFuse_EmbedMethod=3

NFuse_AllowCustomizeLaunchType=On

NFuse_ShowAppIcons=1

NFuse_ShowAppNames=1

NFuse_ShowAppDescriptions=0

;NFuse_HiddenApps=app1, app2, app3

;NFuse_HiddenFolders=folder1, folder2, folder3

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Citrix Secure Gateway and SSL Relay integration

;CSG_Enable=On

;CSG_Gateway=njctxlaptop.njcitrix.com:443

;CSG_STA=http://3.3.88.7:80/Scripts/CtxSta.dll

;CSG_STA=http://sta_server2:80/Scripts/CtxSta.dll

;CSG_STA=http://sta_server3:80/Scripts/CtxSta.dll

;CSG_InternalNetworks=10.,192.168.

NFuse_SSLPrivateRootCertName=myroot.cer

NFuse_SSLPrivateRootCABFile=myroot.cab

NFuse_SSLPrivateRootJARFile=myroot.jar

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Other miscellaneous features

; NFuse_DomainList=DOMAIN1, DOMAIN2, DOMAIN3

NFuse_HideSingleDomainList=0

NFuse_PopulateUserName=0

NFuse_DisableRightClick=0

NFuse_LaunchSingleApp=0

;NFuse_IdleSessionTimeout=20

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Logging and Debugging

NFuse_Debug=0

NFuse_LogGatewayErrors=1

NFuse_LogGatewaySuccess=1

10

NFuse_LogSignonErrors=1

NFuse_LogSignonSuccess=1

Note: After making changes to the config.txt file, you must restart the World Wide Web Publishing service or unload the ASP application in Internet Services Manager, then point your browser to default.htm. To restart the WWW service on an IIS 5.0 server, simply go to a command prompt and type: iisreset

This command will stop and restart the WWW service automatically. Syntax Descriptions For the purpose of this document, we will be utilizing the following features in the config.txt file. The config.txt is located in \inetpub\wwwroot\Columbia\Version6.01.036\config. Integrating with Citrix Secure Gateway Under the “Citrix Secure Gateway and SSL Relay integration” section in config.txt: CSG_Enable=On CSG_Gateway=csg-gateway.company.com:443 CSG_STA=http://STA-server-1:80/Scripts/CtxSta.dll CSG_STA=http://STA-server-2:80/Scripts/CtxSta.dll CSG_STA=http://STA-server-3:80/Scripts/CtxSta.dll CSG_InternalNetworks=IP-prefix [,…] Where: Enable=On This enables CSG usage in Project Columbia. csg-gateway.company.com:443 This is the FQDN of the server running the CSG service. This FQDN must exactly match the subject name of the server certificate installed on the CSG gateway server, and all clients must be able to resolve this FQDN to the CSG’s external IP address. 443 is the SSL port that CSG will service client requests on. STA-server-1:80 This is the server name or IP address of the Secure Ticket Authority. Configure your STA here, along with the default port and location of the CtxSta.dll. Only one STA server is required for normal operation, but up to 8 STA servers may be listed for failover purposes here. 80 is the default TCP port for the STA. IP-prefix This is a comma-separated list of client IP address prefixes for whom CSG should not use. For example: CSG_InternalNetworks=3.,172.16., In this scenario, any end user whose IP address begins with “3.” Or “172.16.” will connect directly to MetaFrame servers without using CSG.

11

3. Configuring Columbia and the Embedded Java Client

3.1 Using Private SSL Certificates Citrix Secure Gateway, NFuse or the Citrix SSL Relay service requires a server certificate obtained from a private certification authority (i.e. Microsoft Certificate Services), you must install your CA’s root certificate onto every client machine in order for the ICA-SSL connection to succeed. In the case of the embedded ICA Java client, the root certificate must be packaged into a .cab file (for Internet Explorer users) or a .jar file (for Netscape users). All the root certificates are stored in browser’s (Internet Explorer or Netscape) properties Figure 5.

Figure 5. Root Certificates A root certificate verifies the signature of the Certificate Authority (CA) on the Server Certificate. As Figure 5 indicates, Windows usually installs many pre-installed CA certificates for well-known CA’s:

Verisign

Entrust

Baltimore

RSA

Thawte

12

Figure 6. Example of a root Certificate Root certificates are self-signed entities that are used to verify server certificates. Self-signed infer the issued to field is identical to the issued by field

3.2 Creation of .cab or .jar files The .cab and .jar files must then be copied to your web server beneath the ..\Columbia\Clients subdirectory. This procedure allows you to deploy the embedded Java client without having the user manually download and install the root certificate.

The steps for packaging and using a private root certificate with Columbia and the Java ICA client are as follows:

1. Export your private root certificate to a file named “certnew.cer”. This certificate name will be specified later in the following location in config.txt:

NFuse_SSLPrivateRootCertName

13

2. Next, we need to obtain the appropriate Java Development Kit (JDK). Download the appropriate JDK as follows:

• To create .jar files for Netscape and other JVM’s, download a copy of the Sun JDK at: http://java.sun.com/products/jdk/1.1/

• To create .cab files for Internet Explorer, download the Microsoft SDK for Java at: http://www.microsoft.com/java/dowload.htm

3. To install the Sun JDK and create the .jar archive, complete the following steps:

• Download and run the following file: jdk-1_1_8_008-win.exe

• By default, the following directory will be created from running the installation: C:\Program Files\jdk1.1.8

• Change to the above directory and ensure that your exported private root certificate is copied into the C:\Program Files\jdk1.1.8 directory.

• Create the Java archive. To do this, execute the following command:

jar –cf certnew.jar certnew.cer

Note: the Jar command in located in the \Bin directory Figure 5

This command creates an archive called “certnew.jar”. This archive name will be specified later in the following location in config.txt:

NFuse_SSLPrivateRootJARFile

Figure 7. The Jar utility

4. To install the Microsoft SDK for Java and create the .cab archive, complete the following steps:

• Download and run the following file: SDKJava40.exe

• By default, the following directory will be created from running the installation: C:\Program Files\Microsoft SDK for Java 4.0

14

• Change to the above directory and ensure that your exported private root certificate is copied into the C:\Program Files\Microsoft SDK for Java 4.0 directory.

• Create the cab archive. To do this, execute the following command:

cabarc n certnew.cab certnew.cer

Note: the Cabarc command in located in the \Bin directory Figure 6

• This command creates an archive called “certnew.cab”. This archive name will be specified later in the following location in config.txt:

NFuse_SSLPrivateRootCABFile

Figure 8. Cabarc utility

5. Copy the certnew.jar and certnew.cab files you just created into Columbia’s clients directory, i.e. C:\Inetpub\wwwroot\Columbia\Clients

This step allows Columbia to automatically pull the embedded client(s) from the \Columbia\Clients directory along with the private certificate archive.

6. Edit the config.txt file in ..\Columbia\Config as follows:

NFuse_SSLPrivateRootCertName=certnew.cer

NFuse_SSLPrivateRootCABFile=certnew.cab

NFuse_SSLPrivateRootJARFile=certnew.jar

Where:

PrivateRootCertName is the root certificate name

PrivateRootCABFile= the .cab file created above

PrivateRootJARFile= the .jar file created above

15

7. Upon saving changes to the config.txt file, restart IIS by typing “iisreset” at the command line of the web server in order for the config.txt changes to take effect.

3.3 Configuring Embedding of Published Applications

By default, NFuse 1.61 will launch applications in separate seamless windows. Project Columbia allows you to embed published applications into an HTML page using the ActiveX, Netscape plugin or Java applet ICA clients.

To configure this setting for Columbia, edit the following entries in config.txt:

NFuse_EmbedApplications=On

NFuse_EmbedMethod=1 | 2 | 3

Where NFuse_EmbedMethod numbers correspond to the following options:

1. ActiveX Control

2. Netscape Plugin

3. Java Applet

When NFuse_EmbedApplications=On, applications will launch in an HTML window with the preferred ICA client embedded into the window.

Additionally, this setting dictates the default client choice setting in the users “Settings” page of NFuse/Columbia.

3.4 Allowing Users to Select Application Launch Methods Administrators may choose to allow end users to choose their own method for launching applications. In order for users to see this settings page, you must make the following change to NFuse.conf:

AllowCustomizeSettings=On

Note: This setting applies to NFuse.conf, not config.txt

The following setting controls this preference:

NFuse_AllowCustomizeLaunchType=On

16

When NFuse_AllowCustomizeLaunchType=On, users will receive a menu labeled “Client Type” on the NFuse settings page allowing them to choose between launching applications with their native ICA client or embedding applications with any of the three browser methods listed above.

17

4. Client Configuration and Usage

With the above implementation complete, the client requires no configuration or client installation, provided the embedded Java client is configured as the default client.

With the embedded Java client, users simply need to navigate to your NFuse/Columbia website, i.e. https://yourserver.columbia.com

Figure 9. Login

18

Figure 10. Web enabled applications

Although the Java client is configured as the default, users may be allowed to change the client mechanism that they wish to use if desired. This administrative functionality can be turned on or off. Users can change this client selection by choosing “Settings” from the Columbia webpage as displayed below:

19

Figure 11. Client Customization

20

Figure 12. Java embedded application

21

Reference

Citrix Secure Gateway Admin Guide

Citrix Secure Gateway Getting Started Guide

Citrix ICA Java Client Admin Guide

Citrix Knowledgebase

www.citrix.com

http://java.sun.com/products/jdk/1.1/

http://www.microsoft.com/java/dowload.htm

White paper: Using the Citrix SSL Relay Service

SSL and TLS Essentials, by Stephen Thomas

ISBN: 0-471-38354-6

www.citrix.com/cdn

Project Columbia

List of Contributors:

Mike Fouts

David Kim

Jay Tomlin

Citrix Technical Support

Ken Staples