webrdp html5 gateway - amazon web servicesstoneware-docs.s3.amazonaws.com/webrdp-html5... · webrdp...

© 2014 Stoneware, Inc.

webRDP HTML5 Gateway

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.

webRDP HTML5 Gateway2


Table of Contents

Foreword 0

Part I Introduction 3

................................................................................................................................... 31 Welcome

................................................................................................................................... 42 New in 1.1

................................................................................................................................... 53 Overview

Part II Features 6

................................................................................................................................... 61 Overview

Part III Requirements 18

Part IV Security Gateway 19

Part V Installation 21

Part VI Connecting to the HTML5 Gateway 29

................................................................................................................................... 301 Custom Links

Part VII Configuring the Gateway 32

................................................................................................................................... 321 Overview

................................................................................................................................... 342 Configuration Options

Part VIII Adding a Signed SSL Certificate 36

Part IX Using the webRDP Utility Menu 39

................................................................................................................................... 391 Overview

Part X Gateway Services and Parameters 42

................................................................................................................................... 421 Overview

................................................................................................................................... 452 Sample HTML

Part XI Troubleshooting 47

Index 0

Introduction 3


1 Introduction

1.1 Welcome

Thank you for installing the Stoneware webRDP HTML5 Gateway. This document will provide anoverview of the webRDP HTML5 Gateway features and how to install / configure the gateway inyour environment. For more information regarding the webRDP HTML5 Gateway, please visit theStoneware web site at www.webrdp.com.

http://www.webrdp.com



1.2 New in 1.1

The following provides a brief description of what is new in the webRDP HTML5 Gateway. Formore detail information, please refer to the documentation.

Support for Linux operating systems

webRDP HTML5 Gateway supports the installation of the gateway service on Linuxoperating systems

New gateway user interface

HTML5 interface

New mobile view mode for smartphones and tablets

webRDP clipboard

Supports the passing of text between the local device and the remote Windowsdesktop / Terminal Server

URL Generation

Allows the user to generate a URL that can be used to automatically access the remoteWindows desktop. The URL can be embedded into a web page, a web link, or email.

Supports encrypted URLs

Supports time expiration, the URL will no longer be valid after a specified date

Custom Logout URLs

Specifies where (the URL) the end user will be redirected after their remote desktopsession is over

Network Level Authentication

Supports stronger security with CredSSP and SSL (TLS encryption)

Microsoft Hyper-V Virtual Machine Connections

Allows connections to Hyper-V manager virtual machines using a VM GUID

Introduction 5


1.3 Overview

The Stoneware webRDP HTML5 Gateway is a software product designed to connect remote endusers with Windows desktops and Microsoft Terminal Servers using just a web browsers. Theproduct is considered a "gateway" because it translates the HTML5 code within the web browserto Microsoft's Remote Desktop Protocol.

Diagram:

Support: Through this gateway, users can connect to the following Windows systems:

Windows XP, Vista, 7, and 8 Windows Server 2000, 2003, 2008, 2012 Windows Virtual Desktop Systems (with RDP enabled) Microsoft Remote Desktop Services / Terminal Services

Benefits:

No client-side software required No browser plug-in required Access Remote Windows Desktops from desktops, notebooks, tablets, and smartphones Supports most operating systems including Windows, Mac, Linux, iOS, and Android Takes minutes to install and configure Fully customizable for Managed Service Providers, Hosted Service Providers, customdevelopers, and large IT shops



2 Features

2.1 Overview

A matrix of webRDP HTML5 Gateway features is displayed below.

Feature

Username/PasswordDisplay SettingsStart ProgramsRDP 5 Bulk CompressionExperienceKeep AliveAdmin ConsoleCut and PasteCustomizable BannerCustomizable SplashHTTP(S) Proxy SupportSOCKS 5 SupportEncrypted PasswordPassword ExpirationCustomizable LogoClipboard (text only)Mobile Connection ScreenLogout URL URL Generator URL Expiration TLS (SSL) EncryptionNetwork Level AuthenticationMS Hyper-V VM ConnectVirtual Keyboard

A description of each webRDP HTML5 Gateway feature is listed below.

Connection Screen

The connection menu is used to instruct webRDP HTML5 Gateway to connect to a hostcomputer.

Features 7


Computer (required)

The IP address, DNS name, or machine name of the backend device the webRDP HTML5Gateway 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 thecomputer name. In the case of a Hyper-V console connect: enter the IP address, DNSname, or machine name of the Hyper-V manager server along with the target virtualmachine GUID.

Example: mymachine.stone-ware.com:4595

Username

The user ID required to access the Windows machine via the remote desktop protocol(RDP). This parameter is not required. The remote desktop or Terminal Server willprompt if authentication is required.

Domain (Optional, Coming Soon to the webRDP HTML5 Gateway)

For some Terminal Services connections, the user may need to pass the domain name aspart of the authentication process. If required, the domain name of the remote Windowssystem can be entered into this field.



Admin Mode

The webRDP HTML5 Gateway will connect to a Terminal Server in console mode allowingan administrator to manage the Terminal Server (if allowed)

Security Options

