The MySQL 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 MySQL installed and the root MySQL user configured. If this is not the case, install MySQL now. Most distributions will provide a convenient MySQL package which will set up everything for you, including the root user. After MySQL is installed, create the new database and user:

$ 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-0ubuntu0.12.10.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
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> CREATE DATABASE guacamole;
Query OK, 1 row affected (0.00 sec)

mysql> CREATE USER 'guacamole'@'localhost' IDENTIFIED BY 'some_password';
Query OK, 0 rows affected (0.00 sec)

mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole.* TO 'guacamole'@'localhost';
Query OK, 0 rows affected (0.00 sec)

mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.02 sec)

mysql> quit
Bye
$

The database and user can be named whatever you like, but these instructions will refer to both as "guacamole". Naturally, you should choose a real password for your user rather than the string "some_password" shown above.

The SQL scripts that create the database schema and default administrator user are included in the archive you downloaded within the schema/ directory. They are named such that they can be run in order with one command:

$ ls schema/
001-create-schema.sql  002-create-admin-user.sql  upgrade
$ cat schema/*.sql | mysql -u root -p guacamole
Enter password: password
$

If the operation is successful, all tables have been created successfully, and the database is now ready for use. All that is left now is to configure Guacamole to use the database we've created.

$ ls schema/upgrade/
upgrade-pre-0.8.2.sql
$ mysql -u root -p guacamole < schema/upgrade/upgrade-pre-0.8.2.sql
Enter password: password
$

Now that the database and user is created, and the SQL scripts have been run, we need to add a few properties to guacamole.properties such that Guacamole can connect to MySQL when authenticating users:

# Auth provider class
auth-provider: net.sourceforge.guacamole.net.auth.mysql.MySQLAuthenticationProvider

# MySQL properties
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole
mysql-username: guacamole
mysql-password: some_password

Be sure to specify the correct password for the MySQL user you created, and specify the correct database and username if you didn't use "guacamole". If you wish to only allow one user at a time to access any single connection, you can also limit concurrent access to connections:

mysql-disallow-simultaneous-connections: true

This is not required, but with the above property in place, users attempting to use a connection that is currently in use by another user will be denied access. By default, concurrent access is allowed.

You can also limit whether a single user is allowed to connect to the same connection or group concurrently. By default, this is enabled, as it has security implications when balancing groups are used, but you can explicitly disable this if you want to allow duplicate connections:

mysql-disallow-duplicate-connections: false

Now just restart Tomcat (or whatever servlet container you are using) and authentication will use MySQL.

After the MySQL authentication module is installed, you need to log in and change your password, and add whatever connections and additional users you need.

The default user is "guacadmin", with the default password of "guacadmin". You can change your password by editing your own user in the administration screen.

More detailed instructions for managing users and connections is given in Chapter 7, Using Guacamole in the section called “Administration”.

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 guacamole_user table contains the following columns:

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:

-- 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.

Note that versions of MySQL earlier than 5.5.5 do not have the SHA2 function. If you are using one of these versions, you will need to calculate the SHA-256 value manually (by using the sha256sum command, for example).

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 guacamole_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:

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 guacamole_connection_parameter table associated with its corresponding connection. This table contains the following columns:

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 guacamole_connection (connection_name, protocol) VALUES ('test', 'vnc');
SET @id = LAST_INSERT_ID();

-- Add parameters
INSERT INTO guacamole_connection_parameter VALUES (@id, 'hostname', 'localhost');
INSERT INTO guacamole_connection_parameter VALUES (@id, 'port', '5901');

Each connection group has an entry in the guacamole_connection_group table, with a one-to-many relationship to other groups and connections.

The guacamole_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:

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 guacamole_connection_group (connection_group_name, type)
     VALUES ('test', 'ORGANIZATIONAL');

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.