PIAM Installation

Install CIPAM Server

1. Download the Guacamole source code.

   https://guacamole.apache.org/releases/1.5.0/

   https://archive.apache.org/dist/guacamole/1.5.0/source/guacamole-client-1.5.0.tar.gz

   https://archive.apache.org/dist/guacamole/1.5.0/source/guacamole-server-1.5.0.tar.gz

2. Extract the file and navigate to its directory.

   tar -xvf guacamole-client-1.5.0.tar.gz

   tar -xvf guacamole-server-1.5.0.tar.gz

   

3. Build the CPAM Server using the downloaded source files(CIPAM Guacamole server directory).

   sudo ./configure --with-init-dir=/etc/init.d --enable-allow-freerdp-snapshots

   sudo make

   sudo make install

4. Update the installed library cache and reload the system

   sudo ldconfig

   sudo systemctl daemon-reload

5. Start guacd

   sudo systemctl start guacd

   sudo systemctl enable guacd

   

   Create a directory to store CPAM configuration files and extensions. These directories are used in later steps.

sudo mkdir -p /etc/guacamole/{extensions,lib}

Install CIPAM Web App

1. Install Apache Tomcat.

   

2. Download the CPAM Client

   https://archive.apache.org/dist/guacamole/1.5.0/binary/guacamole-1.5.0.war

   

3. Move the client to the Tomcat web directory.

   sudo mv guacamole-1.3.0.war /var/lib/tomcat9/webapps/guacamole.war

4. Restart both Apache Tomcat and Guacd.

   sudo systemctl restart tomcat9 guacd

   

Setting up Database Authentication

While CPAM does support basic user authentication via a user-mapping.xml file, it should only be used for testing. For this guide, we will use production-ready database authentication through MySQL/MariaDB.

1. Install either MySQL or MariaDB on your system.

   sudo apt install mariadb-server

2. Run the following command to perform the initial security configuration:

   sudo mysql_secure_installation

   Before populating the database, install the MySQL Connector/J library and Guacamole JDBC authenticator plugin.

3. Download the MySQL Connector/J (Java Connector). For this guide, download the platform-independent archived file.

   wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.26.tar.gz

4. Extract the tar file and copy it to /etc/guacamole/lib/.

   tar -xf mysql-connector-java-8.0.26.tar.gz

   sudo cp mysql-connector-java-8.0.26/mysql-connector-java-8.0.26.jar /etc/guacamole/lib/

5. Download the JDBC auth plugin for Apache Guacamole. This file can be found at http://guacamole.apache.org/releases/ by selecting the release version and then locating the “jdbc” file.

   https://archive.apache.org/dist/guacamole/1.5.0/binary/guacamole-auth-jdbc-1.5.0.tar.gz

6. Extract the tar file and copy it to /etc/guacamole/extensions/.t

   tar -xf guacamole-auth-jdbc-1.3.0.tar.gz

   sudo mv guacamole-auth-jdbc-1.3.0/mysql/guacamole-auth-jdbc-mysql-1.3.0.jar /etc/guacamole/extensions/

7. Log in to mysql as the root user.

   mysql -u root -p

   The prompt should change again to MySQL>.

8. While in the mysql prompt, change the root password, create a database, and create a new user for that database. When running the below commands, replace any instance of password with a secure password string for the mysql root user and the new user for your database, respectively.

   ALTER USER 'root'@'localhost' IDENTIFIED BY 'password';

   CREATE DATABASE guacamole_db;

   CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'password';

   GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';

   FLUSH PRIVILEGES;

   Exit the MySQL prompt by typing quit.

9. Locate the scheme files in the extracted directory for the JDBC plugin.

   cd guacamole-auth-jdbc-1.3.0/mysql/schema

10. Import those sql schema files into the MySQL database.

    cat *.sql | mysql -u root -p guacamole_db

11. Create the properties file for CPAM.

    sudo nano /etc/guacamole/guacamole.properties 

    

Extension Directory

Lib Directory

Access CIPAM in a Browser

With SSL

1. Create a new Admin user.

   Note:

   Before continuing with configuring CPAM, it’s recommended that you create a new admin account and delete the original.

   • Click the guacadmin user dropdown menu on the top right and select Settings.

   • Navigate to the Users tab and click the New User button.

   • Under the Edit User section, enter your preferred username and a secure password.

   • Under the Permissions section, check all the permissions.

   • Click Save to create a new user.

   • Log out of the current user and log in as the newly created user.

   • Click your username on the top left and select Settings from the dropdown menu.

   • Navigate to the Users tab and click the guacadmin user.

   • At the bottom of the Edit User screen, click Delete to remove the default user.

2. Create an SSH Connection

   To test CPAM, create a new connection in CPAM that opens up an SSH connection to the server.

   • After logging in to CPAM, click your username on the top left and select Settings from the dropdown menu.

   • Navigate to the Connections tab and click New Connection.

   • Under Edit Connection, enter a name for your new connection (such as “Guacamole SSH”) and select SSH as the Protocol.

If you do not wish to build Apache Guacamole entirely from the source, pre-built versions of the web application (.war) and all extensions are provided in binary form for convenience. Please note that the guacamole server must still be built and installed from the source.

Enabling SAML

SAML is a widely implemented and used Single Sign On (SSO) provider that allows applications and services to authenticate in a standard way and brokers those authentication requests to one or more back-end authentication providers. The SAML authentication extension allows CPAM to redirect to a SAML Identity Provider (IdP) for authentication and user services. This module does not provide any capability for storing or retrieving connections and must be layered with other authentication extensions that provide connection management.

Download the SAML authentication extension

CPAM’s SSO extensions are available separately from the main guacamole.war. The SSO extensions are packaged together in .tar.gz  file containing one extension for each supported SSO method:

The extension for the desired SSO method, in this case, guacamole-auth-sso-saml-1.5.1.jar from within the saml/ subdirectory, must ultimately be placed in GUACAMOLE_HOME/extensions.

By default, the recording storage extension will search within /var/lib/guacamole/recordings for the recordings associated with a connection. Unless you or a third-party installation tool have created this directory, this directory will not exist, and you will need to create it manually:

mkdir -p /var/lib/guacamole/recordings 

You can also use another directory of your choice if you override the default location using the recording-search-path property.