The webRDP HTML5 Gateway will connect to a Terminal Server using the desired securityand authentication mode. The default encryption level is Native RDP (least secure) butcan be set to use SSL, uses TLS (1.0, 1.1, 1.2), or set to use Windows Network LevelAuthentication. TLS is automatically used when using NLA and supports CredentialSecurity Source Provider (CredSSP). Hyper-V virtual machine connections automaticallyuse NLA security.

Hyper-V Virtual Machine Connect

The webRDP HTML5 Gateway is able to connect to a Hyper-V manager server Forenvironments that utilize Microsoft's Hyper-V virtualization software. Enter the IPaddress, DNS name, or machine name of the Hyper-V manager server along with thetarget virtual machine GUID (e.g. D8556AC93-6744-4854-A6CE-E42E5978A505). The defaultHyper-V port, 2179, is used however you can specify a different port on the computerfield should Hyper-V be configured to listen on an alternate port, e.g. 192.168.1.1:2180.

Display

The Display menu controls the screen resolution displayed through the webRDP HTML5Gateway. The client supports multiple display settings including:

Fit to Browser (recommended) - automatically determines screen resolution

640x480

800x600

1024x768

1280x720

1280x768

1280x1024

Features 9


1440x900

1440x1050

1600x1200

1680x1050

1920x1080

1920x1200

Start Program

The Start Program feature allows the webRDP HTML5 Gateway to automatically start a specificapplication on the backend Terminal Server. The Terminal Server will suppress the desktopview and only display the application's interface via the connection. This feature is onlyavailable when connecting to a Microsoft Terminal Server.

Start Folder (optional)

Specifies the working directory for the application specified in the Start Program field.

Experience

The experience tab will control some of the performance settings associated withcontrolling the remote desktop or terminal session. Performance between the webRDPHTML5 Gateway and remote desktop can be improved by disabling graphical features ofthe remote desktop when creating the RDP session. The performance settings aredescribed below:



Desktop Background - When checked, the remote desktop or terminal session willdisplay any desktop background configured on the machine. Often the desktopbackground can be very graphic intensive and require the client to redraw the screenmore frequently, thus slowing performance.

Font Smoothing - When checked, the webRDP HTML5 Gateway client will display fontsmoothing if enabled on a 2003 Terminal Server or a 2008 Terminal Server. This featurewill improve the visual presentation of desktop windows and text.

Desktop Composition (Vista and Windows 7 feature) - When Desktop Composition isenabled, individual windows no longer draw directly to the screen or primary displaydevice as they did in earlier versions of Windows. Instead, their drawing is redirected tooff-screen surfaces in video memory, which are then rendered into a desktop imageand presented on the display. This feature will consume more bandwidth and can bedisabled by removing the check from the box.

Show Contents of Window While Dragging - When checked, the webRDP HTML5Gateway will display the contents of the window being dragged across the desktopinterface. When disabled, the contents of the window are suppressed while beingmoved within the desktop. Enabling this option will require more resources and maydecrease performance.

Menu & Windows Animation - When checked, the menu animations of the desktop willbe displayed on the remote desktop client. These animations will generate more

Features 11


network traffic when being sent to the remote desktop client (i.e. -webRDP). Menuanimations can be disabled to reduce communication traffic by disabling the check box.

Visual Styles - When checked, the theme associated with the desktop will be displayedin the webRDP HTML5 Gateway. Themes are more graphically intensive and thereforewill generate more traffic between the webRDP HTML5 Gateway and remote desktopand/or Terminal Server. To disable the theme within the remote desktop client,uncheck the box.

WebRDP Gateway Clipboard (text) - enables the clipboard feature between the localmachine and the remote Windows desktop. When enabled, the text held in theclipboard buffer will be transferred to the other device. Automatically disabled whenusing Hyper-V virtual machine connections.

Keep Alive - the keep alive option will send a packet to the backend Terminal Server ordesktop on a predetermined interval to stop the device from being disconnected. Theuser can set the keep alive by checking the box and selecting the number of secondsthe webRDP HTML5 Gateway should send a keep alive packet.

On Logout

Allows the user to be redirected to a different location (URL) after the remote Windowssession is over. This option designed to be used with the URL Generator, allowing theadministrator to redirect the user back to a specific web page or web site. If no customHTML page is chosen, the URL:PORT location will automatically redirect the user to thewebRDP connection page.

URL - enter the URL that the user will be redirected to when the remote Windowssession is closed.

URL Generator (Launch URL)



The URL Generator allows the user to take all of the various connection parameters (listedabove) and create a URL that will automatically connect to the backend Terminal Server orWindows desktop. The URL can be used in desktop shortcuts, web pages, links, andemails. There are two types of URLs:

Plain Text - the parameters are displayed in clear text in the address bar of thebrowser Encrypted - the parameters are encrypted in the address bar of the web browser. Stoneware suggests always using the encrypted URL. However, the Plain Textversion is useful for troubleshooting. URLs are encrypted using the gateway licenseand require the same license for decrypting.Expire On - sets the date when the URL will no longer allow the connection to theremote desktop through the gatewayDynamic Resize - when checked, the screen will dynamically resize to the client'sdevice (e.g. - smartphone, tablet, desktop, or notebook)

Network (Proxy Support)

Features 13


