Apache Guacamole comes with a built-in, simplified, XML-driven authentication mechanism for the sake of testing. Accounts and connections can be defined within
/etc/guacamole/user-mapping.xml without having to install support for a database. The default file included with Glyptodon Enterprise looks like this:
As noted at the top of the file, you can leverage this to verify that your Guacamole installation is functional, however the
user-mapping.xml file should not be used for production deployments. Production deployments of Guacamole should instead use one of the authentication extensions, such as the database support or LDAP. Unlike the XML, all of these extensions are intended for production use.
user-mapping.xml file consists of a main, root-level
Defining user accounts
<user-mapping> element may contain any number of
<authorize> blocks, each describing a user and their corresponding password:
Granting access to connections
<authorize> blocks in turn may contain any number of
<connection> blocks, each describing a connection that should be accessible to the user:
This file is automatically reread when modified, so you should be able to immediately log in when you define a new user in this way, however changes to an active user’s connections will not be available to that user until they logout.
Defining connections (protocols and parameters)
<connection> contains exactly one
<protocol> element (specifying the unique name of the protocol to use to connect to the remote desktop) and any number of
<param> elements (specifying the name of a parameter and the value to use for that connection). These protocol and parameter names are standardized and case-sensitive. The names of each supported protocol are defined by Guacamole, and the names of available parameters are defined by the part of Guacamole implementing that support:
|Protocol||Unique name||Glyptodon Enterprise package|
The names of many parameters are predictable and common across the supported protocols, like "hostname" and "port", but please consult the documentation for the relevant protocol for a full list of available parameters and their allowed values, as well as which parameters are absolutely required.
When ready to move to a production deployment leveraging a database, protocol and parameter names will be handled automatically by the web interface enabled by the database. The internal names of protocols and their parameters are mainly useful for authentication methods that require connections to be entered manually (
user-mapping.xml, encrypted JSON, connections defined directly within an LDAP directory, or custom extensions leveraging the Guacamole API). They are not visible when using one of the database authentication backends except if manually manipulating data within the database using SQL.
Moving to production
When finished testing, you should prepare to move forward with adding the remaining layers normally required by a production deployment:
- A supported database: MySQL / MariaDB, PostgreSQL, and SQL Server are supported. If you do not already have a database deployed, or are unfamiliar with deploying databases, instructions are provided for installing a local instance of MariaDB.
- SSL termination: Apache HTTPD and Nginx are supported for this purpose. If you do not already have a reverse proxy in place, or are unfamiliar with installing and configuring a reverse proxy, instructions are provided for installing Nginx to provide SSL termination.