Guacamole-Based Clientless RDP-SSH

Mobile AccessClosed Check Point Software Blade on a Security Gateway that provides a Remote Access VPN access for managed and unmanaged clients. Acronym: MAB. integrates with Apache Guacamole to provide clientless RDP and SSH connectivity from the Mobile Access Portal.

This new feature provides a way for customers to connect to their office desktops without the installation of a client on their endpoint computers. It offers secure, seamless and authorized Clientless Remote Desktop connections with WebSocket technologies.

The new feature includes:

Guacamole

Apache Guacamole is a clientless RDP, SSH, and VNC platform through HTML5 and WebSocket. The Guacamole project is open-source and MIT-licensed.

The Mobile Access integration with Guacamole is available on R81 and higher for clientless RDP and SSH connectivity from its portal.

Important:

  • The Mobile Access clientless RDP/SSH feature requires a separate machine running either 'guacd' or a full Guacamole installation. For instructions to easily install a Docker image-based 'guacd', see Installing the Guacamole Docker Image.

  • As a text-based protocol, Guacamole's RDP performance can be much slower than a 'native RDP' served through SNX or other VPN-based solutions. Before you deploy a Guacamole-based RDP solution, make sure that both the Mobile Access gateway and the 'guacd' server can handle the expected RDP load.

Configuration

Configuration is required on both Security Gateways (ClusterClosed Two or more Security Gateways that work together in a redundant configuration - High Availability, or Load Sharing. Members) and SmartConsoleClosed Check Point GUI application used to manage a Check Point environment - configure Security Policies, configure devices, monitor products and events, install updates, and so on..

Important - In a Cluster, you must configure all the Cluster Members in the same way.

Configuration on Security Gateways and Cluster Members

Configuring communication between the Security GatewayClosed Dedicated Check Point server that runs Check Point software to inspect traffic and enforce Security Policies for connected network resources. (Cluster Members) and the Apache Guacamole server requires updates in the $CVPNDIR/conf/cvpnd.C file:

Attribute Name

Default Value

Description

:guacamoleServerHostname

("")

The Apache Guacamole Server ('guacd') host name or IP address.

Important - Because 'guacd' does not authenticate its clients, it is imperative to configure it to receive traffic only from the Mobile Access Gateway, unless other products are already using its services.

Note - By default, a Guacamole Server's 'guacd' listens to 'localhost' only. Make sure that there is connectivity from the Mobile Access Gateway to the 'guacd' server on the desired port number.

:guacamoleServerPort

(4822)

The Apache Guacamole Server ('guacd') port number.

:guacamoleServerEnableSsl

(true)

Toggles SSL/TLS connection to Apache Guacamole Server ('guacd').

Important - Disabling this attribute might compromise the security of RDP/SSH traffic.

:guacamoleValidateApplicationServerCertificate

(false)

Toggles whether Apache Guacamole Server ('guacd') validates the RDP server's server certificate.

Note - Mobile Access validation of 'guacd's server certificate itself is configured on the next page.

:guacamolePreferQualityOverPerformance

(false)

Toggles whether RDP bandwidth-consuming features such as color depth and Windows background rendering are enabled.

Such features are disabled by default to improve overall performance.

:showRemoteDesktopSectionOnlyIfLinksExist

(true)

When a Mobile Access Gateway is configured for Unified Access Policy mode, you can toggle whether to display the Remote Desktop application section in the portal when no remote desktop links are configured.

In Legacy Mobile Access Policy, the Remote Desktop Application section is displayed for each user authorized for at least one Remote Desktop Application.

:guacamoleRdpSecurityMode

("any")

Determines the RDP security mode.

Valid values are:

  • "any" - The default (performs a handshake).

  • "nla" - Network Level Authentication.

  • "nla-ext" - Extended Network Level Authentication.

  • "tls" - RDP authentication with TLS.

  • "rdp" - Standard RDP authentication (displays Windows login screen, for older versions).