The webRDP HTML5 Gateway client supports the use of HTTP(S) Forward Proxy servers. When enabled, the webRDP HTML5 Gateway will make requests to the backend TerminalServer or remote desktop through a designated Proxy. This feature is useful fororganizations who do not wish to expose their internal Terminal Servers or remotedesktops to the Internet.

The proxy server's IP Address and Credentials (username/password) can be passed as partof the RDP connection. Once the connection to the proxy server is accepted, all RDPtraffic will be redirected to the internal Terminal Server or remote desktop.

Chaining - feature allowing two or more proxy servers to be defined whenconnecting to a Terminal Server or remote desktop.

HTTP/HTTPS Support



Proxy Address - IP address or DNS name of the proxy server that will be used to accessthe remote Windows desktop or Terminal Server Port - the port number the remote proxy server is listening on User - a valid user ID for the remote proxy server Password - a valid password for the remote proxy server

SOCKS Support

The webRDP advanced client supports the use of SOCKS 5 proxies. When enabled, thewebRDP HTML5 Gateway will make requests to the backend Terminal Server or remotedesktop through a designated SOCKS 5 proxy. This feature is useful for organizations whodo 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 aspart of the RDP connection. Once the connection to the SOCKS proxy is accepted, all RDPtraffic will be redirected to the internal Terminal Server or remote desktop.

Chaining - feature allowing two or more SOCKS servers to be defined whenconnecting to a Terminal Server or remote desktop.

Features 15


Proxy Address - IP address or DNS name of the proxy server that will be used to accessthe remote Windows desktop or Terminal Server Port - the port number the remote proxy server is listening on User - a valid user ID for the remote proxy server Password - a valid password for the remote proxy server

* 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 webRDPHTML5 Gateway can connect through a HTTPS proxy server and then through aSOCKS server to get to a backend RDP session.

About

The About tab shows information pertaining to the webRDP HTML5 Gateway license aswell as version of the client.



Additional Features

Keep Alive

The keep alive option will send a packet to the backend Terminal Server or desktop on apredetermined interval to stop the device from being disconnected by networking gear(switches, routers, etc.) due to inactivity.

Customize Logo

Allows an administrator to change the default graphic logo displayed at the bottom rightof the webRDP HTML5 Gateway connection screen. This feature allows OEMs to replacethe shipping graphic logo with their own branded graphic logo. See the section, CustomBranding the Connection Screen.

Customize Splash Screen

Allows the administrator to change the default graphic splash screen that is displayedwhen the webRDP HTML5 Gateway is invoked within a web page or web application. Seethe section, Custom Branding the Connection Screen.

Features 17


RDP Compression

RDP compression is enabled within the webRDP HTML5 Gateway to optimize performancebetween the client and the Terminal Server or remote desktop. The compression isenabled by default and cannot be disabled on the client. If the host does not support RDP5 bulk compression, the client will default back to RDP 4 compression.

Encrypted Password

Allows the webRDP HTML5 Gateway to pass an encrypted password between the clientand the Terminal Server or remote desktop. The encryption method supports RSA 512Public Key/Private Key format. The feature works in stand-alone mode or embeddedwithin a custom page/application. In addition to encrypting the user's password, theadministrator can set an expiration on the password so that it is no longer valid after agiven number of hours. An advanced license is required to use this feature and the samelicense that was used to encrypt the password must be used to decrypt it.

Session Select ( Connection Broker )

Session select is a feature by Microsoft designed to establish or reestablish RDP sessionsthrough the use of an RD Connection Broker. The connection broker will take informationfrom the RD host and make the connection, or reestablish the connection, to an RDPsession. The connection broker can be configured to load balance sessions. Sessionselects version 1 and 2 as described below:

1. Version 1 - ID (32bit integer)2. Version 2 - ID (32bit integer) and String

Virtual Keyboard

The webRDP HTML5 Gateway is equipped with a virtual keyboard that can be useduniversally across devices. The keyboard is accessed via the webRDP Utility Menu once anRDP connection is established, see Using the webRDP Utility Menu. The following layoutsare supported,

US English

Denmark (DA)



3 Requirements

Below are the requirements for the webRDP HTML5 Gateway:

webRDP HTML5 Gateway Server

The webRDP HTML5 Gateway is a Java application that runs on Windows or Linux servers. Theinitial release of the webRDP HTML5 Gateway was released for Windows server platform.

Windows 2003, 2008, or 2012 Server Linux (Ubuntu, Red Hat, SUSE) Server

64-bit onlyCPU: minimum dual core 2.0 Ghz, recommended quad core 3.5 GhzRAM: minimum 4 Gb, recommended 8 GbHDISK: 300 Mb available disk spaceNetwork: Gigabit+ network interfaceNo other application should be using port 80 or 443 on the server

End User Client

Browsers that supports HTML5 (canvas)

Internet Explorer 9.0, 10.0, 11.0Firefox 17+Chrome 22+Safari 6.0.1+iOS 5.1.1+Android 2.3, 4.0+

Requirements 19


4 Security Gateway

The webRDP HTML5 Gateway can act as a secure gateway to your Windows desktops, TerminalServers, and VDI systems. As the diagram below demonstrates, the webRDP HTML5 Gatewayconverts the HTML5 over HTTP(S) conversation to an RDP (remote desktop protocol) conversationon the inside of the network. This conversion of protocols is what makes the product a true"gateway". The user's session is terminated at the gateway inside the DMZ and then converted toan RDP session that the remote Windows devices can understand. This feature of the productmeans that organizations do not have to move their Terminal Servers and VDI systems into theDMZ or open holes from the outside world (Internet) into the data center.

