Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
In the following example we'll put together a very simple browser-based application launcher that uses the RAS Web Client.
Before we begin, let's make sure that our RAS Secure Gateway configuration meets the requirements:
In the RAS Console, navigate to Farm > <Site> > Gateways.
Right-click a Gateway and click Properties.
In the Properties tab, make sure that the Enable RAS Secure Gateway in site option is selected.
In the User Portal tab, make sure that the Enable User Portal option is selected.
Make sure that the Web Client opens in your default web browser.
We are now ready to create our custom resource launcher. In this example, we are making the following assumptions:
Our Secure Gateway is running on the server with the following IP address: 192.168.10.10.
Our web server is running on the server 192.168.20.20.
The published resource that we'll be launching is Google Chrome and it's ID the in the RAS Console is "#4".
You can look up the ID in the RAS Console (Publishing > select a resource > Information tab > look at the first field on the tab page, which displays the resource ID followed by resource name). Note that the pound sign (#
) must be included together with the actual ID. You can also obtain a resource ID via RAS PowerShell by executing Get-RASPubItem "resource-name"
. The returned PubItem
object has the Id property that specifies the resource ID. To get the list of all available published resources, execute the Get-RASPubItem
cmdlet with no parameters.
First we need to create a JSON payload containing user credentials and the application info. To do so, open a text editor and type (or paste) the following:
In the payload above, substitute 'user-name' and 'user-password' with your own. Change the "a:" parameter value to the ID of the published application that you wish to launch. Save the payload as a text file with the ".js" extension in the folder on your web server. In our example, we'll save the file as Google-Chrome.js in the wwwroot folder of our web server.
We now need to create a web page from where users will be launching our published application:
Create a simple HTML page and save it to a folder on a local web server from where it can be opened in a web browser.
Add the following link to the web page and name it "Google Chrome" (or use the name of your own application):
https://192.168.10.10/userportal/?https://192.168.20.20/Google-Chrome.js#/launch
In the URL above, substitute the Gateway address (192.168.10.10) and the web server address (192.168.20.20) with your own, and use the ".js" file name that you created in previous steps.
Save the web page.
To test our custom launcher:
Open the web page in a browser.
Click the Google Chrome link (or the name you used).
The remote application will open in the browser using Parallels Web Client.
Note: To use the RAS Web Client, the Enable User Portal option must be enabled for the RAS Secure Gateway in the Parallels RAS Console and the gateway must be reachable on https://<server>/userportal/
where <server>
is the IP address or FQDN of the RAS Secure Gateway server.
Parallels Web Client is a browser-based app launcher that is available out of the box with Parallels RAS. The Parallels Web Client is described in detail in the Parallels RAS Administrator's Guide, which is available for download on the Parallels website at the following location: https://www.parallels.com/products/ras/resources/.
The interface described here makes it possible to implement a custom resource launcher.
The following is a typical scenario of the RAS Web Client usage:
A user logs in to the local web portal where the available published resources are listed.
The user clicks on a resource (e.g. an application) that is to be served via Web Client.
A new tab is opened in the web browser in the background using the RAS Web Client URL and some additional parameters, one of which is the name of a JSON payload containing user credentials and the information about the resource being launched. The customer or partner is expected to generate the required payload (we'll talk more about it later in this section).
The Secure Gateway loads the Parallels Web Client and performs a GET request to obtain the JSON payload (see above).
The RAS Web Client then calls a function passing the credentials and resource information.
The user is authenticated and, if successful, the resource is launched on the user's desktop.
This chapter describes the RAS Web Client.
When a user clicks a resource name (a link) on a custom web page, the URL behind it must have one of following formats:
https://<server>/userportal/?appinfo=https://<webserver>/<app-name>.js&theme=<theme-name>#/launch
or
https://<server>/<theme-name>/?appinfo=https://<server>/<app-name>.js#/launch
where:
<server>
is the IP address or FQDN of the RAS Secure Gateway server.
<webserver>
is a web server from where information about published resources and authorized users is served.
<app-name>.js
is a payload in JSONP format containing user credentials and a published resource information. Note that since payload must contain user credentials, the payload should be generated dynamically for every user and every application, desktop, published resource to which a user has access through the web portal. For testing purposes, you can create a temporary ".js" file with all the required information and save it in a folder on your web server. The payload structure is described in the section that follows this one.
<theme-name>
is the name of the Theme that will be used. This parameter is optional if you use the first URL format.
Note: You can use the /RASHTML5Gateway
suffix instead of /userportal
, but this is not recommended.
The JSON payload that the RAS Secure Gateway receives as a response has the following structure (the values are for demonstration purposes only and should be substituted with your own):
Note: You can also use the older function _RASHTML5LoadApp
instead of _RASWebClientLoadApp
for backwards compatibility.
The following table describes the available JSON parameters:
Parameter Name | Description |
---|---|
u:
User name
q:
User password
a:
Published resource ID, as displayed in the RAS Console in the Publishing category. It's the number in front of the application name on the Information tab (e.g. #4: Google Chrome). The number must be included in the payload together with the pound sign, e.g. "#4". If this parameter is omitted, the user will see all applications available on User Portal.
p:
Optional arguments (if an application has them).
d:
Domain name.
logonURL:
URL of a third-party IdP login page.
logoutURL:
URL of a third-party IdP logouts page.
extra: redirectLinks:
Boolean: true = redirect links; false = do not redirect.
extra: redirectPrinter:
Boolean: true = redirect printer; false = do not redirect.
extra: redirectSound:
Boolean: true = redirect sound; false = do not redirect.
This section describes how the API works behind the scenes. You cannot change any of it because that's how Secure Gateways operate, but it should give you an idea of what is involved.
When you open the main URL in a browser (https://<server>/userportal/?https://<webserver>/<app-name>.js#/launch
), you invoke the Secure Gateway.
The Gateway loads the Parallels Web Client and, using the second part of the URL above, performs a GET request with a <script>
tag (this overcomes issues when working across varying domains):
<script type='text/javascript' src='https://webserver.host/getAppInfo/JSONP/7EB8A5D1C2D3E986AB432D'></script>
RAS Web Client obtains the JSON payload and then calls the following Gateway function passing the parameters from the JSON payload:
_RASWebClientLoadApp ({ u: 'user-name', q: 'user-password', a: '#4', p: 'c:\\temp\\another.txt', extra: { redirectPrinter: true, redirectLinks: true, redirectSound: true } })
;
The function call above launches the resource in the browser using Parallels Web Client.
Starting with Parallels RAS 18, specific published resources may be directly accessed through RAS Web Client. This can be achieved with the introduction of a new parameter, appid, which allows administrator to use links to access the published resource directly. This allows a more flexible and easier way for users to access Parallels RAS published resources such as using browser shortcuts or bookmarks or third-party portals such as Azure My Apps Portal to access independent SAAS applications and Parallels RAS virtual apps and desktops.
To launch a published resource directly, you need to specify a URL using one of the following formats:
URL format | Description |
---|---|
Supported parameters:
Parameter | Description |
---|---|
Example:
https://<server>?appid=14&overrideparams=C%3A%2Ftest.txt
When opening a published resource using a direct link, the Auto login option is also used depending on the settings.
https://<server>
?appid=
This format omits the Theme name and uses the default
Web Client Theme.
The "appid" parameter specifies the published resource ID as seen in the Publishing category in the RAS Console. The ID is automatically generated when a resource is published. To see it, select a published resource and examine the Application field on the Information tab. For example, #5: Microsoft Office Word — the application ID of the Microsoft World here is 5.
https://<server>/<theme-name>?appid=<app-ID>
This format is similar to the one above, but specifies a Theme name.
https://<server>/userportal?theme=&appid=
This format is the same as the one above, but uses the full URL specification. It is listed here just for reference.
appid
The published item (application or desktop) to be launched. Note: the format is just a number without # in front.
overrideparams
[Optional]. URL Encoded Override arguments that needs to be passed to the published application.