Clarify wording of draft 1.0.0 release notes, fix typos.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-website/repo Commit: http://git-wip-us.apache.org/repos/asf/guacamole-website/commit/6f785e12 Tree: http://git-wip-us.apache.org/repos/asf/guacamole-website/tree/6f785e12 Diff: http://git-wip-us.apache.org/repos/asf/guacamole-website/diff/6f785e12 Branch: refs/heads/master Commit: 6f785e121b845dc9482e67f6bc8e0d9894c4bccc Parents: b06f4f8 Author: Michael Jumper <[email protected]> Authored: Wed Jan 2 01:02:50 2019 -0800 Committer: Michael Jumper <[email protected]> Committed: Fri Jan 4 11:57:28 2019 -0800 ---------------------------------------------------------------------- _releases/1.0.0.md | 405 ++++++++++++++++++++++++++++++------------------ 1 file changed, 250 insertions(+), 155 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/guacamole-website/blob/6f785e12/_releases/1.0.0.md ---------------------------------------------------------------------- diff --git a/_releases/1.0.0.md b/_releases/1.0.0.md index b7c90f6..08f33cc 100644 --- a/_releases/1.0.0.md +++ b/_releases/1.0.0.md @@ -119,8 +119,8 @@ providing this ability is equivalent to granting your users those privileges. ### Improved keyboard handling / Support for dead keys -Multiple improvements have been made to handling keyboards, including bug fixes -for various clients and support for dead keys. +Multiple improvements have been made to keyboard handling, including bug fixes +for Mac and iOS and support for dead keys. * [GUACAMOLE-161](https://issues.apache.org/jira/browse/GUACAMOLE-161) - Handle CapsLock events properly on Mac OS * [GUACAMOLE-232](https://issues.apache.org/jira/browse/GUACAMOLE-232) - Stuck keys iPad/Bluetooth keyboard (Return/Backspace/Space) @@ -129,19 +129,19 @@ for various clients and support for dead keys. ### Automatic connection behavior -Guacamole has a feature that, if a user has access to only a single connection, -they will be automatically connected to it and skip the home screen. This feature -has been tweaked slightly so that users with elevated access to the Guacamole -Client (Administrative, ability to create connections) will be taken to the -home screen and not automatically taken to the connection. +Guacamole will automatically connect upon login for users that have access to +only a single connection, skipping the home screen. This feature has been +tweaked slightly so that it applies only to non-administrative users. Users +with access to Guacamole's administrative interface will now see the home +screen and not automatically connected. * [GUACAMOLE-508](https://issues.apache.org/jira/browse/GUACAMOLE-508) - Automatically connect only if user lacks access to settings ### Support for renaming RDP drive and printer -A handful of changes allow for changing how the RDP protocol handles naming -of the RDP client and redirected filesystem and printers passed through -via Guacmaole. +By default, the filesystem and printer made available within RDP connections +are named "Guacamole Filesystem" and "Guacamole Printer" respectively. Support +has been added to override these names. * [GUACAMOLE-445](https://issues.apache.org/jira/browse/GUACAMOLE-445) - Allow RDP printer name to be configured * [GUACAMOLE-446](https://issues.apache.org/jira/browse/GUACAMOLE-446) - Allow RDP drive name to be configured @@ -156,25 +156,36 @@ schemes by allowing for the individual colors of a scheme to be customized. ### Optional recording of input events -Guacamole has supported recording sessions for quite some time, but input -events were not recorded (mouse movement, mouse clicks, keyboard input, etc.). -Options are now present for capturing the input events during session -recording. These events are disabled by default, for security and privacy -reasons, but can be enabled if desired. +Guacamole has supported session recording for quite some time, but did not +record input events (mouse movement/clicks, keyboard input, etc.). This meant +that the mouse cursor could not be rendered in recording playback (as the mouse +position information from mouse events was not included) and session recording +could not be used for some auditing purposes that required logging of key +events. + +Options are now available for capturing input events during session +recording. For security and privacy reasons, only mouse events are captured +within session recordings by default. Capture of keyboard events can be +manually enabled, and capture of mouse events can be manually disabled. * [GUACAMOLE-313](https://issues.apache.org/jira/browse/GUACAMOLE-313) - Allow input events within session recording ### SSH host key verification SSH host key verification is now implemented and can be enabled and configured -within Guacamole. In the past, Guacamole has not done any host key checking, -and version 1.0.0 introduces that capability. It is important to note that -this functionality is still disabled by default - if known host keys are not -provided, Guacamole will continue to behave as it has in the past and will not -perform host key checking. If host keys are provided, however, either in a -known_hosts file within the GUACAMOLE_HOME directory on the server running -guacd, or by passing in a parameter to the connection with the key of the -specific server. +within Guacamole. In the past, Guacamole has not performed any SSH host key +checking, and version 1.0.0 introduces this capability. + +For compatibility with past releases, this functionality is still disabled by +default. If known host keys are not provided, Guacamole will continue to behave +as it has in the past and will allow the connection to succeed, though a +warning will be logged. + +If host keys *are* provided (either in a `known_hosts` file within the +`GUACAMOLE_HOME` directory on the server running guacd, or by passing in a +parameter to the connection with the key of the specific server), host checking +will be strictly enforced and the connection will only succeed if the host +matches. * [GUACAMOLE-527](https://issues.apache.org/jira/browse/GUACAMOLE-527) - Add parameter for specifying known SSH/SFTP server host key @@ -185,20 +196,23 @@ specific server. ### Support for configuring Guacamole with environment variables Support has been added for specifying any of the properties supported in the -GUACAMOLE_HOME/guacamole.properties file by setting environment variables that -resemble the names of the parameters. The variables are all caps and replace -dashes with underscores. +`GUACAMOLE_HOME/guacamole.properties` file by setting environment variables +that correspond to those properties. The name of the environment variable for +any particular property is the name of the property in uppercase with all +dashes replaced with underscores. + +For security reasons, the `enable-environment-properties` property must be set +to `true` for reading of properties from environment variables to be enabled. * [GUACAMOLE-464](https://issues.apache.org/jira/browse/GUACAMOLE-464) - Extension configuration properties from the OS environment ### Improvements to `guacamole/guacd` and `guacamole/guacamole` Docker images -Many improvments have been made to the Docker support files for building -and running Guacamole within Docker containers. Most notable among these is -that the default image for Guacamole Server has been changed from CentOS7 -to the latest Debian stable. This allows for more recent, but still stable, -versions of libraries to be used to support the various protocols and features -of guacd. +Many improvements have been made to the Docker support files for building and +running Guacamole within Docker containers. Most notable among these is that +the base for the guacd Docker image has been changed from CentOS 7 to the +latest Debian stable. This allows for more recent, but still stable, versions +of libraries to be used to support the various protocols and features of guacd. * [GUACAMOLE-42](https://issues.apache.org/jira/browse/GUACAMOLE-42) - Support setting guacd log level on Docker container * [GUACAMOLE-407](https://issues.apache.org/jira/browse/GUACAMOLE-407) - Update guacd Docker image to build against more recent dependencies @@ -207,13 +221,12 @@ of guacd. ### General usability improvements -A few changes address the usability of both the client and the server by -adding functionality that addresses issues reported by users. Guacamoel now -supports Ctrl-Alt-End as a hotkey for sending Ctrl-Alt-Delete to remote systems, -which is a widely-used hotkey among remote desktop clients. The zoom level -of the client can be specified more granularly, connections are easier -to click on in the web interface, and guacd now provides a flag for -outputting the build version. +Improvements to usability have been made in order to address issues reported by +users. Guacamole now supports Ctrl-Alt-End as an alternative shortcut for +sending Ctrl-Alt-Delete to remote systems. The zoom level of the client display +can be specified more granularly, connections are easier to select within in +the web interface, and guacd now provides a flag for printing the build +version. * [GUACAMOLE-113](https://issues.apache.org/jira/browse/GUACAMOLE-113) - Add Ctrl+Alt+Del hotkey * [GUACAMOLE-152](https://issues.apache.org/jira/browse/GUACAMOLE-152) - Difficult to reach specific zoom levels @@ -222,12 +235,12 @@ outputting the build version. ### General improvements to terminal behavior -A few updates address improving compatibility of the terminal across -different connections, particularly when dealing with non-Linux operating -systems. Parameters have been added for configuring the terminal type -reported to the remote system, and for adjusting what code the backspace -key sends. The terminal has also been adjusted to hide escape sequences -and control codes that were previously outputted to the screen. +Compatibility of Guacamole's terminal emulator has been improved, particularly +when dealing with non-Linux operating systems. Parameters have been added for +configuring the terminal type reported to the remote system, and for adjusting +the control code sent for backspace. The terminal has also been adjusted to hide +escape sequences and control codes that need not be supported but which were +previously incorrectly printed to the screen. * [GUACAMOLE-269](https://issues.apache.org/jira/browse/GUACAMOLE-269) - Add support for alternative backspace/delete control codes * [GUACAMOLE-564](https://issues.apache.org/jira/browse/GUACAMOLE-564) - Hide APC escape sequence for terminal @@ -235,19 +248,19 @@ and control codes that were previously outputted to the screen. ### Support for systemd -A template systemd init script has been provided and can be built with -Guacamole Server to allow for xyxtem startup on distributions that -have moved from init scripts to systemd. +The guacamole-server build now includes an optional systemd init script to +allow for automatic startup on distributions that have moved from traditional +init scripts to systemd. * [GUACAMOLE-30](https://issues.apache.org/jira/browse/GUACAMOLE-30) - Add Systemd init script for guacd-server ### Control of RDP bitmap and glyph caching Parameters have been added to RDP connections that allow for controlling -how the RDP protocol behaves for caching bitmaps, glyphs, and off-screen -data. The default behavior remains un-changed, with caching of all of these -items enabled, but, for certain scenarios where it may be desirable to -change this behavior the parameters are present. +how the RDP protocol behaves for caching bitmaps, glyphs, and other off-screen +data. The default behavior remains unchanged, with caching of all of these +items enabled, however these parameters are available to workaround issues if +your RDP server handles such caching incorrectly. * [GUACAMOLE-448](https://issues.apache.org/jira/browse/GUACAMOLE-448) - Add parameters for controlling RDP bitmap/glyph/off-screen caching @@ -256,8 +269,13 @@ Internationalization ### Additional RDP keymaps -Several keymaps have been added or updated for better support for keyboard -input on both the Guacamole Client side and on remote systems. +Several keymaps have been added or updated to better support RDP servers with +differing keyboard layouts. As always, bear in mind that [the client side of +Guacamole is always independent of keyboard layout](/faq/#does-guacamole-support-my-keyboard-layout). +Additional keyboard layouts for RDP are mainly of benefit for enabling the +typing of certain characters if your RDP server does not support Unicode +events, and to ensure correct translation of key event to RDP scancode if the +keyboard layout of the RDP server is not the default (US English). * [GUACAMOLE-233](https://issues.apache.org/jira/browse/GUACAMOLE-233) - Add Spanish keymap for RDP * [GUACAMOLE-273](https://issues.apache.org/jira/browse/GUACAMOLE-273) - Add Portuguese Brazilian keymap for RDP @@ -267,9 +285,11 @@ input on both the Guacamole Client side and on remote systems. ### Spanish translation of web interface -The entire web interface has been translated into Spanish, including section -and field headers on the web interface, on-screen keyboard, and remote system -support. +The entire web interface has been translated into Spanish, including the +on-screen keyboard. Spanish will automatically be selected if accessing +Guacamole from a browser whose default language is set to Spanish. The language +can also be [manually selected](/doc/gug/using-guacamole.html#display-language) +within Guacamole's preferences. * [GUACAMOLE-463](https://issues.apache.org/jira/browse/GUACAMOLE-463) - Spanish translation for Guacamole client * [GUACAMOLE-530](https://issues.apache.org/jira/browse/GUACAMOLE-530) - Add Spanish on screen keyboard @@ -279,18 +299,18 @@ Bug fixes ### Hostname / desktop name regression -An issue was corrected where the hostname or desktop name replaced the -connection name on the tab or window title in the browser. The behavior -has been reverted to the desired behavior, where the connection name is -displayed. +An issue was corrected where the hostname or desktop name of VNC and RDP +connections replaced the connection name on the tab or window title in the +browser. The connection name is now always displayed for VNC and RDP. * [GUACAMOLE-502](https://issues.apache.org/jira/browse/GUACAMOLE-502) - Hostname / desktop name replaces connection name ### General connection stability -Several fixes address issues with the stability of connections opened -with Guacamole, either between Guacamole Client and Server, or between -Server and remote systems. +Several issues potentially affecting connection stability have been addressed. +Additional safeguard measures have also been put in place to ensure that +connection processes are automatically killed and cleaned up if an unknown +issue causes the process to become unresponsive. * [GUACAMOLE-324](https://issues.apache.org/jira/browse/GUACAMOLE-324) - Incorrect buffer used in socket write * [GUACAMOLE-384](https://issues.apache.org/jira/browse/GUACAMOLE-384) - Terminal writes during disconnect may segfault @@ -311,24 +331,28 @@ Server and remote systems. ### CAS authorization URI derived incorrectly -To ensure comptability across CAS various implementations of the CAS -protocol, the "/login" portion of the URI has been added to the code -that performs the CAS login. +Guacamole's CAS authentication has been corrected to more properly comply with +the CAS specification. The `/login` portion of the URI used for logins is +required by the specification but was previously omitted by Guacamole. This is +tolerated by some CAS implementations, but not by all. CAS implementations +which require this should now work as expected with Guacamole. * [GUACAMOLE-457](https://issues.apache.org/jira/browse/GUACAMOLE-457) - CAS authentication provider omits login URI ### Build issues for guacamole-server -A couple of fixes were introduced for build issues for Guacamole -server components for various libraries and compilers. +Issues which broke the guacamole-server build on some platforms have now been +fixed. In particular, Guacamole should now build correctly on systems having +GCC 7. * [GUACAMOLE-485](https://issues.apache.org/jira/browse/GUACAMOLE-485) - pango is required with pango support disabled * [GUACAMOLE-500](https://issues.apache.org/jira/browse/GUACAMOLE-500) - Terminal build fails against GCC 7 ### Fixes for guacenc behavior and protocol implementation -A few bugs were squashed in the guacenc program that caused error -messages and erratic behavior under certain conditions. +Previous releases of the "guacenc" utility (part of guacamole-server) produced +incorrect error messages and erratic behavior under certain conditions. These +issues have been corrected. * [GUACAMOLE-307](https://issues.apache.org/jira/browse/GUACAMOLE-307) - guacenc reports "Layer index out of bounds: -1" * [GUACAMOLE-482](https://issues.apache.org/jira/browse/GUACAMOLE-482) - Return value of guacenc_video_flush_frame() not handled @@ -336,9 +360,9 @@ messages and erratic behavior under certain conditions. ### Issues specific to Internet Explorer -Changes were introduced that fix IE-specific issues that either -caused problems or had the potential to impact compatibility with -various versions of IE. +Several issues specific to Internet Explorer which either caused problems or +had the potential to impact compatibility across versions of Internet Explorer +have been fixed. * [GUACAMOLE-316](https://issues.apache.org/jira/browse/GUACAMOLE-316) - IE Compatibility mode doesn't work * [GUACAMOLE-347](https://issues.apache.org/jira/browse/GUACAMOLE-347) - IE may lack window.location.origin @@ -346,22 +370,24 @@ various versions of IE. ### Use of deprecated `navigator.getUserMedia()` -The navigator.getuserMedia() method has been deprecated, so the -Guacamole Client code has been adjusted to remove reliance upon +The `navigator.getUserMedia()` method used by Guacamole's support for audio +input has been deprecated. Guacamole has been updated to no longer rely upon that method. * [GUACAMOLE-237](https://issues.apache.org/jira/browse/GUACAMOLE-237) - navigator.getUserMedia() deprecated ### Incorrect documentation for RDP `load-balance-info` parameter -Documentation was corrected for the load-balance-info parameter. +The `load-balance-info` parameter was incorrectly documented as +`load-balancing-info`. The correct parameter name is indeed +`load-balance-info`. This has been fixed in the documentation. * [GUACAMOLE-427](https://issues.apache.org/jira/browse/GUACAMOLE-427) - RDP "load-balance-info" parameter incorrectly documented ### Erroneous inclusion of "guaclog" binary in source tree -The guaclog binary was accidentally included in one of the source -code releases and in the git repository. It has been removed. +The "guaclog" binary was accidentally included in the source tree of the git +repository. It has been removed. * [GUACAMOLE-492](https://issues.apache.org/jira/browse/GUACAMOLE-492) - guaclog binary erroneously included in source tree @@ -370,26 +396,30 @@ Platform / API changes ### **Java 8 or later is now required** -As noted in the compatibility section below, the Guacamole Client -code has been updated such that Java 1.8 is required for both -build and runtime. +As noted in [the compatibility section below](#deprecation--compatibility-notes), +the Guacamole web application now requires Java version 1.8 or later for both +the build and at runtime. The core Java library, guacamole-common, remains +compatible with Java 1.6, however Java 1.8 is still required for the overall +guacamole-client build. * [GUACAMOLE-497](https://issues.apache.org/jira/browse/GUACAMOLE-497) - Ensure guacamole-client source is compatible with Java 9 * [GUACAMOLE-635](https://issues.apache.org/jira/browse/GUACAMOLE-635) - Build against and require Java 1.8 ### Guacamole no longer uses cookies -The Guacamole Client has been updated such that cookies are no longer -used to store the authentication information, and it is, instead, stored -in the localStorage of the local browser. +The Guacamole web application no longer uses cookies at all, instead relying on +the browser's local storage. * [GUACAMOLE-549](https://issues.apache.org/jira/browse/GUACAMOLE-549) - Store auth token within localStorage ### Removal of NoAuth and other deprecated components Several components that were previously marked as deprecated have been -removed entirely from the code base. This includes the NoAuth extension -and several old properties and API endpoints. +removed entirely from the code base. This includes the NoAuth extension, +several classes and functions, and several old properties. The use of any of +these components would previously have resulted in warnings. They will no +longer be available from this point forward, and continuing to use the +deprecated properties will silently have no effect. * [GUACAMOLE-493](https://issues.apache.org/jira/browse/GUACAMOLE-493) - Remove the NoAuth extension entirely * [GUACAMOLE-494](https://issues.apache.org/jira/browse/GUACAMOLE-494) - Remove support for old, deprecated properties @@ -397,20 +427,14 @@ and several old properties and API endpoints. ### Improvements to extension API -The extension API has been updated with several changes designed to -streamline functionality and make development and maintenance of -extensions easier and more consistent. The error codes sent by -the REST API are now derived from the GuacamoleStatus data structure -rather than being separately calculated. Dependency precendence has -been updated so that the dependencies bundled with the WebApp are -preferred over the ones bundled with the extensions. Base implementations -of UserContext and AuthenticationProvider modules have been provided -and current extensions updated to make use of those, reducing the overall -amount of code to maintain and making implementation of future modules -more straight-forward. Finally, the RESTExceptionMapper class was replaced -by the RESTExceptionWrapper class, which also makes it possible for -extensions to generate their own exceptions that can be handled by the -web applicatlon. +The extension API has been updated to make development and maintenance of +extensions easier and more consistent. The error status codes sent by the REST +API are now derived from the exceptions thrown, allowing extensions to control +the exact code sent. Dependency precedence has been updated so that extensions +always see the classes they bundle, even if the web application bundles a +different version of the same class. Base implementations of `UserContext` and +`AuthenticationProvider` interfaces have been provided, removing the need to +fully implement these interfaces when writing an extension. * [GUACAMOLE-499](https://issues.apache.org/jira/browse/GUACAMOLE-499) - REST API Error Codes should come from GuacamoleStatus * [GUACAMOLE-541](https://issues.apache.org/jira/browse/GUACAMOLE-541) - Webapp dependencies take precedence over bundled extension dependencies @@ -419,20 +443,19 @@ web applicatlon. ### Web application updated to AngularJS 1.6.9 -The AngularJS code was updated from the 1.3.x code to the latest -available 1.x code, which was 1.6.9 at the time of the update. Several -portion of the code were reworked for compatibility with this, including -significant portions of the HTTP request code and how exceptions are -handled within those requests. +The AngularJS library included with the Guacamole web application was updated +from 1.3.16 to 1.6.9. Several parts of the web application were reworked for +compatibility with this update, including the handling HTTP requests and +responses. * [GUACAMOLE-526](https://issues.apache.org/jira/browse/GUACAMOLE-526) - Update Guacamole-Client Webapp to Angular 1.6.9 -### Improvements to Java / JavaScript tunnel API +### Improvements to JavaScript tunnel API -Changes were introduced to improve how the tunnel is handled between the -Java and JavaScript portions of the code, including allowing custom -headers to be configured for the tunnels and insuring that the tunnels -are not closed more than once. +The tunnel implementations provided by Guacamole's JavaScript API have been +updated to allow arbitrary HTTP headers to be included in the connection +request (where supported by the underlying transport), and to allow the same +instance of the tunnel to be reused following disconnect. * [GUACAMOLE-431](https://issues.apache.org/jira/browse/GUACAMOLE-431) - Tunnel implementations handles close only once * [GUACAMOLE-437](https://issues.apache.org/jira/browse/GUACAMOLE-437) - Allow to configure custom headers for Guacamole tunnels @@ -448,13 +471,13 @@ with past releases: ----------------------------------- Most of the Java components of the Guacamole Client have been updated to -require Java 1.8 for both compile and runtime. The decision was made -based on the fact that many support libraries are moving toward -requiring later versions of Java, that Java 1.8 has been out and stable -for many years, and that Java 1.6 and 1.7 have not been updated in -several years. The only exception to this is the base API, the -guacamole-common code, which continues to maintain compatibility with -Java 1.6. +require Java 1.8 for both compile and runtime. This decision was made based on +the fact that many support libraries are moving toward requiring later versions +of Java, that Java 1.8 has been out and stable for many years, and that Java +1.6 and 1.7 have ceased receiving public updates. + +The only exception to this is the core Java API, guacamole-common, which +continues to maintain compatibility with Java 1.6. Database schema changes ----------------------- @@ -468,7 +491,7 @@ required to support those within the database modules (including the Users of any of the database authentication modules will need to run the `upgrade-pre-1.0.0.sql` script specific to their chosen database as part of the move from earlier versions of Guacamole to 1.0.0. More thorough -instructions for this process can be found in the [`JDBC Authentcation`] +instructions for this process can be found in the [`JDBC Authentication`] (http://guacamole.apache.org/doc/gug/jdbc-auth.html) documentation. Hostname logging within database @@ -494,20 +517,15 @@ address. Removal of deprecated NoAuth extension -------------------------------------- -The NoAuth extension has been deprecated for a couple of major releases of -Guacamole, and has been entirely removed from the code base in this release, -both source and binary releases. If you are currently using this extension -you will need to move to a different authentication extension during the -upgrade process, as the NoAuth extension will no longer work. +The NoAuth extension has been [deprecated since +0.9.13-incubating](/releases/0.9.13-incubating/#noauth-now-deprecated), and has +now been removed from Guacamole's codebase. Removal of deprecated properties -------------------------------- The following properties have been deprecated for quite some time, and -are completely removed in the 1.0.0 release. Prior to the 1.0.0 release -a warning would be logged regarding the deprecation of these properties; -as of this release they will be completely ignored if present in the -guacamole.properties file. +have been removed in the 1.0.0 release. * `basic-user-mapping` * `mysql-disallow-simultaneous-connections` @@ -515,29 +533,106 @@ guacamole.properties file. * `postgresql-disallow-simultaneous-connections` * `postgresql-disallow-duplicate-connections` +Prior to the 1.0.0 release a warning would be logged regarding the deprecation +of these properties. As of this release, these properties will be silently +ignored. + Extension API changes --------------------- ### Support for user groups -As noted above, one of the major changes in this version of the Guacamole -Client is the addition of support for user groups across all authentication -modules. This includes changes in the core Extension API (guacamole-ext) -that supports the user groups and allows for those groups to be processed -across various stacked modules and implemented in newer modules. The -AbstractUserGroup, DelegatingUserGroup, SimpleUserGroup, and UserGroup -classes have been added to the Extension API to be implemented within -various extension modules. +As noted above, one of the major changes in this release is the addition of +support for user groups. These changes center around the new `UserGroup` +interface and functions for accessing instances of that interface. Note that if +you are using the abstract base classes `AbstractUserContext` and +`AbstractUser`, little to no changes will be necessary as default +implementations of the required new functions have been provided. + +#### Retrieval of user groups + +The `UserContext` interface now defines a +`getUserGroupDirectory()` function which returns a `Directory<UserGroup>` +providing access to all user groups. If your extension does not provide user +groups, it can simply return an empty `SimpleDirectory<UserGroup>`: + + @Override + public Object getUserGroupDirectory() { + return new SimpleDirectory<UserGroup>(); + } + +#### Effective group membership + +To allow extensions to take group membership into account, even when that +membership is dictated by a different extension, the `AuthenticatedUser` class +now defines `getEffectiveGroups()` function. This function should return the +identifiers of all user groups that apply to the current user. If support for +user groups is not implemented by the extension, simply return an empty set of strings: + + @Override + public Set<String> getEffectiveUserGroups() { + return Collections.<String>emptySet(); + } + +#### Effective permissions + +The `User` interface now provides a `getEffectivePermissions()` function which +should return an implementation of `Permissions` which exposes the permissions +that apply to the user, including permissions which may be inherited through +group membership. If inheritence of permissions is not implemented by your +extension, this function can simply return `this` (as `User` extends +`Permissions`): + + @Override + public Permissions getEffectivePermissions() { + return this; + } + +#### Exposing group membership + +The `User` and `UserGroup` interfaces provide multiple functions for retrieving +parent groups and child objects, if applicable. Existing implementations of the +`User` interface which do not extend `AbstractUser` will need to implement +`getUserGroups()`, a function which retrieves the immediate parent groups of +the user. The returned `RelatedObjectSet` should allow for manipulation of the +group relationship if the extension allows such manipulation (and if the +current user has permission to do so). Extensions which do not implement user +groups can simply return an empty set: + + @Override + public RelatedObjectSet getUserGroups() { + return RelatedObjectSet.EMPTY_SET; + } ### The new decoration API -The 1.0.0 version of the Guacamole Client introduces several classes -that allow extension modules to decorate other modules, providing the -ability to modules to build on top of other modules and store data in -other modules. This was key in allowing the TOTP module to function by -allowing it to store arbitrary data in the databases provided by the -JDBC module, and paves the way for future expansion on how modules -leverage data and functionality from other modules. +The `AuthenticationProvider` interface now defines `decorate()` and `redecorate()` +functions which allow an implementation of `AuthenticationProvider` to decorate the +`UserContext` instances of other extensions. After an extension returns a +`UserContext` instance, the `decorate()` (if the `UserContext` is for a new +session) or `redecorate()` (if the `UserContext` has been updated for an +existing session) functions of all other extensions are invoked to give those +extensions a chance to wrap the `UserContext`. This allows extensions to add +functionality to the objects of other extensions which may not otherwise be +possible. + +Implementations of `AuthenticationProvider` which extend `AbstractAuthenticationProvider` need not +implement these functions as default implementations are provided. +Implementations which do not extend `AbstractAuthenticationProvider` and which do not +decorate the `UserContext` of other extensions should simply return the +original `UserContext`: + + @Override + public UserContext decorate(UserContext context, + AuthenticationProvider authProvider, Credentials credentials) { + return context; + } + + @Override + public UserContext redecorate(UserContext decorated, UserContext context, + AuthenticationProvider authProvider, Credentials credentials) { + return decorate(context, authProvider, credentials); + } ### Removal of deprecated `GuacamoleHome` and `GuacamoleProperties` classes @@ -545,11 +640,10 @@ TODO ### Deprecation of `SimpleUserDirectory`, `SimpleConnectionDirectory`, and `SimpleConnectionGroupDirectory` classes -The SimpleUserDirectory, SimpleConnectionDirectory, and -SimpleConnectionGroupDirectory classes have been deprecated in favor -of the SimpleDirectory<T> class. These classes can still be used, -but will result in deprecation warnings, and will be removed in -a future release. +The `SimpleUserDirectory`, `SimpleConnectionDirectory`, and +`SimpleConnectionGroupDirectory` classes have been deprecated in favor of the +`SimpleDirectory<T>` class. These classes can still be used, but will result in +deprecation warnings, and will be removed in a future release. ### Deprecation of `SimpleUser` convenience constructors @@ -586,13 +680,14 @@ TODO ### Addition of `Guacamole.Tunnel.State.UNSTABLE` state -In order to support changes to detecting and handling network -problems within the Guacamole connections, another tunnel state, -UNSTABLE, has been added. Custom code that leverages the -Guacamole.Tunnel.State type may need to be refactored to take -this additional state into account if it does not currently -ignore unknown states, or the code needs to handle unstable -connections. +In order to support changes to detecting and handling network problems within +the Guacamole connections, another tunnel state, `UNSTABLE`, has been added. +The tunnel enters this state when it is still technically connected but the +network connection appears unstable and may result in disconnection. + +Code which handles changes in tunnel state may need to be updated to take this +additional state into account if it does not currently ignore unknown states, +or that code would benefit from explicitly handling the unstable condition. ### Internal WebSocket tunnel implementation changes
