| Sun ONE Portal Server, Secure Remote Access 6.2 Administrator's Guide |
Chapter 5
The NetletThis chapter describes how to use the Netlet to run applications securely between users’ remote desktops and the servers running applications on your intranet. To configure the Netlet, see Chapter 11, "Configuring the Netlet".
This chapter covers the following topics:
Overview of the NetletSun™ ONE Portal Server software users may want to run popular or company-specific applications on their remote desktops in a secure manner. You can provide secure access to these applications by setting up the Netlet on your platform.
The Netlet enables users to securely run common TCP/IP services over insecure networks such as the Internet. You can run TCP/IP applications (such as Telnet and SMTP), HTTP applications, and any fixed port applications.
You can run an application over the Netlet if:
Netlet Components
The various components used by the Netlet are shown in Figure 5-1.
Figure 5-1 Netlet Components
Listen Port on localhost
This is the port on the client machine on which the Netlet applet listens. The client machine is the localhost.
Netlet Applet
The Netlet applet is responsible for setting up an encrypted TCP/IP tunnel between the remote client machine and intranet applications such as Telnet, Graphon or Citrix. The applet encrypts the packets and sends them to the Gateway, and decrypts the response packets from the Gateway and sends them to the local application.
For static rules the Netlet applet is downloaded automatically when the user logs into the portal. For dynamic rules, the applet is downloaded when the user clicks on the link corresponding to the dynamic rule. See "Types of Rules" for details on static and dynamic rules.
To run the Netlet in a Sun Ray Environment, see "Running Netlet in a Sun Ray Environment".
Netlet Rules
A Netlet rule maps an application that needs to run on a client machine to the corresponding destination server. This means that the Netlet operates only on packets sent to ports defined in the Netlet rule. This ensures greater security.
As an administrator, you need to configure certain rules for the functioning of the Netlet. These rules specify various details such as the cipher to be used, URL to invoke, the applets to be downloaded, the destination port and the destination host. When a user on a client machine makes a request through the Netlet, these rules help determine how the connection has to be established. See "Defining Netlet Rules" for details.
Netlet Provider
This is the UI component of the Netlet. The provider allows users to configure the required applications from the Sun ONE™ Portal Server desktop. A link is created in the provider, and the user clicks on this to run the required application. Users can also specify the destination host for a dynamic rule in the desktop the Netlet provider. See "Defining Netlet Rules".
EProxy
All client requests are routed through the EProxy. EProxy handles only Netlet requests and passes any other requests to the RProxy. EProxy parses the Netlet requests and passes them to the Netlet Proxy (if it is enabled) or directly to the destination host.
Netlet Proxy (Optional)
The Gateway ensures a secure tunnel between the remote client machine and the Gateway. The Netlet Proxy is optional and you may choose not to install this proxy during the installation. For information on the Netlet Proxy, see "Using a Netlet Proxy".
Destination Port
This is the port on which the destination application’s server listens.
Netlet Usage Scenario
The following sequence of events are involved in using the Netlet:
- The remote user logs into the Sun ONE™ Portal Server desktop.
- If a static Netlet rule has been defined for a user, role or organization, the Netlet applet is automatically downloaded to the remote client.
If a dynamic rule has been defined for a user, role, or organization, the user needs to configure the required application in the Netlet provider. The Netlet applet is downloaded when the user clicks on the application link in the Netlet provider. See "Defining Netlet Rules" for details on static and dynamic rules.
- The Netlet listens on the client ports defined in the Netlet rules.
- The Netlet sets up a channel between the remote client and server over the ports specified in the Netlet rule.
Working With Netlet
For the Netlet to work as required for various users across different organizations, you need to do the following:
- Determine whether you need to create static or dynamic rules based on the user requirements. See "Types of Rules".
- Define the global options in the Netlet template from the Service Configuration tab on the Identity Server administration console. See Chapter 11, "Configuring the Netlet".
- Determine whether the rules should be organization, role, or user-based and make modifications as required at each level. See the Sun ONE Portal Server Administrator’s Guide for details on organization, role and user.
Defining Netlet RulesNetlet configuration is defined through Netlet rules that are configured in the Identity Server administration console under the SRA Configuration section. Netlet rules can be configured for organizations, roles, or users. If the Netlet rule is for a role or user, select the desired role or user after selecting the organization.
Netlet rules consist of the following fields:
Table 5-1 lists the fields in the Netlet rule. Table 5-1 has three columns. The first column lists the field name. The second column describes the field, and its function in the Netlet rule. The third column lists possible values for that particular field.
Table 5-1 Fields in a Netlet Rule
Parameter
Description
Value
RuleName
Designates a name for this Netlet rule. You need to specify a unique name for each rule. This is useful while defining user access to specific rules. See "Define Access to Netlet Rules" for details.
Encryption Ciphers
Defines the encryption cipher, or specifies the list of ciphers that the user can choose from.
The ciphers that you select appear in the Netlet provider as a list. The user can choose the required ciphers from the selected list.
Default - The Default VM Native Cipher and the Default Java Plugin Cipher specified in the Netlet administration console are used.
URL
Specifies the URL that the browser opens when the user clicks the associated link in the Netlet provider. The browser opens the window for the application and connects to localhost at the local port number specified later in the rule.
You need to specify a relative URL.
URL to the application invoked by the Netlet rule. For example, telnet://localhost:30000.
Specify a URL if the application uses an applet to invoke the application.
null – Value that you set if the application is not started by a URL or controlled by the desktop. This is normally true for non-web-based applications.
Download Applet
Indicates whether it is necessary to download an applet for this rule.
False - Do not download an applet.
True - Download the applet from the Portal Server machine using the loopback port.
Specify the applet details in the format clientport:server:serverport where:
- clientport indicates the destination port on the client. This port must be different from the default loopback port. See Chapter 11, "Configuring the Netlet" for details. Specify a unique client port for each rule.
- server is the name of the server from which to download the applet.
- serverport represents the port on the server used to download the applet.
If an applet is to be downloaded, and if the server is not specified, the applet is downloaded from the Portal Server host.
Extend Session
This controls the idle time-out of a Portal Server session when the Netlet is active.
Enabled - This is required to keep the portal session alive when only the Netlet is active and rest of the portal application is idle.
Disabled - The portal session idle times out at session idle time out even though the Netlet application is active but rest of the portal application is idle.
Client Port
Port on the client where the Netlet listens.
The value of clientport must be unique. You cannot specify a particular port number in more than one rule.
Specify multiple client ports if you are specifying multiple hosts for multiple connections. See "Static Rule With Multiple Host Connections" for the syntax.
For an FTP rule the client port value has to be 30021
Target Host(s)
Recipient of the Netlet connection.
host - Name of the host to receive the Netlet connection. This is used in a static rule. Use either the simple host name such as siroe, or a fully-qualified DNS-style host name such as siroe.mycompany.com. You can specify multiple hosts to:
- establish connection with each host specified. You need to specify the corresponding client and target ports for each host specified. See "Static Rule With Multiple Host Connections" for the syntax.
- try to connect to any available host from the list of hosts specified. See "Static Rule with Multiple Host Selection" for the syntax.
TARGET - Rules that specify TARGET in the syntax are dynamic rules. TARGET indicates that end-users can specify the required destination host or hosts in the Netlet provider of desktop.
You cannot have a combination of a static host and TARGET in a single rule.
Target Port(s)
The port on the target host
In addition to the host and target, you must specify a destination port.
You can specify multiple destination ports in case of multiple destination hosts. Specify multiple ports in the format port1+port2+port3-port4+port5.
The plus (+) sign between ports numbers indicates the alternative ports for a single target host.
The minus (-) sign between port numbers is the separator between the port numbers for different target hosts.
Here, the Netlet tries to connect to the first destination host specified using port1, port2 and port3 in order. If this fails, the Netlet tries to connect to the second host using port4 and port5 in that order.
You can configure multiple ports only for static rules.
Types of Rules
There are two types of Netlet rules based on how the destination host is specified in the rule.
Static Rule
A static rule specifies a destination host as a part of the rule. If you create a static rule, the user does not have the option to specify the required destination host. In the following example, sesta is the destination host.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
ftpstatic
SSL_RSA_WITH_RC4_128_MD5
null
false
true
30021
sesta
21
You can configure multiple target hosts and ports for static rules. See "Static Rule With Multiple Host Connections" for an example.
Dynamic Rule
In a dynamic rule, the destination host is not specified as a part of the rule. The user can specify the required destination host in the Netlet provider. In the following example, TARGET is the placeholder for the destination host.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
ftpdynamic
SSL_RSA_WITH_RC4_128_MD5
null
false
true
30021
TARGET
21
Encryption Ciphers
Based on the encryption cipher, Netlet rules can be further classified as follows:
- User Configurable Cipher Rules - In this rule, you can specify a list of ciphers that users can choose from. These optional ciphers appear as a list in the Netlet provider. The user can choose the required cipher from the list. In the following example, the user can choose from multiple ciphers.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
Telnet
SSL_RSA_WITH_RC4_128_SHA
null
false
true
30000
TARGET
23
SSL_RSA_WITH_RC4_128_MD5
See "Supported Ciphers" for a list of the ciphers supported by the Netlet and the corresponding keywords.
See "Supported Ciphers" for a list of ciphers supported by the Netlet and the corresponding keywords.
Supported Ciphers
Table 5-2 lists the cipher supported by the Netlet in the first column, and the keyword used to associate an cipher in the second column. Use the corresponding keywords to specify the ciphers in the Netlet rules.
Backward Compatibility
Earlier versions of the Portal Server did not support ciphers as part of the Netlet rules. For backward compatibility with existing rules without ciphers, a default cipher is used by the rules. An existing rule without ciphers such as:
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
Telnet
telnet://localhost:30000
false
true
30000
TARGET
23
is interpreted as:
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
Telnet
Default ciphers
telnet://localhost:30000
false
true
30000
TARGET
23
This is similar to an Administrator Configured Rule with the Encryption cipher field chosen as Default. See "Specify the Default Encryption Cipher" for details.
* loopback is used internally by the system.
Netlet Rule Examples
This section contains some examples of Netlet rules to illustrate how Netlet syntax works.
Basic Static Rule
This rule supports a Telnet connection from the client to the machine sesta.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
myrule
SSL_RSA_WITH_RC4_128_MD5
null
false
true
1111
sesta
23
where
myrule is the name of the rule.
SSL_RSA_WITH_RC4_128_MD5 indicates the cipher to be used.
null indicates that this application is not invoked by a URL or run through the desktop.
false indicates that the client does not download an applet to run this application.
true indicates that the Portal Server should not time out when the Netlet connection is active.
1111 is the port on the client where the Netlet listens for a connection request from the target host.
sesta is the name of the recipient host in the Telnet connection.
23 is the port number on the target host for the connection, in this case the well-known port for Telnet.
The desktop Netlet provider does not display a link, but the Netlet automatically starts and listens on the port specified (1111). Instruct the user to start the client software - in this case a Telnet session that connects to localhost on port 1111.
For example, to start the Telnet session, the client needs to type the following on the UNIX command line in a terminal:
Static Rule With Multiple Host Connections
This rule supports a Telnet connection from the client to two machines, sesta and siroe.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
myrule
SSL_RSA_WITH_RC4_128_MD5
null
false
true
1111
sesta
23
1234
siroe
23
where
23 is the port number on the target host for the connection – reserved port for Telnet.
1111 is the port on the client where the Netlet listens for a connection request from the first target host sesta.
1234 is the port on the client where the Netlet listens for a connection request from the second target host siroe.
The first six fields in this rule are the same as in "Basic Static Rule". The difference is that three more fields identify the second target host.
When you add additional targets to a rule, you must add three fields, client port, target host, and target port, for each new target host.
This rule works the same as the previous rule. The Netlet provider does not display any link, but the Netlet automatically starts and listens on the two ports specified (1234). The user needs to start the client software, in this case a Telnet session that connects to localhost on port 1111 or the localhost on port 1234 to connect to host example2.
Static Rule with Multiple Host Selection
Use this rule to specify multiple alternative hosts. If connection to the first host in the rule fails, the Netlet tries to connect to the second host specified and so on.
where
10491 is the port on the client where the Netlet listens for a connection request from the target host.
The Netlet tries to establish connection with siroe on port 35, port 26 and port 491 in the same order, depending on which one is available.
If connections to siroe are not possible, the Netlet tries to connect to sesta on port 35 and 491 in the same order.
Dynamic Rule to Invoke a URL
This rule enables a user to configure the destination host required, enabling the user to telnet to various hosts over the Netlet.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
myrule
SSL_RSA_WITH_RC4_128_MD5
telnet://localhost:30000
false
true
30000
TARGET
23
where
myrule is the name of the rule.
SSL_RSA_WITH_RC4_128_MD5 indicates the cipher to be used.
telnet://localhost:30000 is the URL invoked by the rule.
false indicates that no applets are to be downloaded.
true indicates that the Portal Server should not time out when the Netlet connection is active.
30000 is the port on the client where the Netlet listens for connection requests for this rule.
TARGET indicates that the destination server needs to be configured by the user using the Netlet provider.
23 is the port on the target host opened by the Netlet, in this case the well-known port for Telnet.
To Run the Netlet After a Rule is Added
After this rule is added, the user must complete some steps to get the Netlet running as expected. The user needs to do the following on the client side:
- Click Edit in the Netlet provider section of the Portal Server desktop.
The new Netlet rule is listed under Rule Name in the Add New Target section.
- Choose the rule name and type the name of the target host.
- Save the changes.
The user returns to the desktop with the new link visible in the Netlet provider section.
- Click the new link.
A new browser is launched that goes to the URL given in the Netlet rule.
Dynamic Rule to Download an Applet
This rule defines a GO-Joe connection from the client to hosts that are dynamically allocated. The rule downloads a GO-Joe applet from the server on which the applet is located, to the client.
Rule Name
Encryption Cipher
URL
Downlaod Applet
Extend Session
Client Port
Target Host(s)
Target Port(s)
gojoe
SSL_RSA_WITH_RC4_128_MD5
/gojoe.html
8000:gojoeserve:8080
true
3399
TARGET
58
where
gojoe is the name of the rule.
SSL_RSA_WITH_RC4_128_MD5 indicates the cipher to be used.
/gojoe.html for example is the path of the HTML page containing the applet, the path should be relative to the documentation root of the web container on which portal is deployed.
8000:server:8080 indicates that port 8000 is the destination port on the client to receive the applet, gojoeserve is the name of the server providing the applet, and 8080 is the port on the server from which the applet is downloaded.
Indicates that the Portal Server should not time out when the Netlet connection is active.
3399 is the port on the client where the Netlet listens for connection requests of this type.
TARGET indicates that the destination server needs to be configured by the user using the Netlet provider.
58 is the port on the destination server opened by the Netlet, in this case the port for GoJoe. Port 58 is the port that the target host listens to for its own traffic. The Netlet passes information to this port from the new applet.
Sample Netlet RulesTable 5-3 lists sample Netlet rules for some common applications.
The table has 7 columns corresponding to the following fields in a Netlet rule: Rule Name, URL, Download Applet, Client Port, Target Host, Target Port. The last column includes a description of the rule.
Note
Table 5-3 does not list the Cipher and Extend Session fields of the Netlet rule. Assume these to be "SSL_RSA_WITH_RC4_128_MD5" and "true" for the samples provided.
Enabling Netlet LoggingYou can enable logging of Netlet related activities in the Gateway service. See "Enable Netlet Logging". The log files are created in the directory specified in the Log Location attribute as part of the Logging section of the Identity Server Configuration attributes. The log file name has the following convention:
srapNetlet_gateway hostname_gateway-profile-name
The Netlet log captures the following information:
Terminating the Netlet at LogoutTo terminate the Netlet when the user logs out, the Gateway needs to get the session notification from the Portal Server. To get the notification, do the following:
- Add this line:
com.iplanet.am.jassproxy.trustAllServerCerts=true
to the following property file:
portal-server-install-root/SUNWam/lib/AMConfig.properties on the Portal Server.
- Restart the Gateway from a terminal window:
gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start
- Restart the Portal Server (web server or application server).
Customizing the NetletYou can customize the text that displays in message windows in the Netlet provider and on the administration console for the Netlet service.
- For the Netlet provider, modify:
portal-server-install-root/SUNWam/locale/srapNetletProvider.properties
- For the Netlet service on the Identity Server administration console, modify:
portal-server-install-root/SUNWam/locale/srapNetlet.properties
- For the Netlet servlet, modify:
portal-server-install-root/SUNWam/locale/srapNetletServlet.properties
- For the Netlet applet, modify:
portal-server-install-root/SUNWam/locale/srapNetletApplet.properties
Running Netlet in a Sun Ray EnvironmentIf you want to run an application which requires the applet to be downloaded to the client machine on a Sun Ray environment, you need to change the HTML file. Here is a sample file showing you the necessary modifications that need to be done.
New HTML File
<!-- @(#)citrix_start.html 2.1 98/08/17 Copyright (c) 1998 i-Planet, Inc., All rights reserved. -->
<html>
<script language="JavaScript">
var KEY_VALUES; // KEY_VALUES['key'] = 'value';
function retrieveKeyValues() {
KEY_VALUES = new Object();
var queryString = '' + this.location;
queryString = unescape(queryString);
queryString = queryString.substring((queryString.indexOf('?')) + 1);
if (queryString.length < 1) {
return false; }
var keypairs = new Object();
var numKP = 0;
while (queryString.indexOf('&') > -1) {
keypairs[numKP] = queryString.substring(0,queryString.indexOf('&'));
queryString = queryString.substring((queryString.indexOf('&')) + 1);
numKP++;
}
// Store what's left in the query string as the final keypairs[] data.
keypairs[numKP++] = queryString;
var keyName;
var keyValue;
for (var i=0; i < numKP; ++i) {
keyName = keypairs[i].substring(0,keypairs[i].indexOf('='));
keyValue = keypairs[i].substring((keypairs[i].indexOf('=')) + 1);
while (keyValue.indexOf('+') > -1) {
keyValue = keyValue.substring(0,keyValue.indexOf('+')) + ' ' + keyValue.substring(keyValue.indexOf('+') + 1);
}
keyValue = unescape(keyValue);
// Unescape non-alphanumerics
KEY_VALUES[keyName] = keyValue;
}
}
function getClientPort(serverPort) {
var keyName = "clientPort['" + serverPort +"']";
return KEY_VALUES[keyName];
}
function generateContent() {
retrieveKeyValues();
var newContent =
"<html>\n"
+ "<head></head>\n"
+ "<body>\n"
+ "<applet code=\"com.citrix.JICA.class\" archive=\"JICAEngN.jar\" width=800 height=600>\n"
+ "<param name=\"cabbase\" value=\"JICAEngM.cab\">\n"
+ "<param name=\"address\" value=\"localhost\">\n"
+ "<param name=ICAPortNumber value="
+ getClientPort('1494')
+ ">\n"
+ "</applet>\n"
+ "</body>\n"
+ "</html>\n";
document.write(newContent);
}
</script>
<body onLoad="generateContent();">
</body>
</html>
Deprecated HTML File:
<html>
<body>
<applet code="com.citrix.JICA.class" archive="JICAEngN.jar" width=800 height=600>
<param name="cabbase" value="JICAEngM.cab">
<param name="address" value="localhost">
<param name=ICAPortNumber value=1494>
</applet>
</body>
</html>