:customUserRecordAttribute

("")

The user record attribute to be used by the $$custom macro, especially for mapping end-user accounts to their desktop FQDNs or IP addresses.

If specified, and if its value is not empty, the value is stored on the end-user's session after successful authentication.

If the desired user record attribute is not available by default, see Configuring Custom User Record Attributes for how to add it to the fetched user record.

:guacamoleEnableBitmapCaching

(true)

These three attributes configure settings for the RDP protocol only.

These three attributes deal with faulty RDP server implementations.

Disabling these advanced RDP features may improve compatibility with certain types of RDP servers.

You must disable 'glyph caching' to connect through Guacamole 1.3.0 and newer versions to Windows 7 RDP servers.

:guacamoleEnableOffscreenCaching

(true)

:guacamoleEnableGlyphCaching

(true)

:guacamoleEnableConsoleMode

(false)

When true, connects to the 'console' session of an RDP server (not recommended for regular use).

:guacamoleServerKeyboardLayout

("")

Example values:

  • en-us-qwerty

  • fr-fr-azerty

  • failsafe (Unicode)

Refer to Guacamole's configuration help page for detailed instructions:

https://guacamole.apache.org/doc/gug/configuring-guacamole.html

:guacamoleEnableClipboardCopy

(true)

When false, blocks copying text from the remote desktop to the end-user's desktop's clipboard.

:guacamoleEnableClipboardPaste

(true)

When false, blocks pasting text from the end-user's desktop's clipboard to the remote desktop.

:guacamoleRdpCustomSettings

("")

A set of custom Guacamole RDP attributes for compatibility with future Guacamole versions. Attribute names and values are provided in a semicolon-delimited list:

attribute1=value1;attribute2=value2

Notes:

  • Mobile Access Guacamole client forwards only attributes explicitly requested through the 'guacd' server's args instruction.

  • Adding attribute name/value pairs which are already configured by other cvpnd.C attributes may overwrite those values.

To configure attributes in the $CVPNDIR/conf/cvpnd.C file:

  1. Connect to the command line.

  2. Log in to the Expert mode.

  3. Back up this file:

    cp -v $CVPNDIR/conf/cvpnd.C{,_BKP}

  4. Set each of the attributes as follows:

    cvpnd_settings $CVPNDIR/conf/cvpnd.C set <Attribute Name> <Attribute Value>

    Example:

    cvpnd_settings $CVPNDIR/conf/cvpnd.C set guacamoleServerHostname guacamole.example.com

  5. When the value of the "guacamoleServerEnableSsl" attribute is set to "true" (recommended), the SSL configuration below is required in the $CVPNDIR/conf/guacdispatcher.C file:

    Attribute Name

    Default Value

    Description

    :trustedCaCertificatesDir

    ("$CVPNDIR/var/ssl/ca-bundle/")

    Local path on the gateway of trusted CA certificate files.

    You can add more certificates to those that come with the installation.

    Recommended: Keep default.

    :customCipherSuites

    ("")

    Allowed ciphers for SSL between the gateway and the Apache Guacamole Server ('guacd').

    Recommended: Keep default.

    :verifyServerCertificate

    (true)

    Toggles whether the Mobile Access Gateway verifies Apache Guacamole Server's server certificate each time a Guacamole session is initiated.

    Important - Disabling this attribute might compromise the security of RDP/SSH traffic.

    Note - If this attribute is enabled, configure the Apache Guacamole Server ('guacd') host name as an FQDN, not as an IP address. Also, make sure that the FQDN is resolvable from the Mobile Access Gateway.

    1. Configure each of the attributes as follows:

      cvpnd_settings $CVPNDIR/conf/guacdispatcher.C set <Attribute Name> <Attribute Value>

      Example:

      cvpnd_settings $CVPNDIR/conf/guacdispatcher.C set verifyServerCertificate true

    2. If the Apache Guacamole Server's server certificate is issued by a CA, which is not already included in Mobile Access's CA bundle:

      1. Copy the CA's certificate to the Mobile Access Gateway's trusted CA certificates directory, or to the one defined by the value of the "trustedCaCertificatesDir" attribute, if it is different.

      2. Rename the extension of the certificate file to PEM: *.pem

      3. Run:

        rehash_ca_bundle

  6. Restart the Mobile Access services:

    cvpnrestart

