Apache Guacamole 1.3.0 (Archived)

Apache Guacamole 1.3.0 is an archived release, and was originally released on 2021-01-01. The latest release of Apache Guacamole is 1.5.5.

Apache Guacamole is split into two subprojects: "guacamole-client", the HTML5 web application which serves the Guacamole client to users, and "guacamole-server", the remote desktop proxy which the web application communicates with. The source code for each of these may be downloaded below.

You must verify the integrity of any downloaded files using the OpenPGP signatures we provide with each release. The signatures should be verified against the KEYS file, which contains the OpenPGP keys of Apache Guacamole's Release Managers. Checksums of each released file are also provided.

Filename Signatures / Hashes
guacamole-client-1.3.0.tar.gz PGP SHA-256
guacamole-server-1.3.0.tar.gz PGP SHA-256

If you do not wish to build Apache Guacamole entirely from source, pre-built versions of the web application (.war) and all extensions are provided here in binary form for convenience. Please note that guacamole-server must still be built and installed from source.

Filename Signatures / Hashes
guacamole-1.3.0.war PGP SHA-256
guacamole-auth-cas-1.3.0.tar.gz PGP SHA-256
guacamole-auth-duo-1.3.0.tar.gz PGP SHA-256
guacamole-auth-header-1.2.0.tar.gz PGP SHA-256
guacamole-auth-jdbc-1.3.0.tar.gz PGP SHA-256
guacamole-auth-ldap-1.3.0.tar.gz PGP SHA-256
guacamole-auth-openid-1.3.0.tar.gz PGP SHA-256
guacamole-auth-quickconnect-1.3.0.tar.gz PGP SHA-256
guacamole-auth-saml-1.3.0.tar.gz PGP SHA-256
guacamole-auth-totp-1.3.0.tar.gz PGP SHA-256

Release notes

The 1.3.0 release features support for automatically prompting users for their remote desktop credentials, user group support for both CAS and OpenID, and several bug fixes. For a full list of all changes in this release, please see the changelog.

The 1.3.0 release is compatible with older 1.x components. You should upgrade older components to 1.3.0 when possible, however things should continue to work correctly in the interim:

  • Extensions written for older 1.x releases can be used by 1.3.0.
  • Components written for the version of the Guacamole protocol used by older 1.x releases can be used with components of the 1.3.0 release.

Regardless of inter-component compatibility, there are changes in 1.3.0 which may affect downstream users of Guacamole’s APIs and the Guacamole protocol. Please see the deprecation / compatibility notes section for more information.

Automatic prompting for remote desktop credentials

Historically, Guacamole has required that remote desktop credentials either be stored alongside connection configuration, passed through from web application authentication (typically Active Directory), or retrieved interactively by the remote desktop itself.

In addition to these methods, Guacamole will now automatically prompt the user to enter any credentials not already provided by the administrator if those credentials are required.

User group support for CAS and OpenID

If using a CAS or OpenID identity provider to automatically sign in your users, user groups can now also be retrieved from the identity provider. Similar to the support already present for SAML, this support allows the admininstrator to define how user groups are exposed by the identity provider and allow those user groups to affect the permissions granted to their members within Guacamole.

Changelog

User interface / platform

  • Parameter prompting within client interface (GUACAMOLE-221)
  • Objects may appear duplicated if access is granted via multiple groups (GUACAMOLE-1021)
  • Support automatic conversion of usernames to lowercase/uppercase via parameter tokens (GUACAMOLE-1081)
  • Ctrl+Alt+End(Supr) keyboard shortcut only works once (GUACAMOLE-1125)
  • Connection group permissions do not correctly determine presence of save/delete buttons (GUACAMOLE-1150)

Docker images

  • Add support for TOTP to Guacamole Docker image (GUACAMOLE-753)
  • Add support for HTTP header authentication to Guacamole Docker image (GUACAMOLE-857)
  • Update base image of Guacamole Docker image (GUACAMOLE-980)
  • Add environment variables for ldap-user-attributes property to Guacamole Docker image (GUACAMOLE-987)
  • Add support for CAS to Guacamole Docker image (GUACAMOLE-1082)
  • Run web application as reduced-privilege user within Guacamole Docker image (GUACAMOLE-1110)
  • Add environment variables for ldap-dereference-aliases, ldap-follow-referrals, ldap-max-referral-hops, and ldap-operation-timeout properties to Guacamole Docker image (GUACAMOLE-1147)

