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.

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

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.

This chapter described the Parallels Client URL scheme.

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.