Configuration in SmartConsole

Create a new Web Application object to represent the Remote Desktop Application.

  1. In the Global toolbar, click Objects > More object types > Custom Application/Site > Mobile Application > New Web Application.

  2. From the left tree, click General Properties.

  3. In the Name field, the object name must start with the prefix guac__ (with two underscores).

  4. From the left tree, click Authorized Locations.

  5. In the Host or DNS name field, select the Host object, to which it is necessary to allow an RDP/SSH connection.

    You can use an IP address or a DNS object.

    Configure the names of the applicable DNS objects with these macros:

    • The $$user macro represents the username of the currently logged-in user.

    • The $$domain macro represents the domain name of the logged-in user.

    • The $$custom macro represents the value of the custom attribute configured through the 'customUserRecordAttribute' setting described above.

    Warning - The '$$custom' macro may have security implications when used as an Authorized Location - anyone with write access to the attribute's value on the user's directory can add arbitrary locations to the set of authorized locations, so the feature must be used with care.

  6. Go to Authorized Locations > Services > Edit.

  7. Add one of these services as the only authorized service:

      • "Remote_Desktop_Protocol"

      • "SSH"

      • "SSH_version_2"

    Note - All the services above have default ports. For example, RDP's default port is 3389. If your server is listening on a different port, change this port in the Service object. Do not use a different service object.

  8. Click Link in Portal > URL.

  9. Use a special URL format to define the Guacamole application's link:

    http://guacamole?host=<HOST>&port=<PORT>

    Where:

    • <HOST> - Host name or IP address of the remote desktop host.

    • <PORT> - The port used by the remote desktop host to allow the RDP connection. Default ports are 3389 for RDP, and 22 for SSH.

    Notes:

    • You can use the "$$" macros from step 4 in the <HOST> part of the link.

    • You can only change the values of <HOST> and <PORT> while configuring the Remote Desktop Application link.

      For example:

      http://guacamole?host=desktop-$$user.example.com&port=3389

Logs and Debugs

In case of an error, Mobile Access Portal shows an error message.

Traffic logs for Guacamole-based applications are created with a "Web" category and contain failure information in case of a server error.

To show Guacamole-based application connections for each user, enter this command on the Mobile Access Gateway:

PingerAdmin guac report all

Integration of Mobile Access with Guacamole Server

Publishing Guacamole-based applications with the Mobile Access Software Blade:

  • Configure Guacamole's portal as a standard Mobile Access Web application object.

  • Publish Guacamole applications directly from Mobile Access Portal.

Feature

Guacamole as Web App

Integrated Guacamole

Availability

Available on all supported Mobile Access Software Blade versions.

Available on all supported Mobile Access Software Blade versions.

Guacamole server requirements

Requires a full Guacamole installation.

(Java Web server + 'guacd')

Requires 'guacd' only, easily available as a Docker image.

Authentication

Performed by the Guacamole server.

Performed by Mobile Access Software Blade according to its policy configuration.

Access Control

Performed by the Guacamole server.

Performed by Mobile Access Software Blade according to its policy configuration.

Guacamole application links

Available on the Guacamole server's portal, as served by Mobile Access.

Available on Mobile Access Portal.

WebSocket protocol handling

WebSocket traffic is proxied as specified in sk95311, and forwarded 'as is' to the Guacamole server.

WebSocket traffic is handled by Mobile Access, and the inner 'Guacamole protocol' content is forwarded to Guacamole's server.

Performance

WebSocket traffic is handled by a single process.

WebSocket traffic is handled by multiple processes.

