Keeper Connection Manager supports multiple authentication mechanisms which can be enabled through installing additional packages.

Advanced Linux Install Method

For Advanced Linux Install method, packages are available through the Keeper Connection Manager repository and automatically place the necessary Apache Guacamole extension within /etc/guacamole/extensions and any necessary dependencies (such as database drivers) within /etc/guacamole/lib.

The "Test Installation" using the user-mapping.xml file is meant as a quick means of verifying the functionality of Guacamole but is not supported for production deployments.

All authentication methods packaged listed below are production-ready:

• Authenticating users with LDAP

• Authenticating users with SAML 2.0

• Authenticating users with OpenID Connect

• Using Guacamole with a MySQL Database

• Using Guacamole with a PostgreSQL Database

• Using Guacamole with a SQL Server Database

Using a database like MySQL, PostgreSQL, or SQL Server enables additional features within Keeper Connection Manager, including connection sharing and a web-based administration interface. The LDAP authentication allows authentication to be provided through an LDAP directory such as OpenLDAP or Active Directory, and can be combined with a database, thus avoiding the need to store connections within the LDAP directory using schema modifications.

Multi-factor Authentication

If you wish to enable multi-factor authentication in front of Keeper Connection Manager, you may do so with Duo or TOTP. Multi-factor authentication is supported in front of any of the above production-ready authentication mechanisms, however keep in mind that a database is always required for TOTP:

• Using Duo for Multi-factor Authentication

• Using TOTP for Multi-factor Authentication

Important Note: MFA cannot be activated if the SAML authentication method is already active.

Overview

Keeper Connection Manager can be configured to authenticate users with any SAML 2.0 compatible identity provider. Users can be forced to login with SAML, or you can make SAML an optional login link from the home screen.

Instructions for popular Identity Providers is below.

Azure Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Microsoft Azure.

(1) In Azure, go to Enterprise Applications and Create a new application.

(2) Give the Enterprise Application a name, and then select "non-gallery" application.

(3) Set up Single Sign On with SAML.

(4) Configure for SAML

(5) Set up the SAML properties to point Azure to your Keeper Connection Manager installation URL:

(6) To support Azure Group to Keeper Connection Manager User Group mappings, you can add a Group claim by editing the Attributes & Claims then adding a Group Claim.

When prompted, you can decide whether the group claim is always sent, or only for specific groups or assigned users.

(7) Assign users and/or groups to the Keeper Connection Manager application, as you would normally do with any SAML connected app.

(8) Download the Azure Metadata file and save to your local machine as metadata.xml

The Azure side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

(9) Add the KCM Logo

From the "Properties" screen of the Enterprise Application, upload the KCM logo. The file can be downloaded below.

Here's how the logo will look:

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

$ sudo yum install kcm-guacamole-auth-sso-saml

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

##
## [SAML-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP.
##
## The SAML IdP will typically provide this information in advance in the form
## of an XML file. If no such XML file is provided, or if information is
## missing from that XML file, additional properties will need to be specified
## to provide that information.
##
## The key pieces of information required are:
##
##  * The URL of the SAML endpoint used by the IdP.
##  * The "entity ID" that should be used by Guacamole to identify itself with
##    the IdP.
##
## If the SAML IdP provides an XML metadata file, it is unusual for that file
## to not contain both of the above pieces of information.
##
## THIS INFORMATION IS REQUIRED if the SAML extension will be used.
##

saml-idp-metadata-url: file:///etc/guacamole/metadata.xml
saml-entity-id: https://glyptodon.mycompany.com

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

##
## [SAML-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the SAML IdP
## when authenticating the user. This information defines how the SAML IdP
## should send identity assertions back to the Guacamole server if their
## identity is confirmed.
##
## THIS PROPERTY IS REQUIRED if the SAML extension will be used. It is not
## otherwise possible for Guacamole to know its own public-facing URL,
## particularly in a production deployment that is expected to use SSL
## termination.
##

saml-callback-url: https://glyptodon.mycompany.com

The 3rd section contains the SAML group attribute that can be used for mapping IdP Groups to Keeper Connection Manager Groups. This is useful for assigning permissions to Connections based on a Group attribute from your identity provider. The below example is referencing a Microsoft Azure configuration.

##
## [SAML-3] Identity mapping
##
## How identity assertions received form the SAML IdP should be mapped back to
## user and group identities. The mapping for user identities is already known
## by the SAML standard, but the mapping for user groups can vary. If your SAML
## IdP provides user group information in addition to user identities, the
## attribute used by your SAML IdP to define those groups within assertions
## should be provided here.
##

saml-group-attribute: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

The 4th section contains optional parameters that can be set.

##
## [SAML-4] Request/response compression
##
## Whether compression should be used for requests sent to the SAML IdP, and
## whether compression should be requested for responses from the SAML IdP.
## By default, compression will be used for both requests and responses.
##

#saml-compress-request: true
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, ensure that the saml-group-attribute parameter is defined to match the Identity Provider Group Attribute. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.

If the group name attribute from the identity provider is not easy to read, this may end up requiring you to create Group Names that look like below:

Okta Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Okta.

(1) In Okta, go to Admin > Applications > Create App Integration and select SAML 2.0. Click Next.

(2) Give the Enterprise Application a name and upload the logo file linked below then click Next.

The image logo is here:

(3) Configure the SAML Settings

The SAML configuration should match the format as seen below:

• Replace demo3.lurey.com with the URL of your Keeper Connection Manager domain.

• Ensure the full path appears, e.g. https://DOMAIN/api/ext/saml/callback

• For the Audience URI, use the path to the Login screen (remove the trailing slash). For example, https://demo3.lurey.com

Scroll down to the Group Attribute Statements. To send the group attribute, set the name to "groups", and the name format to "Basic". If you would like ALL groups assigned to the user to be sent to Keeper Connection Manager, select the "Matches regex" with a value of ".*"

Click Next.

(4) In the Feedback section, make the selections as appears below.

(5) Assign users and/or groups to the Keeper Connection Manager application, as you would normally do with any SAML connected app.

(6) Download the Okta Metadata file and save to your local machine as metadata.xml

The location of the metadata file depends on your version of the Okta interface. In this example there is a link called "Identity Provider metadata" on the application page. There may also be a text box that contains the metadata which you can copy and paste into a local file on your computer.

The metadata XML file could also be linked in the Sign On tab > SAML Signing Certificate section under "Actions".

Save the resulting metadata.xml file by selecting "Save page as..." in your browser.

The Okta side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

$ sudo yum install kcm-guacamole-auth-sso-saml

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

##
## [SAML-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP.
##
## The SAML IdP will typically provide this information in advance in the form
## of an XML file. If no such XML file is provided, or if information is
## missing from that XML file, additional properties will need to be specified
## to provide that information.
##
## The key pieces of information required are:
##
##  * The URL of the SAML endpoint used by the IdP.
##  * The "entity ID" that should be used by Guacamole to identify itself with
##    the IdP.
##
## If the SAML IdP provides an XML metadata file, it is unusual for that file
## to not contain both of the above pieces of information.
##
## THIS INFORMATION IS REQUIRED if the SAML extension will be used.
##

