raer2015 Chapter 4. Datebase autnentication
Chapter 4. Database authentication
Guacamole supports authentication via MySQL or PostgreSQL databases through extensions available from the
project website. These extensions allows users and connections to be managed from within the web application. Unlike
the default, XML-driven authentication module, all changes to users and connections take effect immediately; users
need not logout and back in in order to see new connections.
The official database authentication also supports load balancing through the use of "balancing groups". When a
balancing group is created, it can be used like any other connection, but will use the least-used of its underlying
connections, spreading load evenly across any connections contained within.
Installing database support
The database authentication modules are not included in the main Guacamole bundle nor are they enabled by default.
‘You must use the download link provided in the downloads section of the main Guacamole site.
The downloaded .tar.gz file will contain several directories:
mysql/
Contains the MySQL authentication module as a . jar file, along with a schema/ directory containing the SQL
scripts required to set up the database.
The MySQL JDBC connector is not included. You must obtain the JDBC connector .jar from within the
"Connector/J" archive downloadable from MySQL's website.
postgresql/
Contains the PostgreSQL authentication module as a .
‘SQL scripts required to set up the database.
jar file, along with a schena/ directory containing the
The PostgreSQL JDBC driver is not included. You must obtain the JDBC driver . jar from PostareSQL's
website. The proper . jar file depends on the version of Java you have installed.
‘The authentication module . jar file for your database must be copied into the directory specified by the lib-directory
property in guacamole. properties, along with the your database's JDBC driver. If this property is not specified, you
will need to add it. On Linux servers, /var/1ib/guacanole/classpath is a good choice, but it can be whatever you
like.
After copying the files in place, check to make sure everything looks sane.
‘The contents of for a MySQL database should match the files shown here:
$ 1s /var/lib/guacamole/classpath
guacamole-auth- jdbc-mysql-0.9.6.jar
mysql-connector- java-5.1.23-bin. jar
$
For PostgreSQL, the contents should match the files shown here:
$ 1s /var/1ib/guacanole/classpath
guacamole-auth-jdbc-postgresql-@.9.6.jar
postgresql-9.4-1201.jdbe41. jar
$
Each of the . jar files above is either the authentication module itself (guacamole-auth- jdbc-*-0.9.6. jar) or the
corresponding JDBC driver. if any of these files is missing, authentication will not work!
Creating the database
tipiiguac-devcrgldclgugfdbe-auh hitraer2015 Chapter 4. Datebase autnentication
The database authentication module will need a database to store all authentication data and a user to use only for
data access and manipulation. You could use an existing database and existing user, but for the sake of simplicity and
security, these instructions assume you will be creating a new database and new user that will be used only by
Guacamole and only for this authentication module,
At this point, you need either MySQL or PostgreSQL installed, and must have sufficient access to create and
administer databases. If this is not the case, install your database of choice now. Most distributions will provide a
convenient MySQL or PostgreSQL package which will set up everything for you, including the root database user, if
applicable.
For the sake of clarity, these instructions will refer to the database as “guacamole_db" and the user as
"guacamole_user’, but the database and user can be named whatever you like. Naturally, you should also choose a
real password for your user rather than the string "some_password” used as a placeholder below.
MySQL
fusing MySQL, you must create your database and user first:
$ mysql -u root -p
Enter password: password
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 233
Server version: 5.5.29-Oubuntu@.12.1@.1 (Ubuntu)
Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
Type ‘help;’ or '\h' for help. Type '\c' to clear the current input statement.
mysql> CREATE DATABASE guacamole_db ;
Query OK, 1 row affected (0.88 sec)
mysql> CREATE USER * guacamole_user’ @'localhost' IDENTIFIED BY ' some_password ';
Query OK, @ rows affected (@.8@ sec)
mysql> GRANT SELECT, INSERT,UPDATE,DELETE ON guacamole _db .* TO ‘ guacamole_user’ @* localhost’ ;
Query Ok, @ rows affected (0.00 sec)
mysql> FLUSH PRIVILEGES;
Query OK, @ rows affected (8.02 sec)
mysql> quit
Bye
$
Once the database and user are created, the database schema must be applied by running the supplied SQL scripts.
‘These SQL scripts are included in the nysq1/schema/ directory of the archive you downloaded from the Guacamole
website. They are named such that they can be run in order with one command:
$ 1s schema/
ee1-create-schema.sql @22-create-admin-user.sql upgrade
$ cat schema/*.sql | mysql -u root -p guacamole_db
Enter password: password
$
I the operation is successful, all tables have been crealed successfully, and the database is now ready for use.
Important
bipiigue-devcxgldolguaabo-auh hilraer2015 Chapter 4. Datebase autnentication
If you are upgrading from an older version of Guacamole that lacked support for connection
groups (older than 0.8.2), you should instead run the upgrade script located within the upgrade/
directory:
$ 1s schema/upgrade/
upgrade-pre-0.8.2.sql upgrade-pre-0.9.6.sql
$ mysql -u root -p guacamole db < schema/upgrade/upgrade-pre-0.8.2.sql
Enter password: password
$
If you are upgrading from a version of Guacamole before 0.9.6, the default permissions
associated with new users have changed such that users can change their own passwords. You
may, if desired, run the upgrade script to migrate any existing users to the new permissions:
$ mysql -u root -p guacamole db < schema/upgrade/upgrade-pre-0.9.6.sql
Enter password: password
$
PostgreSQL
fusing PostgreSQL, the database and schema must be created first:
$ createdb guacamole_db
$ 1s schema/
@e1-create-schema.sql 002-create-admin-user.sql.
$ cat schema/*.sql | psql -d guacamole db -f -
CREATE TYPE
CREATE TYPE
CREATE TYPE
CREATE TABLE
CREATE INDEX
INSERT
en
INSERT @ 4
INSERT @ 3
$
Once the database exists, you can safely create a new user for the database, and grant that user sufficient privileges to
manage the contents of ail tables in the database’
$ psql -d guacanole_db
psql (9.3.6)
Type "help" for help.
guacamole=# CREATE USER guacamole_user WITH PASSWORD ' some_password
CREATE ROLE
guacamole=# GRANT SELECT,INSERT,UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO guacamole_user ;
GRANT
guacamole=# GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO guacamole_user ;
GRANT
guacamole=# \q
$
‘As support for PostgreSQL was not added until 0.9.6, no upgrade scripts are necessary to migrate the databases of
earlier versions of Guacamole; no such databases exist.
Configuring Guacamole
Now that the database has been created, and all required SQL scripts have been run, we need to add a few properties
bipiigue-devcxgldolguadbo-auh hil 29raer2015 Chapter 4. Datebase autnentication
to guacamole. properties such that Guacamole will load the appropriate authentication module and connect to the
proper database. These properties are specific to the database being used.
To use a MySQL database, you will need to specify the following:
# Auth provider class
auth-provider: net. sourceforge. guacanole.net.auth.mysql.MySQLAuthenticationProvider
# MySQL properties
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: some_password
For PostgreSQL the properties are similar, but with different prefixes:
# Auth provider class
auth-provider: org.glyptodon.guacanole. auth. postgresql PostgreSQL AuthenticationProvider
# MySQL properties
postgresql -hostnam
postgresql-port: 5432
postgresql-database: guacamole_db
postgresql-username: guacamole_user
postgresql-password: some_password
localhost
Be sure to specify the correct password for the MySQL or PostgreSQL user you created, and specify the correct
database and username if you didn't use "guacamole_db" and "guacamole_user".
The database authentication module also provides configuration options to restrict concurrent use of connections if
desired:
# MySQL
mysql-disallow-simultaneous-connections: true
# PostgreSQL
postgresql-disallow-simultaneous-connections: true
This is not required, but with the above property in place, users attempting to use a connection that is already in use by
another user will be denied access. By default, concurrent access is allowed. This does not affect balancing groups, but
does affect the usage of connections within balancing groups.
Concurrent access to balancing groups is restricted by default, and while balancing groups can be used by any number
of users simultaneously, each individual user may only have one active connection to a balancing group. You can
change this if you wish, but beware that individual users will then be able to exhaust the available connections of a
balancing group.
# mysQu
mysql-disallow-duplicate-connections: false
# PostgreSQL
postgresql-disallow-duplicate-connections: false
Once you have guacamole. properties modified appropriately, restart Tomcat (or whatever servlet container you are
using) and Guacamole will use your database for authentication. Be sure to watch the logs in case something is wrong
with the configuration, and remember that, for security reasons, Guacamole will always report authentication errors as
“invalid login’ regardless of the true cause.
Logging
bipiigue-devcxgldolguadbo-auh hilraer2015 Chapter 4. Datebase autnentication
The default Guacamole user created by the provided SQL scripts is “guacadmin", with a default password of
“guacadmin”. Once you have the database authentication working, you should change your password immediately by
editing your own user in the administration screen.
More detailed instructions for managing users and connections is given in Chapter 8. Administration.
Modifying data manually
If necessary, itis possible to modify the data backing the authentication module manually by executing SQL statements
against the database. In general use, this will nt be common, but if you need to bulk-insert a large number of users or
connections, or you wish to translate an existing configuration automaticaly, you will need to know how everything is
laid out at a high level
This section assumes knowledge of SQL and your chosen database, and that whatever you need to do can be
accomplished if only you had high-level information about Guacamole’s SQL schema.
Users
Every user has a corresponding entry in the guacamole_user table, Each user has a corresponding unique username
and salted password. The salted password is split into two columns: one containing the salt, and the other containing
the password hashed with SHA-256.
The guacanole_user table contains the following columns:
user_id
The unique integer associated with each user. This value is generated automatically when a new entry is
inserted into the guacamole_user table.
username
The unique name associated with each user. This value must be specified manually, and must be different
from any existing username in the table. References to users in other tables use the value from user_id, not
username.
password_hash
The result of hashing the user's password concatenated with the contents of password_salt using SHA-256.
The salt is appended to the password prior to hashing
Although passwords set through Guacamole will always be salted, it is possible to use unsalted password
hashes when inserted manually or through an external system. If password_sall is NULL, the password_hash
will be handled as a simple unsalted hash of the password
password _salt
‘A32-byle random value. When a new user is created from the web interface, this value is randomly generated
using a cryptographically-secure random number generator.
This will always be set for users whose passwords are set through Guacamole, but it is possible to use
unsalted password hashes when inserted manually or through an extemal system. if password_salt is NULL,
the password_hash will be handled as a simple unsalted hash of the password.
Important
If you choose to manually set unsalted password hashes, please be sure you understand the
security implications of doing so.
In the event that your database is compromised, finding the password for a salted hash is
‘computationally infeasible, but finding the password for an unsalted hash is often not. In many
‘cases, the password which corresponds to an unsalted hash can be found simply by entering the
hash into a search engine like Google.
If creating a user manually, the main complication is the salt, which must be determined before the INSERT statement
can be constructed, but this can be dealt with using variables, For MySQL:
bipiigue-devcxgldolguadbo-auh hilraer2015 Chapter 4. Datebase autnentication
-- Generate salt
SET @salt = UNHEX(SHA2(UUID(), 256);
-- Create user and hash password with salt
INSERT INTO guacamole_user (username, password_salt, password_hash)
VALUES (‘myuser", @salt, UNHEX(SHA2(CONCAT(‘mypassword', HEX(@salt)), 256)));
This sort of statement is useful for both creating new users or for changing passwords, especially if all administrators
have forgotten theirs,
If you are not using MySQL, or you are using a version of MySQL that lacks the SHA2 function, you will need to
calculate the SHA-256 value manually (by using the sha256sum command, for example).
Connections and parameters
Each connection has an entry in the guacamole_connection table, with a one-to-many relationship to parameters,
stored as name/value pairs in the guacamole_connection_parameter table.
The guacanole_connection table is simply a pairing of a unique and descriptive name with the protocol to be used for
the connection. It contains the following columns:
connection_id
The unique integer associated with each connection. This value is generated automatically when a new entry
is inserted into the guacamole_connection table.
connection_name
The unique name associated with each connection. This value must be specified manually, and must be
different from any existing connection name in the same connection group. References to connections in other
tables use the value from connection _id, not connection_name.
protocol
The protocol to use with this connection. This is the name of the protocol that should be sent to guacd when
connecting, for example "vnc" or "rdp"
Parent_id
The unique integer associated with the connection group containing this connection, or NULL if this connection
is within the root group.
As there are potentially multiple parameters per connection, where the names of each parameter are completely
arbitrary and determined only by the protocol in use, every parameter for a given connection has an entry in table
guacanole_connection_parameter table associated with its corresponding connection. This table contains the
following columns:
connection_id
The connection_id value from the connection this parameter is for
parametor_name
The name of the parameter to set. This is the name listed in the documentation for the protocol specified in the
associated connection,
parameter_value
The value to assign to the parameter named. While this value is an arbitrary string, it must conform to the
requirements of the protocol as documented for the connection to be successful
‘Adding a connection and corresponding parameters is relatively easy compared to adding a user as there is no salt to
generate nor password to hash
-- Create connection
INSERT INTO guacanole_connection (connection_name, protocol) VALUES (' test ',
"vnc ")5
bipiigue-devcxgldolguadbo-auh hilraer2015 Chapter 4. Datebase autnentication
-- Determine the connection_id
SELECT * FROM guacamole connection WHERE connection_name = ‘test ' AND parent_id IS NULL
-- Add paraneters to the new connection
INSERT INTO guacamole_connection_paraneter VALUES (1, ‘hostname’, ' localhost ');
INSERT INTO guacaole_connection_paraneter VALUES (1, ‘port’, '59@1');
Usage history
When a connection is initiated or terminated, a corresponding entry in the guacamole_connection_history table is
created or updated respectively, Each entry is associated with the user using the connection, the connection itself, and
the time the connection started. If the connection has ended, the end time is also stored.
Itis very unlikely that a user will need to update this table, but knowing the structure is potentially useful if you wish to
generale a report of Guacamole usage. The guacamole_connection_history table has the following columns.
history_i
The unique integer associated with each history record. This value is generated automatically when a new
entry is inserted into the guacanole_connection_history table.
usor_id
The value of the user_id from the entry in guacamole_user associated with the user using the connection,
connection_id
The value of the connection_jd from the entry in guacanole_connection associated the connection being
used.
start_date
The time at which the connection was started by the user specified, Despite its name, this column also stores
time information in addition to the date.
end_date
The time at which the connection ended. If the connection is stil active, the value in this column will be NULL.
Despite its name, this column also stores time information in addition to the date.
Connection groups
Each connection group has an entry in the guacanole_connection_group table, with a one-to-many relationship to
other groups and connections.
The guacanole_connection_group table is simply a pairing of a unique and descriptive name with a group type,
which can be either ORGANIZATIONAL or BALANCING. It contains the following columns
connection_group_l
‘The unique integer associated with each connection group. This value is generated automatically when a new
entry is inserted into the guacanole_connection_group table.
connection_group_name
The unique name associated with each connection group. This value must be specified manually, and must be
different from any existing connection group name in the same connection group. References to connections
in other tables use the value from connection_group_id, not connection_group_name.
type
The type of this connection group. This can be either ORGANIZATIONAL or BALANCING,
parent_i
The unique integer associated with the connection group containing this connection group, or NULL if this
connection group is within the root group.
bipiigue-devcxgldolguadbo-auh hil 79raer2015 Chapter 4. Datebase autnentication
Adding a connection group is even simpler than adding a new connection as there are no associated parameters
stored in a separate table:
-- Create connection group
INSERT INTO guacanole_connection_group (connection_group_nane, type)
VALUES (* test", ' ORGANIZATIONAL *);
Permissions
There are three permissions tables in the schema which correspond to the three types of permissions in Guacamole’s
authentication model: system permissions, which control operations that affect the system as a whole, and user and
connection permissions, which control operations that affect specific, existing users or connections respectively.
Systom permissions
‘System permissions are defined by entries in the guacanole_system_permission table. Each entry grants permission
for a specific user to perform a specific system operation.
The guacanole_systen_permission table contains the following columns:
user_id
The value of the user_id column of the entry associated with the user owning this permission.
permission
The permission being granted. This column can have one of three possible values: ADMINISTER, which grants
the ablity to administer the entire system (essentially a wildcard permission), CREATE_CONNECTION, which
grants the ability to create connections, CREATE_CONNECTION GROUP, which grants the ability to create
connections groups, or CREATE_USER, which grants the ability to create users.
User permissions
User permissions are defined by entries in the guacamole_user_permission table. Each entry grants permission for a
specific user to perform a specific operation on another existing User.
The guacanole_user_permission table contains the following columns:
user_id
The value of the user_id column of the entry associated with the user owning this permission.
affected_usor_id
‘The value of the user_id column of the entry associated with the user affected by this permission. This is the
user that would be the object of the operation represented by this permission.
permission
‘The permission being granted. This column can have one of four possible values: ADMINISTER, which grants
the ability to add or remove permissions which affect the user, READ, which grants the ability to read data
associated with the user, UPDATE, which grants the ability to update data associated with the user, or DELETE,
which grants the ability to delete the user.
Connection permissions
Connection permissions are defined by entries in the guacanole_connection_permission table, Each entry grants
permission for a specific user to perform a specific operation on an existing connection.
The guacanole_connection_permission table contains the following columns’
‘The value of the user_id column of the entry associated with the user owning this permission,
connection_id
bipiigue-devcxgldolguadbo-auh hilraer2015 Chapter 4. Datebase autnentication
The value of the connection_id column of the entry associated with the connection affected by this permission.
This is the connection that would be the object of the operation represented by this permission,
pormission
The permission being granted, This column can have one of four possible values: ADMINISTER, which grants
the ability to add or remove permissions which affect the connection, READ, which grants the ability to read
data associated with the connection (a prerequisite for connecting), UPDATE, which grants the ability to update
data associated with the connection, or DELETE, which grants the ability to delete the connection
Connection group permissions
Connection group permissions are defined by entries in the guacamole_connection_group_permission table, Each
entry grants permission for a specific user to perform a specific operation on an existing connection group.
‘The guacanole_connection_group_permission table contains the following columns:
The value of the user_id column of the entry associated with the user owning this permission,
connection_group_id
The value of the connection_group_id column of the entry associated with the connection group affected by
this permission. This is the Connection group that would be the object of the operation represented by this
permission
permission
The permission being granted. This column can have one of four possible values: ADMINISTER, which grants
the ability to add or remove permissions which affect the connection group, READ, which grants the abiliy to
read data associated with the connection group, UPDATE, which grants the ability to update data associated
with the connection group, or DELETE, which grants the abllty to delete the connection group (and implicitly its
contents).
bipiigue-devcxgldolguadbo-auh hil