Setting up the webRDP HTML5 Gateway inside the firewall is very simple. The administratorshould follow the steps below:

1. Open ports 443 and 80 from the Internet to the webRDP HTML5 Gateway server in the DMZ

Port 80 does not need to be opened if the webRDP HTML5 Gateway has been configuredto support SSL

2. Open port 3389 (or alternative RDP port) from the webRDP HTML5 Gateway server to eachdevice inside the data center

3. Your OS vendor should supply instructions for "hardening" the operating system on theserver running the webRDP HTML5 Gateway, please refer to their support page

Security Gateway 21


5 Installation

This section will discuss how to install the webRDP software in Gateway Mode. Please reviewthe Before You Start section before beginning.

Before You Start

Download the webRDP HTML5 Gateway software Download the webRDP HTML5 Gateway license Verify that the system you are installing the gateway on meets the requirements specifiedin the requirements section Verify that the account you are installing with has Administrator privileges to the system

1. Start the webRDP Installation by clicking on the webRDP-Gateway.exe. For Linuxinstallations, navigate to the directory the webRDP-Gateway.bin file is located, ensureexecute permissions are allowed, and use the ./webRDP-Client.bin command to start theinstallation from a command terminal.

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 ifyou agree to the terms. Select the NEXT button when complete.



4. Installation Directory. Use the CHOOSE button and select the directory where the webRDPsoftware will be installed. The default directory is webRDP-Gateway. Hit the NEXT buttonwhen complete.

5. License File. Use the CHOOSE button to browse and select the webRDP license file. Thisfile should be sent to the customer after purchase of the product or can be downloadedthrough the Stoneware customer portal, https://customer.stone-ware.com. Select theNEXT button when complete. During installation the license file is copied to the installlocation.

https://customer.stone-ware.com

Installation 23


6. webRDP Port & IP Configuration. Check the ENABLE SSL box if you want the gateway tosupport HTTPS connections from the browser. You can bind to any port or IP. The defaultsare port 80 and all IP interfaces.

When the Enable SSL box is checked, you will either create a self-signed certificate orspecify an existing keystore with a signed certificate. The directions for each are below:

Self Signed Certificate

This option will create a keystore that will allow the gateway to support SSL. This



keystore is "self signed", therefore the user will be prompted with the warningabout the SSL certificate prior to connecting with the browser to the gateway. Seethe Adding a Signed SSL Certificate section on how to request and install a validSSL certificate on the gateway. Certificates generated by the webRDP HTML5Gateway will use RSA and 2048 bit strength, this is recommended for valid SSLcertificates as well.

6a. Enter the Internet domain name for the server (e.g. - stone-ware.com)

6b. Enter the Keystore password, since it is creating a new keystore, you aresetting a new password. Please write it down, remember it.

6c. Enter the Keystore password again, hope you remembered it.

Existing Keystore

Use this option when you have an existing keystore that has a valid importedcertificate.

6a. Select the BROWSE button and locate the keystore file

6b. Enter the Keystore's password

6c. Re-enter the Keystore's password

Select the NEXT button to continue.

7. Optional Settings. This option allows the administrator to customize the HTML5 gatewayconfiguration. The options are described below. When customization is complete, selectthe NEXT button to continue.

Installation 25


Custom Index.html Page

This option allows the administrator to replace the default index page with thestandard connection screen with another customized web page. The page can bereplaced to create new interfaces, automatically connect users to a specific system,add new logic into the connection process, automatically login, etc. Please see thesection on Custom Pages later in the guide.

Custom Background Image

This option allows the administrator to specify a different default background/splashscreen on the webRDP Gateway connection page. Check the CUSTOM BACKGROUNDIMAGE and select the BROWSE icon and select the image that will replace the defaultbackground. Background image guidelines are provided below:

Supports PNG and JPG image formatsRecommended image size should be 100k or lessRecommended dimensions are 1920x768 pixels

Custom Logo

This option allows the administrator to specify a different product logo. Organizationscan place their logo on the authentication and connection page. Check the CUSTOMLOGO IMAGE and select the BROWSE icon to select the image that will replace thedefault logo. Logo image guidelines are provided below:

Supports PNG and JPG image formatsRecommended image size should be 50k or less



Recommended dimensions are 100x100 pixels

Select the NEXT button when complete.

8. Firewall Note. If you are installing the HTML5 Gateway in a DMZ, please review theSecurity Gateway section. Select the NEXT button to continue.

9. Pre-Installation Summary. Review the installation summary and select the INSTALL buttonto continue.

Installation 27


10. The file installation will proceed.

11. Select the DONE button when the file installation has completed.



-

The installation has been completed. The webRDP HTML5 Gateway has been installed asa Windows service (webRDP-Gateway) and can be set to start automatically.

Installation 29


6 Connecting to the HTML5 Gateway

By default, the webRDP HTML5 Gateway runs over HTTP on port 80. This is the default protocoland port for web traffic and therefore can be accessed by typing the IP address or DNS name ofthe server running the webRDP HTML5 Gateway in the web browser's address field.