saml-idp-metadata-url: file:///etc/guacamole/metadata.xml
saml-entity-id: https://demo3.lurey.com

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

##
## [SAML-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the SAML IdP
## when authenticating the user. This information defines how the SAML IdP
## should send identity assertions back to the Guacamole server if their
## identity is confirmed.
##
## THIS PROPERTY IS REQUIRED if the SAML extension will be used. It is not
## otherwise possible for Guacamole to know its own public-facing URL,
## particularly in a production deployment that is expected to use SSL
## termination.
##

saml-callback-url: https://demo3.lurey.com

The 4th section contains optional parameters that can be set.

##
## [SAML-4] Request/response compression
##
## Whether compression should be used for requests sent to the SAML IdP, and
## whether compression should be requested for responses from the SAML IdP.
## By default, compression will be used for both requests and responses.
##

#saml-compress-request: true
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, simply create a matching group name with the proper assignments. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.

Google Workspace Configuration

The first step regardless of installation method is to configure your SAML 2.0 identity provider using Google Workspace.

(1) Login to Google Workspace at https://admin.google.com****

Visit the Apps > Web and Mobile Apps screen.

(2) Select "Add App" and select "Add Custom SAML App".

Enter an application name and description. You can also upload a Keeper Connection Manager logo. The image logo is here:

Click Continue.

(3) Download the metadata.xml file

...and then click Continue

(4) Configure the SAML Settings

Update 3 fields: ACS URL, Entity ID and Name ID format.

• The ACS URL needs to start with your Keeper Connection Manager domain followed by "/api/ext/saml/callback".

• The Entity ID is just the Keeper Connection Manager domain.

• The Name ID format must be EMAIL

Click Continue.

(5) Assign group membership (Optional)

You can now assign Group Membership to the Keeper Connection Manager application, which is optional. If you would like to assign a group, make sure that the "App Attribute" is groups (lowercase). Then click FINISH.

(6) Enable Access

After creating the SAML app, it is not yet active for all users. To enable access, click on View details and turn the application ON.

The Google Workspace side of the setup is complete. Note if you change anything, you need to re-download a new metadata.xml file.

Next: KCM Configuration

Advanced Linux Install Method

If you have installed Keeper Connection Manager using the advanced linux install method, setting up SAML can be performed following the steps below.

Installing SAML support for Guacamole

Keeper Connection Manager packages Guacamole’s SAML support within the kcm-guacamole-auth-sso-saml package:

$ sudo yum install kcm-guacamole-auth-sso-saml

Connecting Guacamole to SAML

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the SAML installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “SAML-1” and defines the IdP configuration. Uncomment the saml-idp-metadata-url and saml-entity-id property. You'll need to reference the IdP's metadata file and Entity ID.

##
## [SAML-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP.
##
## The SAML IdP will typically provide this information in advance in the form
## of an XML file. If no such XML file is provided, or if information is
## missing from that XML file, additional properties will need to be specified
## to provide that information.
##
## The key pieces of information required are:
##
##  * The URL of the SAML endpoint used by the IdP.
##  * The "entity ID" that should be used by Guacamole to identify itself with
##    the IdP.
##
## If the SAML IdP provides an XML metadata file, it is unusual for that file
## to not contain both of the above pieces of information.
##
## THIS INFORMATION IS REQUIRED if the SAML extension will be used.
##

saml-idp-metadata-url: file:///etc/guacamole/metadata.xml
saml-entity-id: https://demo3.lurey.com

The second section contains the callback URL that is used by the IdP. This is typically set to the user-facing URL of the Keeper Connection Manager service.

##
## [SAML-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the SAML IdP
## when authenticating the user. This information defines how the SAML IdP
## should send identity assertions back to the Guacamole server if their
## identity is confirmed.
##
## THIS PROPERTY IS REQUIRED if the SAML extension will be used. It is not
## otherwise possible for Guacamole to know its own public-facing URL,
## particularly in a production deployment that is expected to use SSL
## termination.
##

saml-callback-url: https://demo3.lurey.com

The 4th section contains optional parameters that can be set.

##
## [SAML-4] Request/response compression
##
## Whether compression should be used for requests sent to the SAML IdP, and
## whether compression should be requested for responses from the SAML IdP.
## By default, compression will be used for both requests and responses.
##

#saml-compress-request: true
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

KCM Final Setup

Once you have activated the SAML module, there will be a new "Sign in with SAML" link on the login screen of the application as seen below:

When setting up your user identities in the Settings area, if you would like a user to login with SAML / SSO, just leave the "password" field empty.

If you would like to automatically mapping Group assignments in the identity provider to Keeper Connection Manager Groups, simply create a matching group name with the proper assignments. The name of the Group in Keeper Connection Manager needs to match this identifier exactly in order for the mapping to work.

Keeper Connection Manager provides support for TOTP as a second authentication factor, verifying the identities of enrolled users using authentication codes generated with the TOTP standard. To make use of TOTP support, a database authentication mechanism will need be configured, as well, such as MySQL or PostgreSQL. Only once authentication has succeeded through another installed method will TOTP be used to verify the identity of the user, and a database is specifically required for storage of the key that Guacamole and the user's authentication device will use to generate authentication codes.

Installing TOTP support for Keeper Connection Manager and Guacamole

Keeper Connection Manager packages Guacamole’s TOTP support within the kcm-guacamole-auth-totp package:

$ sudo yum install kcm-guacamole-auth-totp

The Guacamole-side installation of TOTP support within Keeper Connection Manager consists solely of the kcm-guacamole-auth-totp package. Nothing else needs to be installed except for Guacamole itself and some other means of authentication. If Guacamole has not yet been installed and confirmed to work with a database authentication method, that should be done first before attempting to set up TOTP.

Unlike most other extensions, no additional configuration information is typically needed for the TOTP support to work. All configurable values have defaults which are accepted by widely used TOTP implementations like Google Authenticator. You will only need to specify additional configuration information if your authentication devices differ from these defaults:

If the above are acceptable, then no configuration changes need to be made and you should proceed to the "Completing installation" section below. If any of the above need to be changed, you will need to edit /etc/guacamole/guacamole.properties to specify the appropriate values. These properties are documented separately in detail:

• TOTP Configuration Properties

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

$ sudo systemctl restart tomcat

After TOTP support has been installed and Guacamole has been restarted, only users that exist within the database will automatically be enrolled in TOTP. Valid users that exist only outside the database will be able to log in, but will not be automatically enrolled with TOTP.

