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.

This guide is intended for Parallels® RAS customers and partners, such as Independent Software Vendors (ISVs), who intend to utilize a third-party web portal for authenticating their users and launching remote applications, desktops, and other published resources hosted in their Parallels RAS environment. Such an implementation is possible by integrating a custom solution to interact directly with Parallels Clients, including Parallels Client for Windows / macOS / Linux / iOS / Android, and the RAS Web Client.

Integrating a custom solution with Parallels Clients is done via the following interfaces available in Parallels RAS:

• RAS Web Client API — provides connection, user authentication, and resource launching methods called from a web browser via the RAS Web Client.

• Parallels Client URL Scheme — a custom URL scheme that allows you to perform actions in Parallels Client installed on a user device. Actions include configuring a connection, authenticating a user, and launching published resources.

The rest of this guide explains how to use the interfaces described above.

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:

1. A user logs in to the local web portal where the available published resources are listed.

2. The user clicks on a resource (e.g. an application) that is to be served via Web Client.

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

4. The Secure Gateway loads the Parallels Web Client and performs a GET request to obtain the JSON payload (see above).

5. The RAS Web Client then calls a function passing the credentials and resource information.

6. The user is authenticated and, if successful, the resource is launched on the user's desktop.

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:

1. In the RAS Console, navigate to Farm > <Site> > Gateways.

2. Right-click a Gateway and click Properties.

3. In the Properties tab, make sure that the Enable RAS Secure Gateway in site option is selected.

4. In the User Portal tab, make sure that the Enable User Portal option is selected.

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

_RASWebClientLoadApp ({
    u: 'user-name',
    q: 'user-password',
    a: '#4',
    p: '',
        extra: {
            redirectPrinter: true,
            redirectLinks: true,
            redirectSound: true
        }
});

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:

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

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

3. Save the web page.

To test our custom launcher:

1. Open the web page in a browser.

2. Click the Google Chrome link (or the name you used).

3. The remote application will open in the browser using Parallels Web Client.

Parallels Client URL scheme allows you to perform actions and programmatically interact with the Parallels Client installed on a user device. The actions include the following:

• Automatic configuration of Parallels RAS or RDP connection in Parallels Client using predefined settings.

• User Authentication.

• Launch of published resources (application, desktop, document, etc.) from a web page or another application.

• User session log off from a specific RAS server of from all current sessions on all servers.

There are currently two URL schemes used in Parallels RAS: tuxclient:// and prlclient://. Depending on the platform on which Parallels Client is running, the following URL schemes are used:

Note that the tuxclient scheme is kept for backwards compatibility with older Parallels Clients. In the future, the prlclient scheme may replace it in all versions of Parallels Client. At this time, use the scheme that is supported on a given platform. If both are supported, you can use one or the other -- the usage, including command options, is exactly the same.

When Parallels Client is installed on a device, it registers the Parallels Client URL scheme with the operating system, which tells a web browser what to do when the user opens such a URL. In this instance, the web browser will open Parallels Client passing to it the parameters that the URL contains. Parallels Client will process the parameters and will perform actions according to received instructions.

The following describes a typical Parallels Client URL scheme usage scenario:

1. Suppose you want to create an application hub or a web portal from where users can launch applications published in Parallels RAS.

2. You first compose a URL according to specifications, which are described in detail later in this chapter. The URL string begins with the Parallels Client URL scheme followed by the necessary parameters depending on the task and configuration options. For example, prlclient:///?Command=LaunchApp&AppID=2360&.... (the complete URL is not shown for brevity).

3. You then publish the URL on a third-party web portal where end users can use it to launch a published resource.

A user logs in to the web portal and clicks the URL. This opens Parallels Client, which processes the parameters contained in the URL and performs actions according to these parameters (configures a connection, authenticates the user, launches an app, etc.).

Note that if Parallels Client is not installed on a user device, nothing will happen because the URL scheme is unknown to the operating system and no application is associated with it. This only means that Parallels Client must be installed before making use of the custom scheme URL.

This chapter describes the RAS Web Client.

This chapter described the Parallels Client URL scheme.

A URL string always begins with the Parallels Client URL scheme. See the table in the previous section for a scheme supported on a specific platform. If both URL schemes are supported, you can use either one.

The first parameter that you include after the URL scheme is the Command parameter. It tells Parallels Client what kind of action should be performed. The available commands are:

• GetVersion — Allows to determine on the web server side which Parallels Client version is installed on a user device, or if the Parallels Client is installed at all.

• LaunchApp — Creates a connection, authenticates a user, launches a published resource.

• Get2xa — Performs the same actions as the LaunchApp command (above), but uses advanced security, which eliminates passing sensitive information (server name, user credentials, published resource info) in the URL itself.