If the person installing the webRDP HTML5 Gateway has selected a different protocol (i.e. -HTTPS) or port number (e.g. - 8088), the end user will need to connect using a different URL.

For HTTP(S):

http(s):\\[IP Address/DNS]

For a Modified Port Number

http(s):\\[IP Address/DNS]:[Port Number]

After the user has successfully installed the webRDP HTML5 Gateway and navigated to the correctaddress, the default connection screen is displayed, see below.

This is the standard connection screen interface displayed by webRDP HTML5 Gateway. A usercan now enter the connection parameters of the targeted remote Windows desktop or TerminalServer to connect to.



6.1 Custom Links

The webRDP HTML5 Gateway also supports generating custom connection URLs that can be usedand distributed in a number of ways such as in email, embedded page links, or custom pages.

Creating Custom Links

1. Enter connection parameters using the gateway connection screen2. After configuring the connection and any other parameters navigate to the Launch URL

menu (as shown above)3. Set an expiration date for the link or leave blank for no expiration4. Select GENERATE URL5. Two URLs will be generated one is in clear text the other is encrypted

Did You Know:

Custom links can be used in conjunction with custom pages.

Connecting to the HTML5 Gateway 31




7 Configuring the Gateway

7.1 Overview

The webRDP HTML5 Gateway has been designed to allow organizations such as MSPs, hostedproviders, and IT shops to configure the gateway to create their own unique solution. This allowsorganizations to add their own themes and business logic to the connection process for improvedsecurity, device selection, simplified login, etc. with HTML, Javascript, or Java Server Page (JSP)code.

Out of the box, the standard webRDP HTML5 Gateway connection process is displayed below. Theuser enters the IP address or DNS name of the webRDP HTML5 Gateway. The gateway displaysthe connection screen to the end user. The user must enter the information required to connectto the remote Windows device (i.e. - Remote Windows IP address, username, password, etc.). Once the correct information has been entered, the webRDP HTML5 Gateway will connect theuser to the remote Windows device. In each case, the user must know which Windows devicethey wish to connect to, its address, the proper authentication credentials and the desiredconnection parameters.

The provided connection screen is configurable; however, organizations can go beyondconfiguring the connection screen. The webRDP HTML5 Gateway interface allows the customer tocustomize the logic surrounding the connection process. As shown below, the standardconnection screen is replaced by a custom connection page (HTML or JSP) that executes its ownlogic before connecting to the back-end Windows device.

The rest of this chapter will discuss how to configure, set, a custom connection page on thewebRDP HTML5 Gateway .

Configuring the Gateway 33




7.2 Configuration Options

The webRDP HTML5 Gateway can be branded as part of the installation process or after theinstallation (simply rerun the installer). Branding is the process by which the default connectionscreen, background image and logo on are replaced with custom pages and images.

Supported Image Formats:

PNG JPG GIF

Note:

Be careful when adding custom images. You should always try to minimize the size ofyour custom images to maximize the performance of the connection page loading insidethe user's browser. Stoneware recommends that the background image be less than100kb and the logo be less than 50kb.

During the installation process there will be an OPTIONAL SETTINGS screen that allows theinstaller to select either a custom page, background or custom logo.

To change the defaults, select the check box next to the option(s) and then browse the local

Configuring the Gateway 35


machine for the replacement page, background or logo.

Advanced

The custom background and logo images are placed within the product directory during theinstallation process. If you wish to update or change these images at any time, follow the stepsbelow:

Updating the Image1. Locate the webRDP HTML5 Gateway installation file2. Run the installation file3. Step through the installer wizard until you get to the OPTIONAL SETTINGS screen (as

seen above)4. Check the USE CUSTOM BACKGROUND IMAGE box and browse for the image to add the

custom background5. Check the USE CUSTOM LOGO box and browse for the logo to add the custom logo 6. Complete the wizard

Note:

The installation package will determine if a webRDP HTML5 Gateway installation ispresent, populate the current installations configuration settings, and bypass theCHOOSE INSTALL FOLDER and SELECT LICENSE FILE install panels. Also, the installationpackage will automatically stop the webRDP HTML5 Gateway service during configurationand restart once completed. Rerunning the installer will NOT cause you to lose yourcustomized settings. You will see as you run the installer that your current configurationoptions are already saved. To simplify configuration changes Stoneware provides theinstaller wizard to step you through these changes should you need to make them.

To disable the custom image you must rerun the installer and uncheck use custom image and logo.



8 Adding a Signed SSL Certificate

By default, when enabling SSL (Secure Socket Layer) on the webRDP HTML5 Gateway the SSLcertificate is "unsigned". This means that it is not trusted by a Certificate of Authority and willdisplay a message to the end users stating the "site is untrusted/protected, do you wish tocontinue?". Stoneware recommends that customers acquire a signed SSL Certificate for thewebRDP HTML5 Gateway when enabling SSL. There are many vendors that provide SSLcertificates. The documentation below describes how to request and import an SSL certificate.

Before You Begin

This example will use Portecle, it is a tool for viewing and modifying keystores. You candownload this tool from the following URL: Download Portecle from http://sourceforge.net/projects/portecle

Enabling an SSL Certificate is a three step process:

1. Creating a Certificate Request2. Importing Certificates from the Certificate of Authority3. Verifying SSL is enabled with a Trusted SSL Certificate

Creating a Certificate Request

This step will generate a certificate request that can be used by an SSL vendor to generate avalid SSL certificate.

1. Run the Portecle tool 2. Select FILE | OPEN KEYSTORE FILE3. Browse to the /webRDP-Gateway/jetty/etc directory4. Select the KEYSTORE file (file Type will be All Files)5. Select the OPEN button6. Enter the Password for the Keystore; this is the password you provided duringinstallation of the product7. RIGHT-CLICK on the WEBRDP key8. Select GENERATE CERTIFICATE REQUEST9. Enter the Password for the Keystore; this is the password you provided duringinstallation of the product10. Save the Certificate Request file to your desktop using the GENERATE button to savethe request file

Requesting an SSL Certificate

There are several SSL Certificate vendors to select from including GoDaddy, RapidSSL,GeoTrust, Thawte, etc. In each case you will need to provide the vendor with the contentsof the certificate request file created in the previous steps and the type of keystore you are

http://sourceforge.net/projects/portecle

http://sourceforge.net/projects/portecle

Adding a Signed SSL Certificate 37


using. When asked by the vendor for the type of keystore, you can reply with TOMCAT orJETTY.

Importing the SSL Certificate

Once the SSL vendor has successfully fulfilled your request for an SSL certificate, they willrespond back with a set of one or more files. These files will include the actual certificateresponse and one or more root/intermediate certificates. Follow the instructions below toimport the certificate response and the intermediate certificates into the keystore.

If your CA sent you one or more intermediate or root certificates then those will need to beimported.

1. From Portecle (with the keystore open) click on TOOLS, and then IMPORT TRUSTEDCERTIFICATE 2. Select your Intermediate / Root certificates that you were sent via email or told todownload

Note:

IMPORTANT: If you get any errors, it may be easier to import the SSL certificates intoInternet Explorer and then export them from Internet Explorer. Once complete, you are ready to import them intothe KEYSTORE. Be careful when adding custom images.

If you are obtaining a certificate from DigiCert, you will need to make sure you have theirproper Intermediate Certificate in IE. The easiest method for this is to use theirCertificate Management Tool: https://www.digicert.com/util/ With this tool, you caneasily import the correct intermediate certificate, which is necessary to build the propercertificate chain.

Take the certificate you were sent, open Internet Explorer and go to :

1. Tool | Internet Options | Content | Certificates |Import2. Select the certificate you were sent from your CA.3. Once imported, find the certificate usually located under the Other People tab.4. Right click on it and choose Export, select Cryptographic Message Syntax Standard PKCS

#7 option. 5. Select Include all certificates in the certification path if possible. 6. Save this file so you can import it into Keystore.

7. From the Portecle tool, right click on your webRDP keypair and choose IMPORT CAREPLY

8. Select the file from the SSL vendor or the P7B file that you just exported from Internet



Explorer9. You may get a message that says: Click OK, Verify the information about the SSL

Certificate; click OK10.Select YES when it asks if you want to accept the CA Reply11.You should see a message that the CA Reply Import Successful12.Click FILE | SAVE to save your changes to the keystore13.You are now done; restart your webRDP HTML5 Gateway

Adding a Signed SSL Certificate 39


9 Using the webRDP Utility Menu

9.1 Overview

The webRDP Utility Menu allows access to additional connection functionality found in thewebRDP HTML5 Gateway. Access to the webRDP Clipboard, Application and System keyboard, aswell as access to Scroll and Zoom options can be found in the menu.

webRDP Utility Menu

The menu is centered and located at the top of the connection window: . Selectingthe menu will expand to reveal the full utility menu.

webRDP Clipboard

The webRDP HTML5 Gateway supports text copy and paste from local to remote as well asremote to local host. This is accomplished by interacting with the webRDP clipboard.

Local to remote host copy and paste

1. On the local host, highlight the targeted text and copy it to the local clipboard (Ctl+C, orright-click copy)

2. To send the contents of the local clipboard to the remote computer, paste the text intothe webRDP Clipboard text box