If you are using a database alongside LDAP or Active Directory and want to require all users to use TOTP, you should be sure to set the corresponding property within /etc/guacamole/guacamole.properties to enforce existence of database accounts for all logins. Each supported database has its own variant of this property:

This is particularly important if the database's concept of identity may differ from your LDAP server's concept of identity. For example, usernames within PostgreSQL are case-sensitive, but usernames within Active Directory typically are not.

Keeper Connection Manager provides support for Duo as a second authentication factor, automatically verifying user identity with Duo after the user is initially authenticated. To make use of Duo support, some other authentication mechanism will need be configured, as well, such as MySQL, PostgreSQL, or LDAP. Only once authentication has succeeded through another installed method will Duo be used to verify the identity of the user.

Installing Duo support for Guacamole

Keeper Connection Manager packages Guacamole’s Duo support within the kcm-guacamole-auth-duo package:

$ sudo yum install kcm-guacamole-auth-duo

The Guacamole-side installation of Duo support within Keeper Connection Manager consists solely of the kcm-guacamole-auth-duo package. Nothing else needs to be installed except for Guacamole itself and some other means of authentication. If Guacamole has not yet been installed and confirmed to work with some other authentication method, that should be done first before attempting to set up Duo.

Registering Guacamole with Duo

For Duo to be integrated with any application, that specific instance of the application must first be registered with the Duo service. Duo does not provide a specific integration option for Guacamole, but Guacamole’s Duo support uses Duo’s generic authentication API which they refer to as the “Web SDK”. To use your Guacamole deployment with Duo, you will need to add it to your Duo account as a new “Web SDK” application from within the “Applications” tab of the admin panel.

Once this has been done, Duo will expose several properties specific to your Guacamole deployment: the integration key, secret key, and API hostname. These values can be found within the application’s “Details” section in your Duo account, and will need to be copied into /etc/guacamole/guacamole.properties:

$ sudo vi /etc/guacamole/guacamole.properties

The relevant properties can be found in the “DUO-1” section:

##
## [DUO-1] Duo application integration details
##
## The API hostname, integration key, and secret key provided for you by Duo
## when you registered Guacamole in Duo's "Admin" panel. Each of these values
## is required and is generated by Duo.
##

#duo-api-hostname:    XXXXXXXX.duosecurity.com
#duo-integration-key: 0123456789ABCDEF0123
#duo-secret-key:      0123456789ABCDEF0123

Generating the application key

The Duo “Web SDK” requires that an arbitrary and random key be generated for each application. This key resides strictly on the side of the application, and is not registered with Duo.

Any random value containing at least 40 characters will suffice. To quickly grab 40 random characters from /dev/random:

$ tr -dc 'a-zA-Z0-9' < /dev/random | head -c40; echo
xqZKJODwg7ouwxdqU9hvuaWhE6lQFspijY0ofg8I
$

This value must then be copied within the duo-application-key property, which can be found in the "DUO-2" section of guacamole.properties:

##
## [DUO-2] Duo application key
##
## An arbitrary and random key to use when communicating with the Duo service.
## This key MUST be manually generated, and MUST BE AT LEAST 40 CHARACTERS.
##

#duo-application-key: abcdefghijklmnopqrstuvwxyz0123456789ABCD

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

$ sudo systemctl restart tomcat

Installing OpenID Connect support for Guacamole

Keeper Connection Manager packages Guacamole’s OpenId Connect support within the kcm-guacamole-auth-sso-openid package:

$ sudo yum install kcm-guacamole-auth-sso-openid

Connecting Guacamole to OpenID Connect

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the OpenID Connect installation:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “OPENID-1” and defines the IdP configuration. Uncomment the properties in this section and edit them according to your identity provider setup.

##
## [OPENID-1] Identity provider details
##
## The details of the identity provider (IdP) that Guacamole should use for
## authentication. These properties dictate how Guacamole should communicate
## with the IdP, including the how users should be redirected for
## authentication by the IdP. THIS INFORMATION IS REQUIRED if the OpenID
## extension will be used.
##
## If your IdP implements "OpenID Connect Discovery", these values can be
## found within the JSON file hosted at:
##
##   https://identity-provider/.well-known/openid-configuration
##
## where "https://identity-provider" is the base URL of the IdP.
##

#openid-authorization-endpoint: https://myprovider.example.net/sso/openid/auth
#openid-jwks-endpoint: https://myprovider.example.net/sso/openid/certs
#openid-issuer: https://myprovider.example.net

The second section contains the Keeper Connection Manager server information that is used by the IdP.

##
## [OPENID-2] Guacamole server details
##
## The details of the Guacamole server that should be provided to the OpenID
## Connect IdP when authenticating the user. This information defines how the
## OpenID Connect IdP should send identity assertions back to the Guacamole
## server if their identity is confirmed. THESE PROPERTIES ARE REQUIRED if
## the OpenID extension will be used.
##

#openid-client-id: abcd1234-xyz.apps.myprovider.example.net
#openid-redirect-uri: https://myserver.example.net

The 3rd section contains the OpenID Connect identity mappings.

##
## [OPENID-3] Identity mapping
##
## How identity assertions received form the OpenID Connect IdP should be
## mapped back to user and group identities. Mapping users and groups is
## flexible within OpenID, with the definition of user/group identity left
## to the application to determine from the various assertions ("claims")
## returned by the OpenID IdP in response to successful authentication.
##
## By default, Guacamole will use the "email" claim as the username and the
## content of the "groups" claim (if present) as the set of associated user
## groups. OpenID IdP implementations may support additional claims that may
## be more appropriate for your use case. If using different claims from the
## defaults, the "openid-scope" property must be adjusted so that Guacamole
## knows to request those claims from the IdP.
##

#openid-scope: openid email profile
#openid-username-claim-type: email
#openid-groups-claim-type: groups

The 4th section contains optional parameters that can be set.

##
## [OPENID-4] Clock skew and timeouts
##
## By default, clock skew between the Guacamole server and the OpenID IdP of up
## to 30 seconds is tolerated, tokens generated by the OpenID IdP are valid for
## no longer than 5 hours, and the "nonce" generated for each OpenID request by
## Guacamole will remain valid for no longer than 10 minutes.
##
## If necessary, these values can be overridden. Clock skew is specified in
## seconds, and token/nonce validity is specified in minutes.
##

#openid-allowed-clock-skew: 30
#openid-max-token-validity: 300
#openid-max-nonce-validity: 10
#saml-compress-response: true

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

Advanced Linux Install Method

Installing LDAP support for Guacamole

Keeper Connection Manager packages Guacamole’s LDAP support within the kcm-guacamole-auth-ldap package:

$ sudo yum install kcm-guacamole-auth-ldap

Unlike the MySQL, PostgreSQL, SQL Server and authentication backends, Guacamole’s LDAP support does not require a schema to be applied unless you intend to store connection data within your LDAP directory. If LDAP will be used only to authenticate Guacamole users, no schema modifications need be made, and a database should be used to store connection data.

