webRDP Java Plugin Guide

Transcription

webRDP Java Plugin Guide
webRDP Java Plugin Guide
© 2014 Stoneware, Inc.
Note:
This document is the property of Stonew are, a Lenovo
company. It is not to be copied, reproduced, or printed
w ithout prior consent from Stonew are, a Lenovo company.
2
webRDP Java Plugin Guide
Table of Contents
Foreword
0
Part I Introduction
3
1 Welcome
................................................................................................................................... 3
2 Overview
................................................................................................................................... 4
3 New in...................................................................................................................................
1.1
5
4 Requirements
................................................................................................................................... 6
7
Part II Features
1 Overview
................................................................................................................................... 7
Part III Installation
12
Part IV Embedded Web Client
16
1 Overview
................................................................................................................................... 16
2 HTML...................................................................................................................................
Deployment
20
3 JSP Deployment
................................................................................................................................... 23
Part V Stand Alone Client
26
1 Deployment
................................................................................................................................... 26
Overview
.......................................................................................................................................................... 29
Part VI PassGen Utility
38
1 Overview
................................................................................................................................... 38
Index
0
© 2014 Stoneware, Inc.
Introduction
1
Introduction
1.1
Welcome
3
The webRDP Java Plug-in is a Java-based client designed to communicate with backend Microsoft
Remote Desktop Services (Terminal Services) and remote Windows desktops using RDP (remote
desktop protocol). The client was specifically designed to improve the performance, reliability,
and functionality of remote desktop connectivity on Windows and non-Windows platforms such
as Linux and Mac OS X. This document will describe how to start, configure, and embed the
webRDP Java Plug-in into your web environment.
© 2014 Stoneware, Inc.
4
1.2
webRDP Java Plugin Guide
Overview
The webRDP Java Plug-in is a new RDP client designed from the "ground up". The client was
written in Sun's (Oracle) Java programming language to provide maximum portability across a
variety of operating system platforms. The webRDP Java Plug-in runs as a stand alone Java
application or an embedded Java applet within a web page or web application.
As a stand alone application, the user can execute the client on any operating system platform
that supports the Sun's (Oracle) Java Virtual Machine. These operating systems would include
Linux (e.g. - Redhat, SuSE, Ubuntu, etc.), Windows (e.g. - XP, Vista, 7, etc.), and Mac OS X (e.g. - 10,
10.5, etc.).
As an embedded applet within another web page or web application, the webRDP Java Plug-in
can be invoked as long as the browser has the Oracle Java plug-in enabled. The user can view the
remote desktop or terminal session within the browser window or within an iframe inside a web
page. This document will describe how the stand alone client is invoked and how the webRDP
Java Plug-in can be embedded into other applications.
© 2014 Stoneware, Inc.
Introduction
1.3
New in 1.1
The webRDP 1.1 client supports the following new features:
Basic webRDP Java Plug-in Features
Fixes for Java 1.7 update 45
New deployment installation package
Domain connections
Cut and Paste
RDP Compression
Resolution Slider and enhanced resolutions
Admin Console option
Advanced webRDP Java Plug-in Features
HTTP(S) Proxy Support
SOCKS 5 Support
Customizable GUI Banner
Customizable Splash Screen
Password Encryption updates
Network Level Authentication with CredSSP and SSL (TLS encryption)
Microsoft Hyper-V Virtual Machine Connection
© 2014 Stoneware, Inc.
5
6
1.4
webRDP Java Plugin Guide
Requirements
Below are the client-side requirements for both the stand alone and embedded versions of the
webRDP Java Plug-in:
Stand Alone
Sun's (Oracle) Java Runtime Environment 1.6, 1.7 - latest revision. Systems using
webRDP 1.1 must be running Java 1.7 update 45 or greater to run webRDP as an applet
due to security issues with Java.
Mac OS X, Windows (XP, Vista, 7, 8,), Windows Server (2003, 2008, 2012)
Embedded
Sun's (Oracle) Java Runtime Environment 1.6, 1.7 - latest revision. Systems using
webRDP 1.1 must be running Java 1.7 update 45 or greater to run webRDP as an applet
due to security issues with Java.
Firefox, Internet Explorer, Chrome, Safari, Opera
* Note - in order to run the advanced version of webRDP the license file must be located in the
same directory as the webRDP.jar file.
© 2014 Stoneware, Inc.
Introduction
2
Features
2.1
Overview
7
A matrix of webRDP features is displayed below.
Feature
Basic Client
Advanced Client
Username/Password
Display Settings
Start Programs
RDP 5 Bulk Compression
Experience
Keep Alive
Admin Console
Cut and Paste
Customizable Banner
Customizable Splash
HTTP(S) Proxy Support
SOCKS 5 Support
Encrypted Password
Password Expiration
Customizable Logo
TLS (SSL) Encryption
Network Level Authentication
MS Hyper-V VM Connect
A description of each webRDP feature is listed below.
Computer (required)
The IP address, DNS name, or machine name of the backend device the webRDP Java
Plug-in will attempt to connect to. The user can pass a non-standard port number (i.e. something other than the default RDP port 3389) by appending ":[port number]" to the
computer name.
Example: mymachine.stone-ware.com:4595
Username
The user ID required to access the device via the remote desktop protocol (RDP). This
parameter is not required. The remote desktop or Terminal Server will prompt if
authentication is required.
Domain
© 2014 Stoneware, Inc.
8
webRDP Java Plugin Guide
The Microsoft domain, NetBios name. This parameter is not required. Entering the
domain allows the RDP connection to connect to a local domain with a domain level account.
Security Options
The webRDP Java Plug-in will connect to a Terminal Server using the desired security and
authentication mode. The default encryption level is Native RDP (least secure) but can be
set to use SSL, uses TLS (1.0, 1.1, 1.2), or set to use Windows Network Level
Authentication. TLS is automatically used when using NLA and supports Credential
Security Source Provider (CredSSP).
Hyper-V Virtual Machine Connect
The webRDP Java Plug-in is able to connect to a Hyper-V manager server For
environments that utilize Microsoft's Hyper-V virtualization software. Enter the IP
address, DNS name, or machine name of the Hyper-V manager server along with the
target virtual machine GUID (e.g. D8556AC93-6744-4854-A6CE-E42E5978A505).
Display
The Display tab controls the screen resolution displayed through the webRDP Java Plugin. The client supports multiple display settings including:
640x480
800x600
1024x768
1280x1024
1440x900
1600x1200
1680x1050
1920x1080
Start Program
The Start Program feature allows the webRDP Java Plug-in to automatically start a specific
application on the backend Terminal Server. The Terminal Server will suppress the
desktop view and only display the application's interface via the connection. This feature
is only available when connecting to a Microsoft Terminal Server.
Start Folder (optional)
Specifies the working directory for the application specified in the Start Program field.
RDP Compression
RDP compression is enabled within the webRDP Java Plug-in to optimize performance
between the client and the backend Terminal Server or remote desktop. The
compression is enabled by default and cannot be disabled on the client. If the host does
© 2014 Stoneware, Inc.
Features
9
not support RDP 5 bulk compression, the client will default back to RDP 4 compression.
Experience
The experience tab will control some of the performance settings associated with
controlling the remote desktop or terminal session. Performance between the webRDP
Java Plug-in and remote desktop can be improved by disabling graphical features of the
remote desktop when creating the RDP session. The performance settings are described
below:
Desktop Background - When checked, the remote desktop or terminal session will
display any desktop background configured on the machine. Often the desktop
background can be very graphic intensive and require the client to redraw the screen
more frequently, thus slowing performance.
Font Smoothing - When checked, the webRDP Java Plug-in will display font smoothing if
enabled on a 2003 Terminal Server or a 2008 Terminal Server. This feature will improve
the visual presentation of desktop windows and text.
Desktop Composition (Vista and Windows 7 feature) - When Desktop Composition is
enabled, individual windows no longer draw directly to the screen or primary display
device as they did in earlier versions of Windows. Instead, their drawing is redirected to
off-screen surfaces in video memory, which are then rendered into a desktop image
and presented on the display. This feature will consume more bandwidth and can be
disabled by removing the check from the box.
Show Contents of Window While Dragging - When checked, the webRDP Java Plug-in
will display the contents of the window being dragged across the desktop interface.
When disabled, the contents of the window are suppressed while being moved within
the desktop. Enabling this option will require more resources and may decrease
performance.
Menu Animation - When checked, the menu animations of the desktop will be
displayed on the remote desktop client. These animations will generate more network
traffic when being sent to the remote desktop client (i.e. -webRDP). Menu animations
can be disabled to reduce communication traffic by disabling the check box.
Themes - When checked, the theme associated with the desktop will be displayed in
the webRDP Java Plug-in. Themes are more graphically intensive and therefore will
generate more traffic between the webRDP Java Plug-in and remote desktop and/or
Terminal Server. To disable the theme within the remote desktop client, uncheck the
box.
Keep Alive
The keep alive option will send a packet to the backend Terminal Server or desktop on a
predetermined interval to stop the device from being disconnected by networking gear
© 2014 Stoneware, Inc.
10
webRDP Java Plugin Guide
(switches, routers, etc.) due to inactivity.
Clipboard Redirection
The webRDP Java Plug-in supports the transfer of text between the remote desktop and
the client using the clipboard feature of the operating system. The default setting is
enabled, unchecked will disable the clipboard feature.
Admin Console
The webRDP Java Plug-in will connect to a Terminal Server in console mode allowing an
administrator to manage the Terminal Server (if allowed)
Customize Banner (Stand-alone Mode)
Allows an administrator to change the default graphic banner displayed at the top of the
webRDP user interface. This feature allows OEMs to replace the shipping graphic banner
with their own branded graphic banner.
Customize Splash Screen (Embedded Client)
Allows the administrator to change the default graphic splash screen that is displayed
when the webRDP Java Plug-in is invoked within a web page or web application.
Proxy Support
The webRDP advanced client supports the use of HTTP(S) Forward Proxy servers. When
enabled, the webRDP Java Plug-in will make requests to the backend Terminal Server or
remote desktop through a designated Proxy. This feature is useful for organizations who
do not wish to expose their internal Terminal Servers or remote desktops to the Internet.
The proxy server's IP Address and Credentials (username/password) can be passed as part
of the RDP connection. Once the connection to the proxy server is accepted, all RDP
traffic will be redirected to the internal Terminal Server or remote desktop.
© 2014 Stoneware, Inc.
Features
11
Chaining - feature allowing two or more proxy servers to be defined when
connecting to a Terminal Server or remote desktop.
SOCKS Support
The webRDP advanced client supports the use of SOCKS 5 proxies. When enabled, the
webRDP Java Plug-in will make requests to the backend Terminal Server or remote
desktop through a designated SOCKS 5 proxy. This feature is useful for organizations who
do not wish to expose their internal Terminal Servers or remote desktops to the Internet.
The SOCKS server's IP Address and Credentials (username/password) can be passed as
part of the RDP connection. Once the connection to the SOCKS proxy is accepted, all RDP
traffic will be redirected to the internal Terminal Server or remote desktop.
Chaining - feature allowing two or more SOCKS servers to be defined when
connecting to a Terminal Server or remote desktop.
* Note - use of clear text username/password is currently supported with SOCKS 5
Did You Know:
You can chain a combination of SOCKS and PROXY servers together. The webRDP
Java Plug-in can connect through a HTTPS proxy server and then through a SOCKS
server to get to a backend RDP session.
Session Select ( Connection Broker )
Session select is a feature by Microsoft designed to connect to an RDP session through a
connection broker. The connection broker will take information from the connection
string and make the connection to a backend RDP session. Session selects version 1 and 2
as described below:
1. Version 1 - ID (32bit integer)
2. Version 2 - ID (32bit integer) and String
Encrypted Password
New feature that allows the webRDP Java Plug-in to pass an encrypted password between
the client and the backend RDP session. The encryption method supports RSA 512 Public
Key/Private Key format. The feature works in stand-alone mode or embedded within a
web page/application. In addition to encrypting the user's password, the administrator
can set an expiration on the password so that it is no longer valid after a given number of
hours.
© 2014 Stoneware, Inc.
12
3
webRDP Java Plugin Guide
Installation
This section will discuss how to install the webRDP Java Plug-in software. Please review the
Before You Start section before beginning.
Before You Start
Download the webRDP Java Plug-in software
Download the webRDP Java Plug-in license
Verify that the system you are installing the webRDP Java Plug-in on meets the
requirements specified in the requirements section
1. Start the installation by clicking on the webRDP-Client.exe. For Linux installations,
navigate to the directory the webRDP-Client.bin file is located, ensure execute
permissions are allowed, and use the ./webRDP-Client.bin command to start the
installation.
2. Introduction. Review the Introduction Screen (below) and select the NEXT button
3. Accept License. Review the license agreement and then select the I ACCEPT radio button if
you agree to the terms. Select the NEXT button when complete.
© 2014 Stoneware, Inc.
Installation
13
4. Installation Directory. Use the CHOOSE button and select the directory where the software
will be installed. The default directory is webRDP. Hit the NEXT button when complete.
The installer package is great for installing webRDP Java Plug-in on a web server, simply
point the installation directory at the web docs or equivalent location on the web server.
5. License File. Use the CHOOSE button to browse and select the webRDP license file. This
file should be sent to the customer after purchase of the product or can be downloaded
© 2014 Stoneware, Inc.
14
webRDP Java Plugin Guide
through the Stoneware customer portal. Select the NEXT button when complete. During
installation the license file is copied to the install location.
6. Shortcut Locations. Choose which location(s) you want the application shortcut to be
created in.
7. Pre-Installation Summary. Review the installation summary and select the INSTALL button
© 2014 Stoneware, Inc.
Installation
to continue.
8. The file installation will proceed.
9. Select the DONE button when the file installation has completed.
© 2014 Stoneware, Inc.
15
16
webRDP Java Plugin Guide
-
The installation has been completed. The webRDP Java Plug-in has been installed. To
launch to the webRDP Java Plug-in, follow the steps below:
1. Locate the webRDP shortcut and click it - this will execute and launch the webRDP.jar
file
2. Locate the webRDP.jar file in the installation directory and click it - this will execute
and launch webRDP directly
3. Other methods of starting webRDP are available, see the "Embedded Web Client" and
"Stand Alone Client" sections for more deployment specific details
4
Embedded Web Client
4.1
Overview
The webRDP Java Plug-in was specifically designed to be embedded within other web
applications and web pages. Any developer can invoke the webRDP Java Plug-in from their web
application or web page by calling the applet and passing the appropriate parameters. The applet
can be invoked within the web page by using the standard applet command:
<applet name='rdp' code='com.webinflection.webrdp.MainApplet' archive='webRDP.jar'
width='100%' height='100%'>
Parameters can be passed by adding the attributes between the applet tags:
© 2014 Stoneware, Inc.
Embedded Web Client
17
<param name='username' value='<%= user %>'>
The parameters that can be passed to the applet tag are listed below:
<host=>
= host IP address or DNS name
<port=>
= host RDP port (default is 3389)
<username=>
= username
<password=>
= user's password
<domain=>
= Terminal Server Domain (optional)
<program=>
= program automatically launched (Terminal Server only)
<directory=>
= set programs working directory (optional)
<height=>
= desktop screen height
<width=>
= desktop screen width
<bpp=>
= desktop color depth (8/15/16/24)
<keepalive=>
= number of seconds between keep alive events (10-300)
<clipboard=>
= specifies if clipboard is enabled
<load-oem-images=> = specifies if OEM images should be loaded
<onlogout=>
= URL to redirect upon disconnect (e.g. http://www.webrdp.com/)
<admin=>
= whether or not to connect to the admin session on a MS Terminal Server
( to enable = Y, T, or 1 )
<setoption=>
= suppress messages from an unexpected disconnect (to enable = set
close-messages-off)
<log-type=>
= 's' sets the the logging type to upload to Stoneware's support servers for
debugging
<log-mode=c> = 'c' sets the logging mode to create a log file on application close
<pflags=>
= performance flags (add the following values to apply multiple
performance flags)
Disable Wallpaper: 1
Disable Full Window Drag: 2
Disable Menu Animations: 4
Disable Theming: 8
Disable Cursor Shadow: 32
Disable Cursor Settings: 64
Example: a setting of 96 would mean Cursor Shadow and Cursor Settings were disabled.
The advanced parameters that can be passed to the applet tag are listed below:
<epassword=>
= encrypted user password
Use the PassGen utility with the advanced client to create the encrypted
password. See the Passgen Utility section for more advanced concepts. To create
an encrypted password, follow the steps below:
© 2014 Stoneware, Inc.
18
webRDP Java Plugin Guide
1.
2.
3.
4.
copy the webRDP.jar, license, and PassGen.jar file into the same directory
Run the PassGen utility at a command line (i.e. - java - jar PassGen.jar)
Enter the password to be encrypted and hit ENTER
Enter the FROM date (0 is a perpetual password that does not expire) and
hit ENTER
5. An encrypted password will be displayed. Copy the password onto the /ep
parameter.
<ss-version=>
or 2)
<ss-id=>
<ss-string=>
only)
<proxy=>
desktop
= version number of session selection method (supports either 1
= the connection ID (must be an integer)
= string that will be passed to the connection broker (version 2
= proxy server used to connect to Terminal Server or remote
Proxy format = (http | https | socks )://user:password@address:
[port]
Example = https://fred:abcpassword@187.2.33.4:8080
Banners and Splash Screens
Your banner must be in JPG format
Your banner should be approximately 1920x1024 pixels in size
Your banner must be named oem_splash.jpg
To replace the default webRDP splash screen follow the steps below:
1. Copy your new splash file (oem_splash.jpg) into the same file system directory as the
webRDP.jar file.
The webRDP.jar file should pickup the new splash screen and display it before the client
connects to the backend system.
* If you have specified a new splash screen the default webRDP logo will not be displayed. You
will need to also specify a logo if desired on the splash screen.
* The splash screen graphic can be cached by the browser and JRE, you may need to flash the
cache of each in testing.
(OEM Only) If you wish to customize the logo displayed in the lower right-hand corner follow
the steps below:
The default logo that is displayed when the webRDP Java Plug-in is embedded in a web page
or application can be customized in the advanced client. This feature is for OEMs that wish to
© 2014 Stoneware, Inc.
Embedded Web Client
19
customize the interface as part of another product offering. To customize the logo, follow the
steps below:
Before You Begin
Your banner must be in JPG format
Your logo should be approximately 1920x1024 pixels in size
Your logo must be named oem_logo.png
To replace the default webRDP splash screen follow the steps below:
1. Copy your new splash file (oem_logo.png) into the same file system directory as the
webRDP.jar file.
The webRDP.jar file should pickup the new logo graphic and display it before the client
connects to the backend system.
* If you customize only the logo, the logo will be displayed in the bottom right-hand corner of
the screen over the default splash screen
* The logo graphic can be cached by the browser and JRE, you may need to flash the cache of
each in testing.
To see full samples, review the HTML Deployment or JSP Deployment sections in this document.
© 2014 Stoneware, Inc.
20
4.2
webRDP Java Plugin Guide
HTML Deployment
This section of the guide is to provide an example for embedding the webRDP Java Plug-in into an
HTML page that runs inside the web browser. Before you begin, you will need to follow the steps
below to deploy the webRDP Java Plug-in jar file.
1. Copy the webRDP.jar file to the HTML docs directory of the web server.
2. Create an HTML page that invokes the webRDP applet
3. Add the parameters that should be passed into the applet when it starts (e.g. - username,
password, applications, screen resolution, etc.)
A sample of an HTML is given below:
<html>
<head>
<title>webRDP&#0153;</title>
<meta http-equiv='content-type' content='text/html; charset=iso-8859-1'>
<meta http-equiv='content-style-type' content='text/css'>
<meta http-equiv='expires' content='Wed, 26 Feb 1997 08:21:57 GMT'>
<meta http-equiv='pragma' content='no-cache'>
<!-- Sets margin around applet -->
<style>
body.swproxyBody { margin:4px;; }
</style>
<script type='text/javascript'>
// The script below is used to move and resize the browser to the full size of the
monitor. Uncomment the two lines below to activate.
// window.moveTo(0,0);
// window.resizeTo( screen.availWidth, screen.availHeight );
// The script below is used to center and resize the browser to a 800 x 600 px
window. Uncomment the lines below to activate.
// var height = 600;
// var width = 800;
// var left = parseInt( ( screen.availWidth/2 ) - ( width /2 ) );
// var top = parseInt( ( screen.availHeight/2 ) - ( height /2 ) );
// window.moveTo( left, top );
// window.resizeTo( width, height );
// This method is called after the user logs out of their RDP session. The method
name is a congfigurable applet parameter.
© 2014 Stoneware, Inc.
Embedded Web Client
21
function rdpOnLogout() {
alert ( ' User has Logged out ' );
}
</script>
</head>
<body class='swproxyBody'>
<!-- Loads the applet and utilizes 100% of browser window width and height. Width and
height could be hard coded to specific values -->
<applet name='rdp' code='com.webinflection.webrdp.MainApplet' archive='webRDP.jar'
width='100%' height='100%'>
<!-- Hostname or IP Address of Terminal Server -->
<!-- This is a required parameter -->
<param name='host' value='10.1.1.25'>
<!-- Port that the Terminal Server -->
<!-- This is a required parameter. -->
<param name='port' value='3389'>
<!-- Username to authenticate to Terminal Server with -->
<!-- Optional SSO Parameter -->
<param name='username' value='joe'>
<!-- Password to authenticate to Terminal Server with -->
<!-- Optional SSO Parameter. If left blank, the Terminal Server will prompt the
user to supply their password.-->
<param name='password' value='cat1dog2'>
<!-- AD Domain name to authenticate to Terminal Server with -->
<!-- Optional SSO Parameter. In some Terminal Server deployments, this
parameter will be required. -->
<param name='domain' value=''>
<!-- Application to start. This value should be url encoded. In this example we are
launching c:\windows\system32\notepad.exe-->
<param name='program' value='c%3A%5Cwindows%5Csystem32%
5Cnotepad.exe'>
<!-- Working directory for Application. This value should be url encoded. In this
example the working directory will be set to c:\windows\system32\ -->
<param name='directory' value='c%3A%5Cwindows%5Csystem32%5C'>
<!-- In this example I used a site ( http://meyerweb.com/eric/tools/dencoder/ ) to
encode the above values -->
© 2014 Stoneware, Inc.
22
webRDP Java Plugin Guide
<!-- This specifies a javascript method to be called after the user logs out of the
RDP session. This stops the session from hanging is a disconnected state. -->
<param name='onlogout' value='rdpOnLogout'>
</applet>
</body>
</html>
© 2014 Stoneware, Inc.
Embedded Web Client
4.3
23
JSP Deployment
This section of the guide is to provide an example for embedding the webRDP Java Plug-in into an
JSP (Java Server Page) that runs inside the web browser. Before you begin, you will need to
follow the steps below to deploy the webRDP Java Plug-in jar file.
1. Copy the webRDP.jar file to the HTML docs directory of the web server.
2. Create a Java Server Page that invokes the webRDP applet
3. Add the parameters that should be passed into the applet when it starts (e.g. - username,
password, applications, screen resolution, etc.)
A sample of a JSP page is given below:
<%@page import="java.net.*"%>
<%
// This example modifies the HTML example and uses the JSP to pass the parameters to the
applet
// We are not really dynamically creating the parameters, but this is where you would make
calls to your configuration apis to get the parmeter values
String host = "10.1.1.25";
String port = "3389";
// Single Sign-on Parameters.
String user = "administrator";
String pass = "stoneware";
String domain = "";
// Published Application Parameters. Remember to URLEncode the program and the directory
String program = URLEncoder.encode( "c:\\windows\\system32\\notepad.exe" );
String directory = URLEncoder.encode( "c:\\windows\\system32\\" );
%>
<!-This example demonstrates RDP SSO ( Single Sign-on ) and a Published Application ( MS
notepad in this case )
-->
<html>
<head>
© 2014 Stoneware, Inc.
24
webRDP Java Plugin Guide
<title>webRDP</title>
<meta http-equiv='content-type' content='text/html; charset=iso-8859-1'>
<meta http-equiv='content-style-type' content='text/css'>
<meta http-equiv='expires' content='Wed, 26 Feb 1997 08:21:57 GMT'>
<meta http-equiv='pragma' content='no-cache'>
<!-- Sets margin around applet -->
<style>
body.swproxyBody { margin:4px;; }
</style>
<script type='text/javascript'>
// The script below is used to move and resize the browser to the full size of the
monitor. Uncomment the two lines below to activate.
// window.moveTo(0,0);
// window.resizeTo( screen.availWidth, screen.availHeight );
// The script below is used to center and resize the browser to a 800 x 600 px
window. Uncomment the lines below to activate.
// var height = 600;
// var width = 800;
// var left = parseInt( ( screen.availWidth/2 ) - ( width /2 ) );
// var top = parseInt( ( screen.availHeight/2 ) - ( height /2 ) );
// window.moveTo( left, top );
// window.resizeTo( width, height );
// This method is called after the user logs out of their RDP session. The method
name is a congfigurable applet parameter.
function rdpOnLogout() {
alert ( ' User has Logged out ' );
}
</script>
</head>
<body class='swproxyBody'>
<!-- Loads the applet and utilizes 100% of browser window width and height. Width and
height could be hard coded to specific values -->
<applet name='rdp' code='com.webinflection.webrdp.MainApplet' archive='webRDP.jar'
width='100%' height='100%'>
<!-- Hostname or IP Address of Terminal Server -->
<!-- This is a required parameter -->
<param name='host' value='<%= host %>'>
© 2014 Stoneware, Inc.
Embedded Web Client
<!-- Port that the Terminal Server -->
<!-- This is a required parameter -->
<param name='port' value='<%= port %>'>
<!-- Username to authenticate to Terminal Server with -->
<!-- Optional SSO Parameter -->
<param name='username' value='<%= user %>'>
<!-- Password to authenticate to Terminal Server with -->
<!-- Optional SSO Parameter -->
<param name='password' value='<%= pass %>'>
<!-- AD Domain name to authenticate to Terminal Server with -->
<!-- Optional SSO Parameter -->
<param name='domain' value='<%= domain %>'>
<!-- Application to start. This value should be url encoded. -->
<param name='program' value='<%= program %>'>
<!-- Working directory for Application. This value should be url encoded. -->
<param name='directory' value='<%= directory %>'>
<!-- This specifies a javascript method to be called after the user logs out of the RDP
session -->
<param name='onlogout' value='rdpOnLogout'>
</applet>
</body>
</html>
© 2014 Stoneware, Inc.
25
26
webRDP Java Plugin Guide
5
Stand Alone Client
5.1
Deployment
The webRDP Java Plug-in can be started in stand-alone (GUI Interface) mode by any of the
following methods:
Double-clicking the webRDP application
With the Java Runtime Environment (JRE) installed on the desktop, the user should be
able to double-click on the webRDP.jar file and have it automatically start on the desktop.
If the application does not automatically start, check the installation of the JRE on the
local machine.
Starting the webRDP application from a command prompt
The user can start the webRDP Java Plug-in from the command line by typing the
following command:
java -jar webRDP.jar
The user can start the webRDP Java Plug-in using a set of command-line parameters. To
view the available command-line parameters start the webRDP Java Plug-in with the /?
option. See below:
java -jar webRDP.jar /?
© 2014 Stoneware, Inc.
Stand Alone Client
27
the screen above is displayed showing all of the currently supported command-line
parameters
Starting the client from a command prompt or terminal session allows the user to pass
optional parameters that would be set from within the interface. An example of starting
the webRDP Java Plug-in with parameters is displayed below:
java -jar webRDP.jar /v:mymachine.stone-ware.com
java -jar webRDP.jar /v:mymachine.stone-ware.com /u:admin /p:letme1n
A list of optional parameters are provided below:
/v:[value]
/u:[value]
/p:[value]
/t:[value]
/wh:[value]
/w:[value]
/h:[value]
/ka:[value]
/a
© 2014 Stoneware, Inc.
= server name and/or port number
= username
= user's password
= startup program
= aspect ratio (width and height)
= screen width
= screen height
= number of seconds between keep alive events (10 - 300)
= enables the connection to a MS Terminal Server
28
webRDP Java Plugin Guide
administrative console
/s:[value]
= disabled unexpected disconnect messages (closemessages-off)
/pf:[value]
= value for the performance flags (add the values below)
Disable Wallpaper: 1
Disable Full Window Drag: 2
Disable Menu Animations: 4
Disable Theming: 8
Disable Cursor Shadow: 32
Disable Cursor Settings: 64
Example: a setting of 96 would mean Cursor Shadow and Cursor Settings were disabled.
A list of advanced webRDP parameters are provided below:
/ep:[password value]
= encrypted user password
Use the PassGen utility that ships with the advanced client to create the
encrypted password. To create an encrypted password, follow the steps below:
1.
2.
3.
4.
copy the webRDP.jar, license, and PassGen.jar file into the same directory
Run the PassGen utility at a command line (i.e. - java - jar PassGen.jar)
Enter the password to be encrypted and hit ENTER
Enter the FROM date (0 is a perpetual password that does not expire) and
hit ENTER
5. An encrypted password will be displayed. Copy the password onto the /ep
parameter.
/ssv:[version number]
(supports either 1 or 2)
/ssid:[connection ID]
/sstr:[connection string]
broker (version 2 only)
/pr:[<proxy>,<proxy>]
or remote desktop
= version number of session selection method
= the connection ID (must be an integer)
= string that will be passed to the connection
= proxy server used to connect to Terminal Server
Proxy format = (http | https | socks )://
user:password@address:[port]
Example = https://
fred:abcpassword@187.2.33.4:8080
© 2014 Stoneware, Inc.
Stand Alone Client
5.1.1
29
Overview
When executed in stand alone mode, the webRDP Java Plug-in will display the user configuration
interface (seen below). The interface allows the end user to configure the backend device,
display resolution, startup programs, and performance settings. Each of these feature categories
is represented by a tab at the top of the interface. The tabs and their purpose are described in
the section below.
General
The General tab allows the user to specify the backend Terminal Server or desktop the
webRDP Java Plug-in will be connecting to. The user will be required to enter the computer
name, IP address, or DNS name in order to connect to any backend system.
Computer (required)
The IP address, DNS name, or machine name of the backend device the webRDP Java
Plug-in will attempt to connect to. The user can pass a non-standard port number (i.e. something other than the default RDP port 3389) by appending ":[port number]" to the
© 2014 Stoneware, Inc.
30
webRDP Java Plugin Guide
computer name.
Example: mymachine.stone-ware.com:4595
Username
The user ID required to access the device via the remote desktop protocol (RDP). This
parameter is not required. The remote desktop or Terminal Server will prompt if
authentication is required.
Domain (optional)
The Microsoft Active Directory domain name of the server (Terminal Services)
Admin Mode
The webRDP Java Plug-in will connect to a Terminal Server in console mode allowing an
administrator to manage the Terminal Server (if allowed)
Security Options
The webRDP Java Plug-in will connect to a Terminal Server using the desired security and
authentication mode. The default encryption level is Native RDP (least secure) but can be
set to use SSL, uses TLS (1.0, 1.1, 1.2), or set to use Windows Network Level
Authentication. TLS is automatically used when using NLA and supports Credential
Security Source Provider (CredSSP).
Hyper-V Virtual Machine Connect
The webRDP Java Plug-in is able to connect to a Hyper-V manager server For
environments that utilize Microsoft's Hyper-V virtualization software. Enter the IP
address, DNS name, or machine name of the Hyper-V manager server along with the
target virtual machine GUID (e.g. D8556AC93-6744-4854-A6CE-E42E5978A505).
Display
The Display tab controls the screen resolution displayed through the webRDP Java Plug-in.
The user can select the "slider" to pick between the various screen resolutions.
© 2014 Stoneware, Inc.
Stand Alone Client
31
The client supports multiple display settings including 640x480, 800x600, 1024x768, and
1280x720, 1280x1024, 1440x900, 1600x1200, 1680x1050, and 1920x1080.
Programs
This feature is only available when connecting to a Microsoft Terminal Server. The programs
tab allows the webRDP Java Plug-in to automatically start a specific application on the
backend Terminal Server. The Terminal Server will suppress the desktop view and only
display the application's interface via the connection.
Start the Program on Connection
When checked, the webRDP Java Plug-in will direct the Terminal Server to start the
application specified on the Program Path / File Name setting. When disabled, the
request from the webRDP Java Plug-in is to view the entire desktop.
Program Path and File Name
The file system path to the application that will be executed remotely on the
Microsoft Terminal Server. The path should be relative to the Terminal Server (i.e. the Terminal Server's local file system) and include the executable's name.
Example: c:\Program Files\Microsoft\Office 11\excel.exe
Start Folder (optional)
© 2014 Stoneware, Inc.
32
webRDP Java Plugin Guide
Specifies the working directory for the application
Experience
The experience tab will control some of the performance settings associated with controlling
the remote desktop or terminal session. Performance between the webRDP Java Plug-in and
remote desktop can be improved by disabling graphical features of the remote desktop when
creating the RDP session. The performance settings are described below:
Desktop Background
When checked, the remote desktop or terminal session will display any desktop
background configured on the machine. Often the desktop background can be very
graphic intensive and require the client to redraw the screen more frequently, thus
slowing performance.
© 2014 Stoneware, Inc.
Stand Alone Client
33
Font Smoothing
When checked, the webRDP Java Plug-in will display font smoothing if enabled on a
2003 Terminal Server or a 2008 Terminal Server. This feature will improve the visual
presentation of desktop windows and text.
Desktop Composition (Vista and Windows 7 feature)
When Desktop Composition is enabled, individual windows no longer draw directly to
the screen or primary display device as they did in earlier versions of Windows.
Instead, their drawing is redirected to off-screen surfaces in video memory, which are
then rendered into a desktop image and presented on the display. This feature will
consume more bandwidth and can be disabled by removing the check from the box.
Show Contents of Window While Dragging
When checked, the webRDP Java Plug-in will display the contents of the window
being dragged across the desktop interface. When disabled, the contents of the
window are suppressed while being moved within the desktop.
Menu Animation
When checked, the menu animations of the desktop will be displayed on the remote
desktop client. These animations will generate more network traffic when being sent
to the remote desktop client (i.e. -webRDP). Menu animations can be disabled to
reduce communication traffic by disabling the check box.
Themes
When checked, the theme associated with the desktop will be displayed in the
webRDP Java Plug-in. Themes are more graphically intensive and therefore will
generate more traffic between the webRDP Java Plug-in and remote desktop and/or
Terminal Server. To disable the theme within the remote desktop client, uncheck the
box.
Keep Alive
The keep alive option will send a packet to the backend Terminal Server or desktop on
a predetermined interval to stop the device from being disconnected. The user can
set the keep alive by checking the box and selecting the number of seconds the
webRDP Java Plug-in should send a keep alive packet.
Clipboard Redirection
Redirects the contents of the workstation clipboard to the remotely controlled
© 2014 Stoneware, Inc.
34
webRDP Java Plugin Guide
Windows device.
Configuring a Proxy Server (Advanced webRDP Java Plug-in Feature)
To connect to a HTTP or HTTPS forward proxy server the user should know the following
information:
Before You Begin
IP Address or DNS name of the forward proxy server
Username and password for the forward proxy (if necessary)
You must still configure the destination remote desktop or Terminal Server on the
General tab
Connecting to a Proxy server
To configure the webRDP Java Plug-in to connect to a remote desktop or Terminal Server
via an HTTP forward proxy, follow the steps below:
1.
2.
3.
4.
From the webRDP interface, select the NETWORK tab
Check the box next to PROXY CONNECTION
Select the ADD button at the bottom of the screen
Enter the proxy server's information
© 2014 Stoneware, Inc.
Stand Alone Client
35
Proxy type - select the type of proxy (HTTP, HTTPS, or SOCKS 5)
Proxy Address - IP Address or DNS name of the proxy server
Port - the port number of the HTTP(S) proxy (default is 8080)
User - a username to authenticate against the proxy server (if required)
Password - a password for the username sent to the proxy server
5. Select the OK button
6. Continue configuring the connection to the backend Terminal Server or remote
desktop through the other tabs (e.g. - general, display, and programs)
When configured correctly, the webRDP Java Plug-in will connect to the proxy server
using the information provided and request the proxy server to communicate with the
backend remote desktop or Terminal Server. The proxy server will send all RDP requests
to the Computer specified on the General tab.
Chained Proxies
Proxy chaining is the process of utilizing two or more proxies to connect to the
backend Terminal Server or remote desktop. The user can enter additional proxies (as
described above) and then specify the order that the client should connect through
the proxy servers using the UP and DOWN buttons. The user can mix the types of
proxy servers in the chain selecting between HTTP, HTTPS, and SOCKS 5.
SOCKS Proxy
Configuring the client to communicate with a SOCKS 5 proxy. To configure the webRDP
Java Plug-in to connect to a remote desktop or Terminal Server via an SOCKS 5 proxy,
follow the steps below:
© 2014 Stoneware, Inc.
36
webRDP Java Plugin Guide
1.
2.
3.
4.
From the webRDP interface, select the NETWORK tab
Check the box next to PROXY CONNECTION
Select the ADD button at the bottom of the screen
Enter the SOCKS proxy's information
Proxy type - select the type of proxy (HTTP, HTTPS, or SOCKS 5)
Proxy Address - IP Address or DNS name of the proxy server
Port - the port number of the SOCKS proxy
User - a username to authenticate against the SOCKS proxy (if required)
Password - a password for the username sent to the SOCKS proxy
7. Select the OK button
© 2014 Stoneware, Inc.
Stand Alone Client
37
8. Continue configuring the connection to the backend Terminal Server or remote
desktop through the other tabs (e.g. - general, display, and programs)
When configured correctly, the webRDP Java Plug-in will connect to the SOCKS proxy
using the information provided and request the SOCKS proxy to communicate with the
backend remote desktop or Terminal Server. The SOCKS proxy will send all RDP requests
to the Computer specified on the General tab.
Chained Proxies
Proxy chaining is the process of utilizing two or more proxies to connect to the
backend Terminal Server or remote desktop. The user can enter additional SOCKS
proxies (as described above) and then specify the order that the client should connect
through the SOCKS proxy using the UP and DOWN buttons. The user can mix the
types of proxy servers in the chain selecting between HTTP, HTTPS, and SOCKS 5.
Banner (webRDP Java Plug-in Feature)
The default banner that is displayed at the top of the webRDP user interface can be
customized in the advanced client. This feature is for OEMs that wish to customize the
interface as part of another product offering. To customize the interface, follow the steps
below:
Before You Begin
Your banner must be in JPG format
Your banner should be approximately 400x70 pixels in size
Your banner must be named oem_banner.jpg
To replace the default webRDP user interface banner follow the steps below:
1. Copy your new banner file (oem_banner.jpg) into the same file system directory as the
webRDP.jar file.
The webRDP.jar file should pickup the new banner and display it inside the user interface.
© 2014 Stoneware, Inc.
38
webRDP Java Plugin Guide
6
PassGen Utility
6.1
Overview
Users with an advanced license can use PassGen to generate an encrypted password for a user
account. It ships with webRDP 1.1 as part of the installation package. The utility can be
downloaded from the Stoneware Customer Portal for versions of webRDP prior to 1.1.
Using PassGen
PassGen.jar is installed in the installation directory chosen in the "Choose Install Folder" step
of the webRDP Java Plug-in installer. The associated javadoc for PassGen is also installed in
this directory. The license (named "license") needs to be placed into the same folder as the
PassGen.jar. Your license file chosen in the "Choose License File" step of the installer is
located (copied) to the installation directory chosen in the "Choose Install Folder" step of the
installation procedure.
PassGen can be used manually or programmatically
To run PassGen manually, enter "java -jar PassGen.jar" into a command line
Example:
C:\webrdp>java -jar PassGen.jar
PassGen version: 1.0.9.18, 2011-07-15 15:43
Host System: Windows 7 6.1
Host Java: 1.7.0
Enter the password to encrypt : <enter password>
Enter the valid from date (0 = perpetual) : 0
The encrypted password it sends back looks like this :
Aasdf343sadf32adfasfdsfwerADFASDF=
Now when launching webRDP as a standalone application you can do:
C:\installation_directory\webrdp>java -jar webrdp.jar /v:myserver.examplecloud.com /u:myusername /ep:Aasdf343sadf32adfasfdsfwerADFASDF=
Or if running the java.jar as an embedded client, the epassword applet tag can be
used as specified in the "Embedded Web Client" section of the webRDP Installation
Guide.
© 2014 Stoneware, Inc.
PassGen Utility
39
To use PassGen programmatically, include PassGen.jar into your project and use the API
documented in the Javadocs supplied with PassGen
Dynamically creating an encrypted password using the PassGen API involves calling
the com.webinflection.webrdp.PassGen.encrypt( String ) method which returns an
encrypted password that can be used while launching the embedded client using a
JSP.
Assuming PassGen.jar is on the classpath, a sample JSP is given below:
<%-- A Simple JSP that Launches webRDP.jar using PassGen --%>
<%@page import="com.webinflection.webrdp.PassGen"%>
<%@page contentType="text/html" pageEncoding="UTF-8"%>
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>JSP Page</title>
</head>
<body>
<applet name='rdp' code='com.webinflection.webrdp.MainApplet' archive='rdp/
webRDP.jar' width="800" height="600">
<!-- Hostname or IP Address of Terminal Server -->
<!-- This is a require parameter -->
<param name='host' value='192.168.1.77'>
<!-- Port that the Terminal Server -->
<!-- This is a require parameter -->
<param name='port' value='3389'>
<!-- Username to authenticate to terminal server with -->
<!-- Optional SSO Parameter -->
<param name='username' value='some_user'>
<%
out.println("<param name='epassword' value='" +
PassGen.encrypt( "password" ) + "'>");
%>
</applet>
</body>
</html>
© 2014 Stoneware, Inc.