• LogOff — Logs off the user from a session on a specified server or from all sessions on all servers.

The Command parameter is placed in the URL as shown in the following example:

tuxclient:///?Command=LaunchApp

Command options are specified after the command using the ampersand ("&") separator:

tuxclient:///?Command=LaunchApp&AppID=2360&ConnMode=0 ...

Note that the prlclient:// URL scheme uses the same exact format demonstrated here and in all other examples included in this chapter.

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:

Supported parameters:

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.

The Get2xa command performs the same tasks as the LaunchApp command, but uses an advanced security mechanism to pass sensitive information between the web portal and the Parallels Client.

Advanced security is achieved as follows:

1. A user clicks a published resource on a third-party web portal. This opens a URL that uses the Parallels Client URL scheme and includes the following information:

   • The web portal server name, port number, and session ID.

   • A path from which Parallels Client can download an XML file containing the Parallels RAS connection information, user credentials, and the ID of the published resource to launch.

     The XML file that the Parallels Client will be downloading is called a 2XA file, which is a historical name used in Parallels RAS to identify the specific file format. The 2XA file specifications (XML) are described later in this section.

2. The URL opens Parallels Client in the background. The information contained in the URL is passed to Parallels Client.

3. Parallels Client connects to the web server using the received information and downloads a 2XA file using the path that it received via the URL.

   Note that the 2XA file should be dynamically generated for every user and every published resource when a given user attempts to launch a resource in the web portal.

4. Parallels Client parses the information contained in the XML file and uses it to create a connection, authenticate a user, and launch a resource.

Get2xa command options

The following table describes the Get2xa command options:

URL example

The following URL opens Parallels Client and passes to it the web server information, the web portal session ID, the path to the 2XA file, and the path to the original web portal web page.

The GET request from Parallels Client

When Parallels Client receives the information from the URL, it uses it to connect to the web server and download the 2XA file.

The following is an example of the GET request performed by Parallels Client:

2XA XML details

The following table describes the XML document structure used in the 2XA file (see also the XML example below):

XML Example

The XML document must begin with UTF-8 BOM (byte order mark), which consists of the following 3 bytes:

Note that BOM is not a text. You need to use a script that can add these 3 bytes to the beginning of the file.

The following is a sample 2XA XML document:

Note that another option to pass the password is to use the ClearPassword key instead of Base64ClearPassword, as shown below:

The GetVersion command allows to determine on the web server side which Parallels Client version is installed on a user device, or if the Parallels Client is installed at all. If Parallels Client is an older version or not installed on a device, you can display a message to the user with a link from which they can download and install the correct version of Parallels Client.

The command works as follows:

1. A user opens a custom scheme URL with the GetVersion command in it.

2. The URL starts Parallels Client which receives the parameters contained in the URL, including server name, port number, the web portal session ID, and the path to which Parallels Client needs to connect to pass its version information back to the web portal.

3. The Parallels Client uses the received information and connects to the web portal using the specified path with the version information appended to it.

4. The web portal parses the received data and evaluates the Parallels Client version number. If the request times out (no response is received from Parallels Client), it means that Parallels Client is not installed on the user device.

The following table describes the GetVersion command options:

URL example

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

The following table describes the available JSON parameters:

The LogOff command logs off a user from a session on a specified server or from all current sessions on all servers.

URL example

Log off from a specific server:

Log off from all servers:

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.

1. When you open the main URL in a browser (https://<server>/userportal/?https://<webserver>/<app-name>.js#/launch), you invoke the Secure Gateway.

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

3. 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 } });

4. The function call above launches the resource in the browser using Parallels Web Client.

Custom types

The following custom types are used in command options described in this chapter:

The LaunchApp command is used to configure a connection in Parallels Client, authenticate a user, and launch published resources.

Note that the LaunchApp command passes sensitive information inside a URL, including server name, port, and possibly username and password. If this is a concern, use a more secure Get2xa command.

The following table describes the LaunchApp command options:

URL example

The following URL creates a new connection (but doesn't save it in Parallels Client as the "Save" key is set to "NO"), authenticates a user using the specified credentials, and launches an application in Parallels Client.

tuxclient:///?Command=LaunchApp&AppID=2360&Alias=My-RAS-Connection&ConnType=0&ConnMode=0&Server=10.0.0.50&Backup=&Port=80&LoginEx=tester56%402x&EncPass=l6Y1%2bfOryvNHYsI0nWIW4g%3d%3d&SessionID=A78399FE-7077-43AD-8D0A-03641F1C759B&Connect=YES&Save=NO&RequestPage=http://my.portal.testing/mywebportal/Dashboard.aspx