If you do intend to store connection data within your LDAP directory, you will need to apply the provided schema modifications which create the guacConfigGroup object class. Be sure to first finish configuring Guacamole for LDAP authentication, and verify that Guacamole can successfully authenticate users against your LDAP directory.

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the LDAP directory:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “LDAP-1” and defines the TCP connection information for the LDAP directory. Uncomment the ldap-hostname property, modifying its value to point to your LDAP server:

##
## [LDAP-1] LDAP TCP connection information
##
## The TCP connection details of the LDAP server, as well as whether encryption
## should be used.
##
## Legal encryption methods are "none", for unencrypted connections, "ssl" 
## for LDAP over SSL/TLS (also known as LDAPS), or "starttls" for STARTTLS.
##

#ldap-hostname:          localhost
#ldap-port:              389
#ldap-encryption-method: none

By default, Guacamole will connect to your LDAP server without encryption. If your LDAP server uses encryption, you will need to uncomment and set the ldap-encryption-method property to “ssl” for LDAPS (LDAP over SSL/TLS) or “starttls” for STARTTLS.

The default port varies by encryption method, and will be 389 for unencrypted LDAP and STARTTLS, or 636 for LDAPS. If your LDAP server listens on a non-standard port, you will also need to uncomment and modify the ldap-port property.

Mapping Guacamole usernames to LDAP DN’s

To authenticate users using LDAP, Guacamole must translate usernames into their corresponding LDAP DN’s. Depending on the complexity of your LDAP directory, this can be as simple as adding a single attribute to a common base DN, or can involve an LDAP query.

The “LDAP-2” section defines the basic parameters required for either case:

##
## [LDAP-2] LDAP user / user DN description
##
## The base DN of all Guacamole users within the LDAP directory, and the
## attribute which contains each user's username. If the username attribute
## is not part of the DN, a seach DN will need to be provided, as well.
##

#ldap-user-base-dn:       ou=people,dc=example,dc=net
#ldap-username-attribute: uid

The base DN defined by the ldap-user-base-dn property should be the common base shared by all Guacamole users within your LDAP directory, while the attribute which contains the user’s username is defined by ldap-username-attribute. The base DN is always required if LDAP is being used.

Direct username mapping

By default, Guacamole will attempt to derive the user’s DN directly by prepending the username attribute to the base DN. For example, assume a user is attempting to login with the username “someUser”. If the base DN is “ou=people,dc=example,dc=net” and the username attribute is “uid” (the default), then Guacamole will perform the following steps to authenticate the user:

1. Prepend the username to the base DN using the “uid” attribute, producing the DN: “uid=someUser,ou=people,dc=example,dc=net”.

2. Attempt to bind using the DN “uid=someUser,ou=people,dc=example,dc=net” and the password provided by the user.

3. If the bind attempt succeeds, authentication is successful.

Indirect username mapping

For more complex cases, where the user DN is cannot be directly derived by prepending the username attribute, Guacamole can instead issue an LDAP query to determine the user DN. This requires a search DN and password, defined with the ldap-search-bind-dn and ldap-search-bind-password properties respectively, which Guacamole will bind as when performing the query:

##
## [LDAP-3] LDAP user search DN
##
## The DN and password of the user to bind as when searching for the DN of each
## user attempting to log in. If omitted, the DN of each user will be derived
## directly using the user base DN and username attribute.
##

#ldap-search-bind-dn:       cn=someUser,ou=people,dc=example,dc=net
#ldap-search-bind-password: some_password

With the search DN and password configured, Guacamole will perform the following steps to authenticate a user:

1. Bind to the LDAP directory using the search DN and password.

2. Issue an LDAP query for objects within the subtree of the base DN that contain the user’s username within the defined username attribute.

3. If exactly one such object is found, attempt to bind using the DN of that object and the password provided by the user.

4. If the bind attempt succeeds, authentication is successful.

Mapping Guacamole groups to LDAP DN’s

Access to connections within Guacamole may be dictated through LDAP user groups via either of two mechanisms:

1. Defining connections directly within LDAP using schema modifications and dictating group access using the "seeAlso" attribute.

2. Mapping LDAP groups to Guacamole groups and leveraging a database to dictate access.

As it is usually preferable to avoid modifying the LDAP schema, mapping LDAP groups to Guacamole groups is recommended. Doing this will require defining the base DN under which all relevant LDAP groups may be found and defining the LDAP attribute that should be used by Guacamole to determine the unique name of the group:

##
## [LDAP-5] LDAP group / group DN description
##
## The base DN of all Guacamole groups within the LDAP directory, and the
## attribute which should be used by Guacamole to uniquely identify the
## group.
##
## If connections are being stored within LDAP using "guacConfigGroup" objects,
## and you wish to control access to these connections via LDAP groups, this is
## accomplished using the standard "seeAlso" attribute and the
## ldap-group-base-dn property is required.
##
## If connections are being stored outside of LDAP, such as within a database,
## and you wish to control access using LDAP groups, both ldap-group-base-dn
## and ldap-group-name-attribute will be required. The group membership of a
## user cannot be queried without a base DN, and the unique name to be used by
## other parts of Guacamole to represent the group cannot be determined without
## the name attribute.
##

#ldap-group-base-dn:        ou=groups,dc=example,dc=net
#ldap-group-name-attribute: cn

Completing installation

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

Custom Root Certificate

If you require the use of a custom Root Certificate for your LDAP server, you can volume mount the file /etc/pki/ca-trust/extracted/java/cacerts in your Docker Compose to override this certificate in the guacamole docker container.

• Import the certificate into a Java truststore using "keytool".

• Volume mount the cacerts file to your target guacamole docker container

For Advanced Linux Install method leveraging the RPMs, this would be accomplished through Red Hat's automated certificate import tooling following this guide.

Defining the guacConfigGroup object class

When connection data is stored within your LDAP directory, each connection is represented by a special type of LDAP group, and permissions related to Guacamole connections can be managed directly with LDAP based on user membership of these groups. Doing this requires schema modifications which add a new object class called guacConfigGroup.

An LDIF file defining the schema changes in a manner compatible with OpenLDAP is provided by the kcm-guacamole-auth-ldap package within /opt/keeper/share/guacamole-auth-ldap/schema/guacConfigGroup.ldif. This file can be applied to your OpenLDAP server using the “ldapadd” command:

$ sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f /opt/keeper/share/guacamole-auth-ldap/schema/guacConfigGroup.ldif

Once this is done, connections can be defined by creating new guacConfigGroup objects within the LDAP directory. Each guacConfigGroup accepts a single guacConfigProtocol attribute, defining the protocol associated with the connection, and any number of guacConfigParameter attributes, each defining a connection parameter name/value pair. Users that should have access to the connection must be added as members of the guacConfigGroup using the member attribute.

For example, a connection accessible to two users which uses VNC to connect to localhost at port 5900 with the password “secret” could be defined with the following LDIF file:

dn: cn=Example Connection,ou=groups,dc=example,dc=net
objectClass: guacConfigGroup
objectClass: groupOfNames
cn: Example Connection
guacConfigProtocol: vnc
guacConfigParameter: hostname=localhost
guacConfigParameter: port=5900
guacConfigParameter: password=secret
member: cn=user1,ou=people,dc=example,dc=net
member: cn=user2,ou=people,dc=example,dc=net

Configuring Guacamole to read connections from LDAP

Auto Docker And Docker Compose Install Methods:

To read connection data from LDAP, Guacamole’s main configuration file, modify the /etc/kcm-setup/docker-compose.yml file.

The base DN of all connections defined within LDAP must be specified using the LDAP_CONFIG_BASE_DN property. This base DN should be the DN of the portion of the LDAP directory whose subtree contains all Guacamole connections accessible via LDAP. Only connections defined within the subtree of this base DN will be visible:

   guacamole:
        image: keeper/guacamole:2
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            
            # LDAP Connection
            LDAP_HOSTNAME: "localhost"
            LDAP_PORT: 389
            LDAP_ENCRYPTION_METHOD: "none"
            ADDITIONAL_GUACAMOLE_PROPERTIES: "extension-priority: *, ldap"
            
            ## Optional Settings ##
            # Read Connections from LDAP
            LDAP_CONFIG_BASE_DN: "ou=connections,dc=example,dc=net"

Advanced Linux Install Method:

To read connection data from LDAP, Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to define the subtree containing these connections:

$ sudo vi /etc/guacamole/guacamole.properties

The base DN of all connections defined within LDAP must be specified using the ldap-config-base-dn property. This base DN should be the DN of the portion of the LDAP directory whose subtree contains all Guacamole connections accessible via LDAP. Only connections defined within the subtree of this base DN will be visible:

##
## [LDAP-4] LDAP base DN for Guacamole connections ("guacConfigGroup")
##
## The base DN for all Guacamole connections defined directly within the LDAP
## directory using "guacConfigGroup" objects. If connections will not be stored
## within the directory, this property is unnecessary.
##
## If the kcm-guacamole-auth-ldap package has been installed, the LDAP
## schema for "guacConfigGroup" objects can be found at:
##
##   /usr/share/guacamole-auth-ldap/schema/guacConfigGroup.ldif
##
## Alternatively, if your LDAP directory does not accept LDIF files, the schema
## source for "guacConfigGroup" can be found at:
##
##   /usr/share/guacamole-auth-ldap/schema/guacConfigGroup.schema
##

#ldap-config-base-dn: ou=connections,dc=example,dc=net

Controlling access using group membership

Auto Docker and Docker Compose Install Method

To control group membership using LDAP, modify the /etc/kcm-setup/docker-compose.yml file.

It is also possible grant entire groups access to connections using the seeAlso attribute. This attribute is a standard LDAP attribute, and will be taken into account by Guacamole if the LDAP_GROUP_BASE_DN property is defined. This property defines the root of the subtree containing all groups which may apply to Guacamole users authenticated using LDAP:

  guacamole:
        image: keeper/guacamole:2
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            
            # LDAP Connection
            LDAP_HOSTNAME: "localhost"
            LDAP_PORT: 389
            LDAP_ENCRYPTION_METHOD: "none"
            ADDITIONAL_GUACAMOLE_PROPERTIES: "extension-priority: *, ldap"
            
            ## Optional Settings ##
            # Mapping Guacamole groups to LDAP DN's
            LDAP_GROUP_BASE_DN: "ou=groups,dc=example,dc=net"
            LDAP_GROUP_NAME_ATTRIBUTE: "cn"

Advanced Linux Install Method

It is also possible grant entire groups access to connections using the seeAlso attribute. This attribute is a standard LDAP attribute, and will be taken into account by Guacamole if the ldap-group-base-dn property is defined. This property defines the root of the subtree containing all groups which may apply to Guacamole users authenticated using LDAP:

##
## [LDAP-5] LDAP group / group DN description
##
## The base DN of all Guacamole groups within the LDAP directory, and the
## attribute which should be used by Guacamole to uniquely identify the
## group.
##
## If connections are being stored within LDAP using "guacConfigGroup" objects,
## and you wish to control access to these connections via LDAP groups, this is
## accomplished using the standard "seeAlso" attribute and the
## ldap-group-base-dn property is required.
##
## If connections are being stored outside of LDAP, such as within a database,
## and you wish to control access using LDAP groups, both ldap-group-base-dn
## and ldap-group-name-attribute will be required. The group membership of a
## user cannot be queried without a base DN, and the unique name to be used by
## other parts of Guacamole to represent the group cannot be determined without
## the name attribute.
##

#ldap-group-base-dn:        ou=groups,dc=example,dc=net
#ldap-group-name-attribute: cn

Completing installation

Changes to Guacamole’s LDAP configuration will generally only be reread from guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

Advanced Linux Install Method

$ sudo systemctl restart guacamole

$ sudo systemctl restart tomcat

If multiple authentication methods are installed, Guacamole will poll each method as it attempts to authenticate users, and will retrieve connection data from each method once a user has successfully authenticated. This behavior is designed to allow authentication methods to work together, and can be leveraged to authenticate Guacamole users against LDAP while storing the connection data for those users within MySQL, PostgreSQL, or SQL Server.

Guacamole's definition of identity

When reading data from multiple authentication methods, Guacamole compares the unique identifiers of users (usernames) and groups to determine identity. This means that user accounts from different authentication systems will be automatically combined by Guacamole upon successful authentication as long as those user accounts have the same username, and group memberships will take effect across authentication systems so long as the unique names of those groups match.

If both LDAP and a database authentication method have been configured, Guacamole will automatically attempt to authenticate against both systems whenever a user attempts to log in. The LDAP account will be considered equivalent to the database user if the username is identical, and that user will have access to any data associated with them via the database, as well as any visible objects within the LDAP directory. If that user has permission to query their group memberships within LDAP, and Guacamole has been configured to query groups within LDAP, then the user's group membership will also be retrieved upon authentication, and the user will have access to any data associated with those groups via the database.

Administering LDAP users within Guacamole

Rather than having to manually look up users or groups within the LDAP directory, and then manually create those same users and groups within Guacamole, it is possible to set up administrative user accounts which can already see and manage available LDAP objects. This streamlines the administrative process, reducing the number of users which must be manually created to one.

To see LDAP objects within Guacamole’s administrative interface, one of the following tasks must be performed:

1. An administrative user within the Guacamole database, such as the default “guacadmin” user, must be manually created within LDAP with the same username and with sufficient privileges to query all Guacamole users and groups defined within LDAP.

2. An administrative user must be manually created within Guacamole having the same username as an LDAP user with sufficient privileges to query all Guacamole users and groups defined within LDAP.

