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:

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/lib/guacamole/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:

$ ls /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:

$ ls /var/lib/guacamole/classpath
guacamole-auth-jdbc-postgresql-0.9.6.jar
postgresql-9.4-1201.jdbc41.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!

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 -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_db;
Query OK, 1 row affected (0.00 sec)

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

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

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

mysql> quit
Bye
$

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

$ ls 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
$

$ mysql -u root -p guacamole_db < schema/upgrade/upgrade-pre-0.9.6.sql
Enter password: password
$

$ createdb guacamole_db
$ ls schema/
001-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 0 1
INSERT 0 4
INSERT 0 3
$

$ psql -d guacamole_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
$

Now that the database has been created, and all required SQL scripts have been run, we need to add a few properties 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.guacamole.net.auth.mysql.MySQLAuthenticationProvider

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

# Auth provider class
auth-provider: org.glyptodon.guacamole.auth.postgresql.PostgreSQLAuthenticationProvider

# MySQL properties
postgresql-hostname: localhost
postgresql-port: 5432
postgresql-database: guacamole_db
postgresql-username: guacamole_user
postgresql-password: some_password

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:

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

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.

If necessary, it is possible to modify the data backing the authentication module manually by executing SQL statements against the database. In general use, this will not be common, but if you need to bulk-insert a large number of users or connections, or you wish to translate an existing configuration automatically, 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.

-- 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)));

-- Create connection
INSERT INTO guacamole_connection (connection_name, protocol) VALUES ('test', 'vnc');

-- Determine the connection_id
SELECT * FROM guacamole_connection WHERE connection_name = 'test' AND parent_id IS NULL;

-- Add parameters to the new connection
INSERT INTO guacamole_connection_parameter VALUES (1, 'hostname', 'localhost');
INSERT INTO guacamole_connection_parameter VALUES (1, 'port', '5901');

-- Create connection group
INSERT INTO guacamole_connection_group (connection_group_name, type)
     VALUES ('test', 'ORGANIZATIONAL');