Mobile device support

Supported.

Either partially supported or not supported, depending on the mobile device's browser type.

Protocol and feature support

RDP, SSH and VNC are supported, along with file transfer, SFTP and session recording.

Only RDP and SSH are supported. VNC, file transfer, SFTP and session recording are not supported.

Compatibility with Guacamole versions

Mobile Access R81 and R81.10 are optimized for Guacamole version 1.1.0, but partially support later Guacamole versions.

Mobile Access R81.20 is optimized for Guacamole version 1.3.0, the currently latest available Guacamole version provided by the Apache Software Foundation.

Installing the Guacamole Docker Image

Note - The instructions below are for setting up various 3rd-party software suites, namely Linux, Docker, and Guacamole. Therefore, these instructions might not apply to all configurations.

Example installation sequence for a 'guacd' Docker container on a Linux machine:

  1. Switch user to 'root' (or prepend all commands below with 'sudo'):

    su

  2. Download the 'guacd' Docker image:

    docker pull guacamole/guacd

  3. Disable any Docker container proxy configuration, which might block 'guacd' from contacting RDP servers.

    This step is required because Docker may apply 'httpProxy' and 'httpsProxy' configurations for non-HTTP connections such as Guacamole's port 4822.

    1. If the file exists, edit it:

      : ~/.docker/config.json

    2. Remove all references to proxies, which might be used for the 'guacd' connection.

      Note that some Docker versions ignore the 'noProxy' attribute. We do not recommend to rely on it to bypass the proxy.

  4. Run a 'guacd' Docker container based on the downloaded Docker image:

    docker run --name <Name of Container> -d -p <External Port>:4822 -v

    <Path to Directory with Guacamole Server Certificates>:/mnt/certs guacamole/guacd

    /opt/guacamole/sbin/guacd -f -b 0.0.0.0 -L info -C

    /mnt/certs/<Name of Guacamole Server Certificate File> -K

    /mnt/certs/<Name of Guacamole Server Certificate Key File>

    Example:

    docker run --name guacd_example -d -p 4822:4822 -v

    /var/tmp/guacCerts:/mnt/certs guacamole/guacd

    /opt/guacamole/sbin/guacd -f -b 0.0.0.0 -L info -C

    /mnt/certs/guacamole.example.com.pem -K

    /mnt/certs/guacamole.example.com.key

  5. To view 'guacd's logs, enter:

    docker logs <Name of Container> -f

  6. To stop the container, enter:

    docker container stop <Name of Container>

Configuring Custom User Record Attributes

When an end-user successfully authenticates to a Mobile Access Gateway, Mobile Access fetches a user record from the user directory.

Some user record fields such as the user name and the user groups are available by default. However, mapping end-user accounts to their desktop FQDNs or IP addresses usually requires a user directory attribute which is unavailable by default.

To add such custom user directory attributes to the collection of attributes:

  1. Back up this file:

    cp -v $CPDIR/conf/customUserRecordAttribute.conf{,_BKP}

  2. Edit this file:

    vi $CPDIR/conf/customUserRecordAttribute.conf

  3. Add the desired attribute according to the format below:

    (
        :userAttribute ("<Name of User Attribute>")
    )

    Example:

    (
        :userAttribute ("info")
    )

    Notes:

    • The 'info' attribute in the example above maps to the 'Telephones > Notes' UI field on Microsoft Active Directory servers.

    • Only attributes of type 'string' are supported.

    • This version supports fetching a single attribute only.

    • Only attributes returned by LDAP authentication servers are supported.

    • The value of "Name of User Attribute" above must be identical to the value configured for the customUserRecordAttribute in the $CVPNDIR/conf/cvpnd.C file, so that Mobile Access can resolve the '$$custom' macro to the value fetched from here.

  4. Save the changes in the file and exit the editor.

  5. Restart the Mobile Access services:

    cvpnrestart

  6. The changes take effect after end-users log in and the new attribute is fetched.