webrdp html5 gateway - stoneware …stoneware-docs.s3.amazonaws.com/webrdp-html5... · target...

© 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

................................................................................................................................... 43 Overview

Part II Features 6

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

Part III Requirements 16

Part IV Installation 17

Part V Connecting to the HTML5 Gateway 24

Part VI Security Gateway 25

Part VII Adding a Signed SSL Certificate 26

Part VIII Customizing the Gateway 29

................................................................................................................................... 291 Overview

................................................................................................................................... 302 Custom Branding the Connection Screen

................................................................................................................................... 313 Custom Links

................................................................................................................................... 334 Custom Pages

................................................................................................................................... 345 Sample HTML

Part IX Gateway Services and Parameters 35

................................................................................................................................... 351 Overview

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

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.

Introduction 5


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 Connect

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

Connection Screen

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 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).

Display

The Display tab 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

1440x900

1440x1050

1600x1200

Features 9


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 morenetwork 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.

Features 11


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.

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:

o Plain Text - the parameters are displayed in clear text in the address bar of thebrowser



o 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.

o Expire On - sets the date when the URL will no longer allow the connection to theremote desktop through the gateway

o Dynamic Resize - when checked, the screen will dynamically resize to the client'sdevice (e.g. - smartphone, tablet, desktop, or notebook)

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.

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

Network (Proxy Support)

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.

Features 13


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

o Proxy Address - IP address or DNS name of the proxy server that will be used to accessthe remote Windows desktop or Terminal Server

o Port - the port number the remote proxy server is listening on o User - a valid user ID for the remote proxy server



o 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.

o Proxy Address - IP address or DNS name of the proxy server that will be used to accessthe remote Windows desktop or Terminal Server

o Port - the port number the remote proxy server is listening on o User - a valid user ID for the remote proxy server o 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 webRDP

Features 15


HTML5 Gateway can connect through a HTTPS proxy server and then through aSOCKS server to get to a backend RDP session.

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.

RDP Compression

RDP compression is enabled within the webRDP HTML5 Gateway to optimize performancebetween the client and the backend Terminal Server or remote desktop. Thecompression is enabled by default and cannot be disabled on the client. If the host doesnot support RDP 5 bulk compression, the client will default back to RDP 4 compression.

Encrypted Password

New feature that allows the webRDP HTML5 Gateway to pass an encrypted passwordbetween the client and the backend RDP session. The encryption method supports RSA512 Public 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.



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 17


4 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

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 the

https://customer.stone-ware.com

Installation 19


NEXT button when complete. During installation the license file is copied to the installlocation.

6. webRDP Port Configuration. Check the ENABLE SSL box if you want the gateway to supportHTTPS connections from the browser.

When the Enable SSL box is checked, you will either create a self-signed certificate or



specify 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. Thiskeystore 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.

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 21


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 lessRecommended 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 23


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. To connectto the webRDP HTML5 Gateway, follow the steps below:

1. From another workstation or laptop, open a web browser2. Enter the IP address or DNS server name of the webRDP HTML5 Gateway server3. Enter the connection parameters of an existing Windows desktop with Remote

Desktop Support or a Terminal Server to test and verify the gateway is functional

5 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 HTTPS:

https:\\[IP Address]

Connecting to the HTML5 Gateway 25


For a Modified Port Number

http:\\[IP Address]:[Port Number]

When the user has successfully connected to the webRDP HTML5 Gateway, he should see thedefault screen below. This is the standard connection interface displayed by webRDP HTML5Gateway. A user can enter the connection parameters of the remote Windows desktop or remoteTerminal Server to connect through the gateway.

6 Security Gateway

In addition to enabling any device with an HTML5 browser to connect to a remote Windowssystem, the webRDP HTML5 Gateway can act as a secure gateway to your Windows desktops,Terminal Servers, and VDI systems. As the diagram below demonstrates, the webRDP HTML5Gateway converts the HTML5 over HTTP(S) conversation to an RDP (remote desktop protocol)conversation on the inside of the network. This conversion of protocols is what makes theproduct a true "gateway". The user's session is terminated at the gateway inside the DMZ andthen converted to an RDP session that the remote Windows devices can understand. This featureof the product means that organizations do not have to move their Terminal Servers and VDIsystems into the DMZ 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 from the webRDP HTML5 Gateway server to each device inside the datacenter

3. Follow the instructions for "hardening" the operating system on the server running thegateway. Your OS vendor should supply this information on their support site.

7 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.