3. Once the text has been pasted, select "Send to remote" (this will send the text to theremote host's local clipboard)

4. On the remote host you can now paste the copied text (Ctl-V, or right-click paste)

Remote host to local host copy and paste

1. On the remote host, highlight the targeted text and copy it to the remote host



clipboard (Ctl+C, or right-click copy)2. To send the contents of the remote host clipboard to the local host computer, select

"Retrieve from remote" (this will send the text to the webRDP Clipboard)3. From the webRDP Clipboard text box, copy the retrieved text (Ctl+C, or right-click copy,

this will load the local host clipboard with the contents retrieved from the remotehost)

4. Once the retrieved text is copied, you can now paste the contents on the local host (Ctl+V, or right-click paste)

Did you know:

Three clipboards are at play when using the webRDP HTML5 Gateway to copy and pastetext. The local host clipboard, the webRDP clipboard, and the remote host clipboard. The reason for this is because the webRDP clipboard acts like a clipboard broker. In orderto get text from one computer to another you must interact with the broker, webRDPclipboard.

Keyboard

When connecting with touch enabled devices two keyboard types are supported theApplication (virtual) and System keyboard. The Application keyboard is a virtual keyboardand is available regardless of browser and operating system. The system keyboard is thenative touch keyboard provided by the connecting device.

Selecting a keyboard to use

1. Open the webRDP Utility Menu2. Select the drop down on the left side of the "Keyboard" button will reveal the

keyboard options3. To use the Application keyboard select Application, to use the device keyboard select

System

Did you know:

The Application keyboard supports special Window keys and key combinations such asWin, F1-F12, Ctl Alt Delete, Ctl+C and Ctl+V.

Using the webRDP Utility Menu 41


Supported Application Keyboard Layouts

US English

Denmark (DA)

Note: keyboard layouts require the correct language be configured on both the connectinghost browser as well as the OS of the target host.

Scroll & Zoom Options

webRDP HTML5 Gateway supports screen scroll and zoom when connecting with touchdevices (e.g. iOS, Android devices).

Scroll mode

o Initial connections are fully zoomed out and scroll is disabledo Scroll is enabled automatically when zooming in and outo To turn on/off Scroll select the Scroll button, an on/off message will appear indicating

the statuso Some touch functionality is disabled while Scroll is on: touch (hold) and drag, touch

(hold) and release (right-click)

Zoom

1. Select Zoom In to zoom in on a page2. Select Zoom Out to zoom out of a page

Note: when the Zoom option is grayed out you have reached the maximum zoom level



10 Gateway Services and Parameters

10.1 Overview

The webRDP HTML5 Gateway was specifically designed to be embedded within other webapplications, web pages, and custom pages. Any developer can invoke the webRDP HTML5Gateway from their web application or web page by calling the services and passing theappropriate parameters. The webRDP HTML5 Gateway services can be invoked by using thefollowing commands:

Services (HTML5 only services)

start?<GET/POST> = a service that accepts GET or POST request to starts the HTML5session

(e.g. https://gatewayaddress/webRDP/start?u=JohnDoe&p=mySecretPassword&v=192.168.1.134&pf=15&w=1920&h=955)

(e.g. https://gatewayaddress/webRDP/start?e=AMIqX9i5vE/vPmhJXys1Wy6rZOZUsYx8Cr3lfzCnr=)

encrypt<POST> = a service that accepts a POST request to encrypt a string (returnsan encrypted string)

(e.g. https://gatewayaddress/webRDP/encryptParams{"cryptoData":"v=192.168.1.1&u=username&p=password&a=false&sec=rdp&clipboard=on&pf=15&fetchWidthAndHeight=true"}returns e=AMIqX9i5vE/vPmhJXys1Wy6rZOZUsYx8Cr3lfzCnr=)

Special Service Parameters

expireDateLink=<MM/dd/yy> = specify the date when encrypted URL should expirefetchWidthAndHeight=<boolean> = e.g. true/false. when true, uses browser's width andheight of the connecting devicee=<string> = accepts an encrypted string and then starts HTML5webRDP session

(e.g. e=AMIqX9i5vE/vPmhJXys1Wy6rZOZUsYx8Cr3clfzCnr=)

Did You Know:

All console mode tags/parameters work with the webRDP HTML5 Gateway as well as thewebRDP Java applet.

Gateway Services and Parameters 43


Console Mode Parameters

webRDP [/v:<server[:port]>] [/u:<username>] [/p:<password>] [<parameters>]

v:<server[:port]> = host IP address and portu:<username> = user login namep:<password> = user login passwordl:<program> = launch programd:<directory> = launch program work directorya[:<boolean>] = whether to connect to the admin session or nots:<option> = sets an option (see the documentation for available options)w:<width> = session screen widthh:<height> = requested session screen heightwh:<width> = set dimensions to common aspect ratios (640/800/1024...)ka:<seconds> = number of seconds between keep alive events (10=300)cb[:boolean>] = specifies if clipboard is enabled, true (default) or falselo[:boolean] = specifies if OEM images should be loadedpf:<value> = value for the performance flags (add the values below)mm:[:boolean] = specifies if multiple monitors should be used (not valid for HTML 5 orapplet)epr:<string> = encrypted proxy string (e.g. http://proxyuser:[email protected]:8080 but encrypted)lt:<s> = 's' sets the the logging type to upload to Stoneware's support servers fordebugginglm:<c> = 'c' sets the logging mode to create a log file on application closesec:<value> = value for the security option: rdp (default), ssl, nla (ssl implied)sstr:<value> = specifies Hyper=V console connect mode enter a GUID value for theHyper=V host (e.g. 4DB01A8B=C35C=47D7=9DE6=9922B1BD8004, uses NLA by default)

Advanced Commands

ep:<password> = user login password (encrypted)ssv:<version> = the session selection version (must be 1 or 2)ssid:<id> = the connection id to use (must be numeric)ssstr:<string> = the connection string to use (version 2 only)pr:<proxy[,proxy]> = proxy servers used to connect to the host

Proxy format: (http | https | socks)://[user:password@]address[:port]Example: http://proxyuser:[email protected]:8080

Applet Tags

<host=> = host IP address<port=> = host RDP port



<username=> = login username<password=> = login user password<domain=> = login domain<program=> = launch program<directory=> = launch program work directory<admin=> = whether to connect to the admin session or not<setoption=> = sets an option (see the documentation for available options)<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, true (default) or false<load-oem-images=> = specifies if OEM images should be loaded<pflags=> = value for the performance flags (add the values below)<onlogout=> = URL to redirect upon disconnect (e.g. http://www.webrdp.com/)<log-type=> = 's' sets the the logging type to upload to Stoneware's support servers fordebugging <log-mode=> = 'c' sets the logging mode to create a log file on application close

Advanced Applet Tags

<epassword=> = login user password (encrypted)<ss-version=> = the session selection version (must be 1 or 2)<ss-id=> = the connection id to use (must be numeric)<ss-string=> = the connection string to use (version 2 only)<proxy=> = comma separated list of proxy servers (format above)

Performance Flag Values

Disable Wallpaper: 1Disable Full Window Drag: 2 (Default)Disable Menu Animations: 4Disable Theming: 8Enable Font Smoothing: 128 (Default)Enable Desktop Composition: 256 (Default)

http://www.webrdp.com/

10.2 Sample HTML

<html><head>

<title>Custom webRDP Page</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'>

<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 themonitor. Remove the comment from 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 800 x 600 pixelswindow. Remove the comments from 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 );

</script></head>

<body class='swproxyBody'> <h2>Select where to connect</h2> <a href="http://localhost/webRDP/start?e=QU15dGl3SndFeWJVa0FPOWxHQzUyNTBoMW1Uc1R3WnpqYm12N3BtUmlRSm5maHdoUUl1S2Juczhxd2NRNmhwbmtwQkYxNmxnV2hSbVluYlBMUTJtVHo0TjRiNXVqWFNiZ0J3M0cxSmJQa1pZSlJET3hHNHZVNzQzWlIxS2t1R0F2ZW5FYlVJSmtqbmN1SUtLZVJCMFM1bz0=">Sales Server</a> <br> <a href="http://localhost/webRDP/start?e=QUZjNTFlVnQzVG8wRHlGejB6NU0xQWcvZXQyWmI2VElEd2FxTU8vZ2NJMFBFaFRJOHJIU3NBdDJIWWJiSjdMZk4yZENkVXpZYjA1Yy9ldjVBT0tiWVVXRFNXNG4vckFBeW41ZGxsTHF3V3ZRTkx6dnBLSzJ



GeDZ1TWZmNm5vZDJVUStVY2d1MGoraklLZjliZGg3NGZjWT0=">Support Server</a> <br> <a href="http://192.168.1.152/webRDP/start?v=192.168.1.125&u=testuser&p=password&a=false&clipboard=on&pf=15&w=791&h=696">TestServer</a> <br>

</body></html>

11 Troubleshooting

The webRDP HTML5 Gateway comes equipped with the ability to log errors and warnings whichcan assist in troubleshooting and debugging connections. These logs are written out to fileswhich can be found in the webRDP HTML5 Gateway install directory (default: \webRDP-Gateway\jetty\logs\). Administrators can also adjust the image compression levels on the gateway toimprove performance.

Troubleshooting Using Logs

1. When troubleshooting the gateway using log files, first update the parameters shownbelow in either the desktop.jsp or mobile.html file as appropriate. Removing commenttags where appropriate.











2. We suggest using the following settings as a good place to start:

<input name="log-mode" value="c" type="hidden"/><input name="log-type" value="i" type="hidden"/>

3. Next connect using the connection page, using the updated log settings, or connect usingthe following URL:

http://<host>:<port>/webRDP/start?v=<remote_machine_IP>&u=<username>&p=<password>&a=false&clipboard=on&pf=15&fetchWidthAndHeight=1&log-mode=c&log-type=i



4. Once connected log out or end the session. Closing the tab or browser will work, but itwill take extra time for the webRDP HTML5 Gateway to notice the connection was brokenand then generate the logs.

5. Look in C:\webRDP-Gateway\jetty\logs\ for the latest log (e.g. 2014_01_01.stderrout.log). The stderrout.log contains basic information about connections being made or possiblyany errors.

6. Open the log and look at the bottom. You will see an entry similar to the following:

Generating individual log files into C:\Users\<User Account>\AppData\Local\Temp\

7. Go to that directory and there will be more log files:

webRDP_detailed_20140101.logwebRDP_overview_20140101.logwebRDP_comm_20140101.log (if log-comm option was not set to true, this file won’texist)

8. Pay close attention for errors that begin with the following messages:

Invalid parameters - provided parameters are not accepted, recognized, orformatted correctly

Missing parameters - parameters not provided but required by the receiving server

Error loading license - either missing, incorrect, or expired license file

Invalid authentication - the authentication credentials are incorrect or the serverbeing contacted does not support or requires a specific type of authentication (e.g.Network Level Authentication)

Security SSL connection failed, invalid certificate - improperly formed certificate

Improving Performance

The webRDP HTML5 Gateway uses an optimized image compression. IT can adjust thecompression level to optimize server or network resources. Please refer to our Stonewarehelpdesk site (helpdesk.stone-ware.com) and search for "How to adjust webRDP compression".

webrdp html5 gateway - amazon web servicesstoneware-docs.s3.amazonaws.com/webrdp-html5... · webrdp...

Documents