Authentication, integration, and storage

  • Add support for retrieving user groups from CAS (GUACAMOLE-793)
  • Add support for retrieving user groups from OpenID (GUACAMOLE-1172)
  • PostgreSQL database connection may unexpectedly fail due to time out (GUACAMOLE-919)
  • Login using LDAP fails internally if TOTP is used without automatic user creation (GUACAMOLE-1149)
  • CAS module causes app.js download errors (GUACAMOLE-1120)
  • Allow server timezone info to be submitted to MySQL / MariaDB (GUACAMOLE-760)
  • MySQL SSL truststore path must be a valid URL (GUACAMOLE-1135)
  • MySQL SSL client certificate properties incorrectly return truststore property values (GUACAMOLE-1136)
  • Query may fail if all connections disconnect while listing active connections (GUACAMOLE-942)
  • RFC2865 requires NAS IP address to be submitted for RADIUS (GUACAMOLE-1001)
  • Standardize on filtered history query for user and connection management (GUACAMOLE-1123)
  • TOTP authentication fails when totp-period is set (GUACAMOLE-1146)
  • Enabling skip-if-unavailable breaks expired password change (GUACAMOLE-1152)

Protocol support / guacd

  • RDP log message incorrectly refers to “VNC” (GUACAMOLE-982)
  • SFTP upload directory ignored for RDP connections (GUACAMOLE-1031)
  • RDP disable-copy flag does not work (GUACAMOLE-1158)
  • Memory allocated for outbound SVC PDUs may not be freed (GUACAMOLE-1181)
  • Memory allocated for outbound RDP clipboard data is not properly freed (GUACAMOLE-1182)
  • Thread mutexes within Guacamole’s various supported protocols are not always cleanly destroyed (GUACAMOLE-1114)
  • RDP support may fail to build if SSH support is unavailable (GUACAMOLE-1122)

Internationalization

Documentation

  • Documented Duo secret key length is incorrect (GUACAMOLE-819)
  • Guacamole Docker image documentation incorrectly states Docker links are supported for LDAP (GUACAMOLE-912)
  • allowed-languages property incorrectly documented as available-languages (GUACAMOLE-1107)

General housekeeping and cleanup

Deprecation / Compatibility notes

Each 1.x release of Apache Guacamole should be compatible with components of older 1.x releases. This compatibility is intended at the Guacamole protocol level and at the extension level, but not necessarily at the API level. This means:

  • Extensions from older 1.x releases should still work in binary form, but may need code changes before their source will build against a newer version of guacamole-ext.
  • Software which uses the Guacamole protocol of an older 1.x release should still work.
  • Software which uses libguac from an older 1.x release should still work by continuing to use the libguac from that release, as newer versions of libguac may not be API/ABI compatible. In the case of third-party protocol support plugins for guacd, this means that the guacd from that release must also be used. Compatibility with respect to libguac is represented by the soname.
  • You should update to newer versions where applicable and when possible.

As of 1.3.0, the following changes have been made which affect compatibility with past releases:

Java API (guacamole-common) changes

Implementations of GuacamoleSocket should now implement getProtocol()

The required and argv instructions both refer to connection parameters by name. As it is the underlying protocol of a connection that determines the semantics of connection parameters, client implementations will commonly need to expose this information in some way. The mainline web application provided by Apache Guacamole is one such implementation.

A new getProtocol() function has been added to GuacamoleSocket to facilitate this, and implementations of GuacamoleSocket should aim to provide implementations of this function with that in mind.

This will happen automatically for ConfiguredGuacamoleSocket.

Extension API (guacamole-ext) changes

Deprecation of getHistory() for User and Connection interfaces

The User and Connection interfaces have both continued to define a basic getHistory() function for retrieving a raw list of history records. Unlike the getUserHistory() and getConnectionHistory() functions exposed by the UserContext, the getHistory() functions do not support filtering or searching.

The old getHistory() functions have now been deprecated in favor of newer functions that do support filtering. Implementations that provide getHistory() will continue to work, but should migrate to the new functions when possible.

  • GUACAMOLE-1123 - Standardize on filtered history query for user and connection management

Guacamole protocol changes

The new required instruction

To allow the server to request that the client provide credentials (or any other parameters), a new required instruction has been added to the Guacamole protocol. This instruction informs the client that one or more connection parameters need to be specified for the connection to continue. If the client indicated support for the required instruction during the initial connection handshake, the client is then expected to supply values for each of these parameters using argv streams.

libguac API changes

protocol_version added to guac_user_info structure

A new protocol_version member has been added to guac_user_info to allow implementations to make decisions based on the Guacamole protocol version in use, affecting the size of this structure.

Additionally, because guac_user_info forms a part of guac_user, this change also affects the memory offsets of members of the guac_user structure which follow the info member, such as data and various instruction handlers.

Downstream usages of libguac which make use of guac_user or guac_user_info will need to be rebuilt to ensure that the structure sizes and memory offsets used are correct.