Adding a Signed SSL Certificate 27


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 during installationof the product7. RIGHT-CLICK on the WEBRDP key8. Select GENERATE CERTIFICATE REQUEST9. Enter the Password for the Keystore; this is the password you provided during installationof the product10. Save the Certificate Request file to your desktop using the GENERATE button to save therequest 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 contents ofthe certificate request file created in the previous steps and the type of keystore you areusing. 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 will

http://sourceforge.net/projects/portecle

http://sourceforge.net/projects/portecle



respond 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

IMPORTANT: If you get any errors, it may be easier to import the SSL certificates into InternetExplorer and then export them from Internet Explorer. Once complete, you are ready to import them into theKEYSTORE.

**note - If you are obtaining a certificate from DigiCert, you will need to make sure youhave their proper Intermediate Certificate in IE. The easiest method for this is to usetheir Certificate Management Tool: https://www.digicert.com/util/ With this tool, youcan easily import the correct intermediate certificate, which is necessary to build theproper certificate 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.

3. From the Portecle tool, right click on your webRDP keypair and choose IMPORT CA REPLY 4. Select the file from the SSL vendor or the P7B file that you just exported from InternetExplorer 5. You may get a message that says: Click OK, Verify the information about the SSL Certificate;click OK. 6. Select YES when it asks if you want to accept the CA Reply 7. You should see a message that the CA Reply Import Successful. 8. Click FILE | SAVE to save your changes to the keystore 9. You are now done; restart your webRDP HTML5 Gateway

Customizing the Gateway 29


8 Customizing the Gateway

8.1 Overview

The webRDP HTML5 Gateway has been designed to allow organizations such as MSPs, hostedproviders, and IT shops to customize 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 customizable; however, organizations can go beyondcustomizing the connection screen. The webRDP HTML5 Gateway interface allows the customerto change 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 enable a custom connection page on the webRDPHTML5 Gateway and how to create a custom JSP or HTML page.



8.2 Custom Branding the Connection Screen

The webRDP HTML5 Gateway can be branded as part of the installation process. Branding is theprocess by which the default background image and logo on the connection screen are replacedwith custom images. These images can be in the following 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 background or custom logo.

To change the default background, the installer can select the checkbox next to the CustomBackground option and then browse the local machine for the replacement background image.



To change the default logo, the installer can select the checkbox next to the Custom Logo optionand then browse the local machine for the replacement background image.

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.3 Custom Links

The webRDP HTML5 Gateway supports generating custom URLs that can be used and distributed ina 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.



8.4 Custom Pages

Enabling the Custom Connection Page Through the Install Process

During the installation process the Optional Settings screen will be presented with the ability toenable a custom connection screen (see below).

1. Check the USE CUSTOM INDEX.HTML Page

2. Select the BROWSE (...) button

3. Browse and select the custom HTML or JSP page

4. Select the OK button

5. Select the NEXT button

Enabling the Custom Connection Page After the Installation

Enabling a custom connection page after the standard installation process can be accomplished byfollowing the steps below:

1. 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 INDEX.HTML PAGE box and browse for the file to add the

custom page5. Complete the wizard

8.5 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=QUZjNTFlVnQzVG8wRHlGejB6NU0xQWcvZXQyWmI2VElEd2FxTU8vZ2NJMFBFaFRJOHJIU3NBdDJIWWJiSjdMZk4yZENkVXpZYjA1Yy9ldjVBT0tiWVVXRFNXNG4vckFBeW41ZGxsTHF3V3ZRTkx6dnBLSzJGeDZ1TWZmNm5vZDJVUStVY2d1MGoraklLZjliZGg3NGZjWT0=">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>

9 Gateway Services and Parameters

9.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. start?u=JohnDoe&p=mySecretPassword&v=192.168.1.134&pf=15&w=1920&h=955)

encrypt?<GET/POST> = a service that accepts GET or POST request to encrypt a string(returns an encrypted string)

(e.g. encrypt?u=JohnDoe&p=mySecretPassword&v=192.168.1.134&pf=15&expireDateLink=05/16/14&fetchWidthAndHeight=true)

Special Service Parameters

expireDateLink=<MM/dd/yy> = specify the date when encrypted URL should expire



fetchWidthAndHeight=<boolean> = e.g. true/false. when true, uses browsers 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.

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 enabledlo[: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

Gateway Services and Parameters 37


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<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)

http://www.webrdp.com/



Enable Desktop Composition: 256 (Default)

webrdp html5 gateway - stoneware …stoneware-docs.s3.amazonaws.com/webrdp-html5... · target...

Documents