Because a Guacamole user created as defined above would have access to LDAP users and groups, database users and groups, and database connections, all of this data will be unified within the same administrative interface within Guacamole. The user will be able to grant LDAP users and groups access to connections within the database to just as they would if only the database were in use.

If your Active Directory or LDAP deployment spans multiple servers, Guacamole can be configured to use each of your LDAP servers using ldap-servers.yml, a configuration file similar to guacamole.properties and located within /etc/guacamole. When a user authenticates with a Guacamole instance configured to use multiple LDAP servers, each configured LDAP server is tried, in order, until authentication succeeds. Authentication fails only if none of the defined LDAP servers accept the user's provided credentials.

When ldap-servers.yml is used, the values within guacamole.properties still have meaning, but instead serve as defaults for the LDAP servers defined in ldap-servers.yml.

Overview of ldap-servers.yml

The ldap-servers.yml file contains a single YAML list of LDAP servers, with each server definition consisting of a simple list of configuration properties and values. These configuration properties are identical to the LDAP properties available within guacamole.properties except that the "ldap-" prefix is omitted.

For example, a simple ldap-servers.yml that defines two LDAP servers that may be used to authenticate users would contain the following:

- hostname: server1.example.net
  user-base-dn: OU=Users,DC=example,DC=net
  username-attribute: sAMAccountName
  search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
  search-bind-password: SomePassword!

- hostname: server2.example.net
  user-base-dn: OU=Users,DC=example,DC=net
  username-attribute: sAMAccountName
  search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
  search-bind-password: SomePassword! 

When a user attempts to log in, Guacamole will attempt to authenticate the user against the first defined LDAP server (server1.example.net). If that fails, Guacamole will proceed with the next (server2.example.net), and so on. Only if authentication fails against all defined LDAP servers will authentication against LDAP fail overall.

Abbreviating common LDAP parameters

Since the only property that varies between the two servers in the above example is the hostname, and since guacamole.properties serves as the source of default values when ldap-servers.yml is used, the configuration details common to all servers would be better specified within guacamole.properties:

ldap-user-base-dn: OU=Users,DC=example,DC=net
ldap-username-attribute: sAMAccountName
ldap-search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
ldap-search-bind-password: SomePassword!

The contents of ldap-servers.yml can then be reduced to only the hostnames:

- hostname: server1.example.net
- hostname: server2.example.net

Splitting users across multiple LDAP servers

LDAP servers listed within ldap-servers.yml may optionally be restricted to only certain users with the "match-usernames" option. This option accepts both a single string and an array of strings, where each string is a Perl-compatible regular expression. Additionally, if the regular expression includes a capturing group, the contents of the first capturing group will be used as the username representing the user's Guacamole identity.

For example, to define two LDAP servers covering distinct domains, splitting usage of those LDAP servers by whether the user enters their username as "DOMAIN1\username" or "DOMAIN2\username", you would edit your ldap-servers.yml to contain something like the following:

- hostname: domain1.example.net
  user-base-dn: OU=Users,DC=domain1,DC=example,DC=net
  match-usernames: DOMAIN1\\(.*)

- hostname: domain2.example.net
  user-base-dn: OU=Users,DC=domain2,DC=example,DC=net
  match-usernames: DOMAIN2\\(.*)

Each of the LDAP servers defined above will only be used if their corresponding regular expression matches the username specified by the user. Since each of the regular expressions in the above example define a capturing group around the username component of the "DOMAIN\username" format, that portion of the provided username will be used to determine the user's identity. If a user successfully authenticates as "DOMAIN1\myusername", then:

• The captured portion ("myusername") will be used to identify the user's corresponding account in Guacamole's database.

• The captured portion ("myusername") will be used when mapping the user to their fully-qualified LDAP DN.

If there are multiple username formats that need to be accepted by each LDAP server, multiple regular expressions may be specified. For example, to match both "MYDOMAIN\myusername" and the UPN-style "myusername@mydomain.example.net" formats, you would specify:

- hostname: domain1.example.net
  user-base-dn: OU=Users,DC=domain1,DC=example,DC=net
  match-usernames:
    - DOMAIN1\\(.*)
    - (.*)@domain1\.example\.net

- hostname: domain2.example.net
  user-base-dn: OU=Users,DC=domain2,DC=example,DC=net
  match-usernames:
    - DOMAIN2\\(.*)
    - (.*)@domain2\.example\.net

Creating and initializing the Guacamole database

If you haven’t already done so, a database specific to Guacamole needs to be created within MySQL. The database can be called anything you like; all that matters is that the database be dedicated to Guacamole, and not shared by different applications. Get to the MySQL prompt with the command:

sudo mysql -u root

Next, create the database:

CREATE DATABASE guacamole_db;

Then exit MySQL with the "exit" command.

Guacamole will not automatically initialize the database with the required schema. You will need to do this yourself using the SQL scripts provided with the kcm-guacamole-auth-jdbc-mysql package, which are located within the /opt/keeper/share/guacamole-auth-jdbc-mysql/schema directory:

The above scripts must be run in sequence, as it is the first script which actually creates the database schema. The second script, which defines a default administrative user, can only successfully run if the tables created by the first script exist. The simplest way to run both scripts in sequence is to concatenate them:

cat /opt/keeper/share/guacamole-auth-jdbc-mysql/schema/*.sql | mysql -u root -p guacamole_db

Alternatively, the scripts can be run individually, as long as the order is correct:

mysql -u root guacamole_db < /opt/keeper/share/guacamole-auth-jdbc-mysql/schema/001-create-schema.sqlmysql -u root guacamole_db < /opt/keeper/share/guacamole-auth-jdbc-mysql/schema/002-create-admin-user.sql

Connecting Guacamole to MySQL

To execute queries against the database, Guacamole will need its own database user with sufficient privileges. Because Guacamole does not automatically apply or update its own schema, the required privileges are minimal, dealing only with creation and maintenance of data within already-defined tables and indexes:

CREATE USER 'guacamole_user' IDENTIFIED BY 'some_password';
GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user';
FLUSH PRIVILEGES;

Advanced Linux Install Method

Keeper Connection Manager packages Guacamole’s MySQL support within the kcm-guacamole-auth-jdbc-mysql package. This package must be installed before creating Guacamole’s database within MySQL, as it includes the SQL scripts necessary for doing so:

sudo yum install kcm-guacamole-auth-jdbc-mysql

Guacamole's main configuration file, /etc/guacamole/guacamole.properties, must now be modified to specify the credntials of the MySQL user and to point the MySQL database:

sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked "JDBC-1" and defines the TCP connection information for the database in use. Uncomment the mysql-hostname and mysql-port properties, modifying their values to point to your MySQL server:

##
## [JDBC-1] Database TCP connection information
##
## The TCP connection details for the PostgreSQL, MySQL / MariaDB, or SQL
## Server database.
##

mysql-hostname: localhost
mysql-port:     3306

The "JDBC-2" section, which defines the database name and associated credentials, must also be modified to specify the correct database name, username, and password. These values are given with the mysql-database, mysql-username, and mysql-password properties respectively:

##
## [JDBC-2] Database name and credentials
##
## The name of the database to use, as well as the credentials to use when
## connecting to the database. THESE PROPERTIES ARE REQUIRED if one of the
## database authentication extensions will be used.
##

mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: some_password

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

$ sudo systemctl restart tomcat

$ sudo setsebool -P tomcat_can_network_connect_db 1

To make sure everything is working as expected, you should also visit your Guacamole instance with a web browser (most likely at http://HOSTNAME:8080/guacamole/, where “HOSTNAME” is the hostname or IP address of your server). If all is working correctly, you should see a login screen with a username/password prompt, and you will be able to log in using the default account created with the 002-create-admin-user.sql script:

CentOS and RHEL both provide a package for the MariaDB database server called "mariadb-server". Installing this package will install a version of MariaDB that is explicitly supported by Keeper Connection Manager. If you do not have an existing database instance or third-party database hosting provider that you would prefer to use, installing a fresh instance of MariaDB for use by Guacamole will work nicely:

$ sudo yum install mariadb-server

As with other standard CentOS / RHEL packages providing a service, the MariaDB service will not be started by default after the "mariadb-server" package is installed. It must be started manually, and then configured to automatically start if the system is rebooted:

$ sudo systemctl start mariadb
$ sudo systemctl enable mariadb

Dropping default anonymous users

If MariaDB is installed locally (on the same server as Apache Guacamole), its default configuration will prevent Guacamole from authenticating. This is due to the way that MariaDB handles authentication and anonymous database users: if an anonymous user is defined for the same hostname/address, MariaDB will use only the anonymous user, and authentication using a non-anonymous user and password from the same hostname/address will fail.

This can be checked by querying MariaDB's user table directly:

SELECT Host, User FROM mysql.user;

Any users with empty usernames in the results of the above query are anonymous users which may block authentication from succeeding:

+---------------------+----------------+
| Host                | User           |
+---------------------+----------------+
| %                   | guacamole_user |
| 127.0.0.1           | root           |
| ::1                 | root           |
| the.server.hostname |                |
| the.server.hostname | root           |
| localhost           |                |
| localhost           | root           |
+---------------------+----------------+

Dropping those users should allow non-anonymous authentication from those same hosts to succeed:

DROP USER ''@'localhost';
DROP USER ''@'the.server.hostname';
FLUSH PRIVILEGES;

Pointing Guacamole at the new MariaDB instance

Once MariaDB has been deployed, you should move forward with configuring Guacamole to use your new MariaDB instance. This process is documented in its entirety, and the default /etc/guacamole/guacamole.properties file also contains placeholders and comments to help guide administrators to the correct configuration properties. Overall, the process will involve:

• Installing the package providing MySQL / MariaDB support (kcm-guacamole-auth-jdbc-mysql).

• Creating a new database within your MariaDB instance using the provided schema files.

• Creating a database user that Guacamole can use to execute queries against your database.

• Editing /etc/guacamole/guacamole.properties to point Guacamole at your database (and to specify the credentials of the database user it should use).

Creating and initializing the Guacamole database

If you haven’t already done so, a database specific to Guacamole needs to be created within PostgreSQL. The database can be called anything you like; all that matters is that the database be dedicated to Guacamole, and not shared by different applications:

CREATE DATABASE guacamole_db;

Guacamole will not automatically initialize the database with the required schema. You will need to do this yourself using the SQL scripts provided with the kcm-guacamole-auth-jdbc-postgresql package, which are located within the /opt/keeper/share/guacamole-auth-jdbc-postgresql/schema directory:

The above scripts must be run in sequence, as it is the first script which actually creates the database schema. The second script, which defines a default administrative user, can only successfully run if the tables created by the first script exist. The simplest way to run both scripts in sequence is to concatenate them:

$ cat /opt/keeper/share/guacamole-auth-jdbc-postgresql/schema/*.sql | psql -d guacamole_db -f -

Alternatively, the scripts can be run individually, as long as the order is correct:

$ psql -d guacamole_db -f /opt/keeper/share/guacamole-auth-jdbc-postgresql/schema/001-create-schema.sql
$ psql -d guacamole_db -f /opt/keeper/share/guacamole-auth-jdbc-postgresql/schema/002-create-admin-user.sql

Connecting Guacamole to PostgreSQL

To execute queries against the database, Guacamole will need its own database user with sufficient privileges. Because Guacamole does not automatically apply or update its own schema, the required privileges are minimal, dealing only with creation and maintenance of data within already-defined tables and indexes:

CREATE USER guacamole_user WITH PASSWORD 'some_password';
GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO guacamole_user;
GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO guacamole_user;

Advanced Linux Install Method

Keeper Connection Manager packages Guacamole’s PostgreSQL support within the kcm-guacamole-auth-jdbc-postgresql package. This package must be installed before creating Guacamole’s database within PostgreSQL, as it includes the SQL scripts necessary for doing so:

$ sudo yum install kcm-guacamole-auth-jdbc-postgresql

Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must now be modified to specify the credentials of the PostgreSQL user and to point the PostgreSQL database:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “JDBC-1” and defines the TCP connection information for the database in use. Uncomment the postgresql-hostname and postgresql-port properties, modifying their values to point to your PostgreSQL server:

##
## [JDBC-1] Database TCP connection information
##
## The TCP connection details for the PostgreSQL, MySQL / MariaDB, or SQL
## Server database.
##

#mysql-hostname: localhost
#mysql-port:     3306

postgresql-hostname: localhost
postgresql-port:     5432

The “JDBC-2” section, which defines the database name and associated credentials, must also be modified to specify the correct database name, username, and password. These values are given with the postgresql-database, postgresql-username, and postgresql-password properties respectively:

##
## [JDBC-2] Database name and credentials
##
## The name of the database to use, as well as the credentials to use when
## connecting to the database. THESE PROPERTIES ARE REQUIRED if one of the
## database authentication extensions will be used.
##

#mysql-database: guacamole_db
#mysql-username: guacamole_user
#mysql-password: some_password

postgresql-database: guacamole_db
postgresql-username: guacamole_user
postgresql-password: some_password

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process.

Advanced Linux Install Method

$ sudo systemctl restart guacamole

$ sudo systemctl restart tomcat

$ sudo setsebool -P tomcat_can_network_connect_db 1

To make sure everything is working as expected, you should also visit your Guacamole instance with a web browser (most likely at http://HOSTNAME:8080/guacamole/, where “HOSTNAME” is the hostname or IP address of your server). If all is working correctly, you should see a login screen with a username/password prompt, and you will be able to log in using the default account created with the 002-create-admin-user.sql script:

CentOS and RHEL both provide a package for the PostgreSQL database server called "postgresql-server". Installing this package will install a version of PostgreSQL that is explicitly supported by Keeper Connection Manager. If you do not have an existing database instance or third-party database hosting provider that you would prefer to use, installing a fresh instance of PostgreSQL for use by Guacamole will work nicely:

$ sudo yum install postgresql-server

As with other standard CentOS / RHEL packages providing a service, the PostgreSQL service will not be started by default after the "postgresql-server" package is installed. However, if you attempt to start the PostgreSQL service now, the service will fail to start as PostgreSQL's database has not yet been created and initialized. This must be done manually with the "postgresql-setup" command:

$ sudo postgresql-setup initdb

Once the database has been initialized, the service can be safely started and configured to start automatically if the system is rebooted:

$ sudo systemctl start postgresql
$ sudo systemctl enable postgresql

Configuring PostgreSQL to accept password authentication locally

If PostgreSQL is installed locally (on the same server as Apache Guacamole), its default configuration will prevent Guacamole from authenticating. This is because PostgreSQL can be configured to use different authentication mechanisms for connections coming from different networks or addresses, and the default configuration uses "ident" authentication for connections from the local machine. The "ident" method is incompatible with providing a database username and password via TCP, which will result in Guacamole being unable to connect to PostgreSQL.

Edit PostgreSQL's main configuration file, /var/lib/pgsql/data/pg_hba.conf, looking for the lines which associate IPv4 or IPv6 loopback addresses with "ident":

host    all     all     127.0.0.1/32    ident
host    all     all     ::1/128         ident

The keyword ident should be changed to md5 to allow username/password authentication for local connections:

host    all     all     127.0.0.1/32    md5
host    all     all     ::1/128         md5

PostgreSQL will then need to be restarted to apply these changes:

$ sudo systemctl restart postgresql

Pointing Guacamole at the new PostgreSQL instance

Once PostgreSQL has been deployed, you should move forward with configuring Guacamole to use your new PostgreSQL instance. This process is documented in its entirety, and the default /etc/guacamole/guacamole.properties file also contains placeholders and comments to help guide administrators to the correct configuration properties. Overall, the process will involve:

• Installing the package providing PostgreSQL support (kcm-guacamole-auth-jdbc-postgresql).

• Creating a new database within your PostgreSQL instance using the provided schema files.

• Creating a database user that Guacamole can use to execute queries against your database.

• Editing /etc/guacamole/guacamole.properties to point Guacamole at your database (and to specify the credentials of the database user it should use).

Creating and initializing the Guacamole database

If you haven’t already done so, a database specific to Guacamole needs to be created within SQL Server. The database can be called anything you like and there are no specific requirements for the size of the database, collation, etc.; all that matters is that the database be dedicated to Guacamole, and not shared by different applications:

SQL Server Management Studio

CREATE DATABASE guacamole_db;
GO

Guacamole will not automatically initialize the database with the required schema. You will need to do this yourself using the SQL scripts provided with the kcm-guacamole-auth-jdbc-sqlserver package, which are located within the /opt/keeper/share/guacamole-auth-jdbc-sqlserver/schema directory:

The above scripts must be run in sequence. The first script, 001-create-schema.sql, creates the database schema:

SQL Server Management Studio

$ sqlcmd -S sqlserver_database_hostname -U sa -d guacamole_db -i /opt/keeper/share/guacamole-auth-jdbc-sqlserver/schema/002-create-admin-user.sql

Creating a Database User for Guacamole

To execute queries against the database, Guacamole will need its own database user with sufficient privileges. Because Guacamole does not automatically apply or update its own schema, the required privileges are minimal, dealing only with creation and maintenance of data within already-defined tables and indexes. Permission to SELECT, INSERT, UPDATE, and DELETE from all tables in the database is sufficient and exactly covered by SQL Server's db_datareader and db_datawriter roles.

The login to be used by Guacamole must use SQL Server authentication, with a password which will eventually be stored within /etc/guacamole/guacamole.properties:

SQL Server Management Studio

CREATE LOGIN guacamole_user WITH PASSWORD = 'some_password';
GO

The login must then be associated with a user specific to the Guacamole database:

SQL Server Management Studio

CREATE USER guacamole_user;
GO

To grant the necessary SELECT, INSERT, UPDATE, and DELETE permissions for all tables in the Guacamole database, the user must be added to the database's db_datareader and db_datawriter roles:

SQL Server Management Studio

ALTER ROLE db_datawriter ADD MEMBER guacamole_user;
ALTER ROLE db_datareader ADD MEMBER guacamole_user;
GO

Connecting Guacamole to SQL Server

Advanced Linux Install Method

Keeper Connection Manager packages Guacamole’s SQL Server support within the kcm-guacamole-auth-jdbc-sqlserver package. This package must be installed before creating Guacamole’s database within SQL Server, as it includes the SQL scripts necessary for doing so:

$ sudo yum install kcm-guacamole-auth-jdbc-sqlserver

Once the database and database user have been prepared, Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to specify the credentials of that user and to point the SQL Server instance and database:

$ sudo vi /etc/guacamole/guacamole.properties

The guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “JDBC-1” and defines the TCP connection information for the database in use. Uncomment the sqlserver-hostname and sqlserver-port properties, modifying their values to point to your instance of SQL Server:

##
## [JDBC-1] Database TCP connection information
##
## The TCP connection details for the PostgreSQL, MySQL / MariaDB, or SQL
## Server database.
##

#mysql-hostname: localhost
#mysql-port:     3306

#postgresql-hostname: localhost
#postgresql-port:     5432

sqlserver-hostname: localhost
sqlserver-port:     1433

The “JDBC-2” section, which defines the database name and associated credentials, must also be modified to specify the correct database name, username, and password. These values are given with the sqlserver-database, sqlserver-username, and sqlserver-password properties respectively:

##
## [JDBC-2] Database name and credentials
##
## The name of the database to use, as well as the credentials to use when
## connecting to the database. THESE PROPERTIES ARE REQUIRED if one of the
## database authentication extensions will be used.
##

#mysql-database: guacamole_db
#mysql-username: guacamole_user
#mysql-password: some_password

#postgresql-database: guacamole_db
#postgresql-username: guacamole_user
#postgresql-password: some_password

sqlserver-database: guacamole_db
sqlserver-username: guacamole_user
sqlserver-password: some_password

Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:

$ sudo systemctl restart guacamole

$ sudo systemctl restart tomcat

$ sudo setsebool -P tomcat_can_network_connect_db 1

To make sure everything is working as expected, you should also visit your Keeper Connection Manager instance with a web browser (most likely at http://HOSTNAME:8080/guacamole/, where “HOSTNAME” is the hostname or IP address of your server). If all is working correctly, you should see a login screen with a username/password prompt, and you will be able to log in using the default account created with the 002-create-admin-user.sql script: