Keeper Connection Manager provides support for OpenID Connect for authentication.

Docker Environmental Variables

The image keeper/guacamole can be modified to support OpenID using environmental variables. See the OPENID_* variables defined in the documentation.

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

Authentication Methods

• SAML 2.0

• OpenID Connect

• LDAP

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.

• TOTP

• Duo

KCM allows authentication with the web application using the DoD's Common Access Cards (CAC), as well as with any smart card supported by the browser for SSL client auth such as Personal Identity Verification (PIV).

This support depends on an SSL termination instance providing SSL/TLS authentication, a capability that was added to KCM version 2.12.0.

A typical configuration for PIV/CAC would be the following:

1. An SSL termination instance configured with two hostnames: one for normal access (such as kcm.example.net) and another just for handling SSL client auth, which should ideally be a wildcard domain (such as *.login.kcm.example.net). The SSL client auth configuration would include the certificate of the CA providing the PIV/CAC cards.

2. PIV/CAC support installed and configured to authenticate users against *.login.kcm.example.net and redirect them back to kcm.example.net once ready.

3. Database backend configured to automatically create user accounts for users coming from SSO.

4. User creation workflow configured to require approval for users that SSO from PIV/CAC.

Configuration Options for PIV/CAC

Support for PIV/CAC is configured using Keeper's new support for SSL/TLS client authentication. This support is provided by the “guacamole-auth-sso-ssl” extension, which we package as kcm-guacamole-auth-sso-ssl. Setting any SSL_* variable will implicitly include the kcm-guacamole-auth-sso-ssl package.

The following options will need to be set in the keeper/guacamole Docker container definition (or in guacamole.properties for linux distributions):

The following options are also available, though it would be unusual to need to set them:

SSL (NGINX) Configuration Options for PIV/CAC

Authenticating with PIV/CAC (or any smart card) via the browser is using SSL/TLS client authentication. This capability was further enhanced for PIV/CAC by adding convenient configuration options for testing whether certificates have been revoked via OCSP or a CRL. For reference, the following are all options related to SSL/TLS client authentication currently supported by the keeper/guacamole-ssl-nginx Docker image:

Example PIV/CAC Configuration

The example docker-compose.yml below uses the following placeholders:

In practice, these values will vary, as will whether the user chooses to use MySQL or PostgreSQL. The example below was written using PostgreSQL.

version: "3"
services:

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            POSTGRES_HOSTNAME: "db"
            POSTGRES_DATABASE: "guacamole_db"
            POSTGRES_USERNAME: "guacamole_user"
            POSTGRES_PASSWORD: "PasswordForGuacamole"
            SSL_PRIMARY_URI: "https://kcm.example.net"
            SSL_CLIENT_AUTH_URI: "https://*.kcm.example.net"
            SSL_SUBJECT_BASE_DN: "ou=test department,o=u.s. government,c=us"
            POSTGRESQL_AUTO_CREATE_ACCOUNTS: "true"
            REQUIRE_ACCOUNT_APPROVAL: "ssl"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    db:
        image: keeper/guacamole-db-postgres:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_DATABASE: "guacamole_db"
            GUACAMOLE_USERNAME: "guacamole_user"
            GUACAMOLE_PASSWORD: "PasswordForGuacamole"
            GUACAMOLE_ADMIN_PASSWORD: "guacadmin"
            POSTGRES_PASSWORD: "PasswordForPostgresAdmin"

    guacd:
        image: keeper/guacd:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        volumes:
            - "/path/to/pki:/pki:ro"
        environment:

            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"

            SERVERS: |

              # Main hostname, referenced by SSL_PRIMARY_URI
              - SSL_HOSTNAME: "kcm.example.net"
                CERTIFICATE_FILE: "/pki/kcm.example.net.crt"
                PRIVATE_KEY_FILE: "/pki/kcm.example.net.key"

                # The default CSP must be overridden for the main URI to allow
                # it to issue requests to its SSL/TLS-authenticating
                # counterpart. The only change from the default CSP here is to
                # add an the wildcard URI (including https://) to connect-src.
                CONTENT_SECURITY_POLICY: "default-src 'none'; script-src 'self' 'unsafe-eval'; connect-src 'self' wss://kcm.example.net https://*.kcm.example.net; object-src 'self'; frame-src 'self' https:; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; font-src 'self' data:; form-action 'self'; base-uri 'self'; frame-ancestors 'self';"

              # Hostname requiring client auth, referenced by SSL_CLIENT_AUTH_URI
              - SSL_HOSTNAME: "*.kcm.example.net"
                CERTIFICATE_FILE: "/pki/_.kcm.example.net.crt"
                PRIVATE_KEY_FILE: "/pki/_.kcm.example.net.key"
                CLIENT_CERTIFICATE_FILE: "/pki/cac-certificate.pem"
                SSL_VERIFY_CLIENT: "optional" # This is necessary to allow the webapp to receive
                                              # verification failures. Without this, Nginx would
                                              # respond directly to any verification failures and
                                              # will not include the CORS headers necessary to
                                              # allow the webapp to actually see that failure. This
                                              # also allows the webapp to see the nature of the
                                              # failure by investigating the headers Nginx sends.
                                              # There are no such headers (and no such request) if
                                              # this is set to "required" and Nginx aborts
                                              # processing due to an invalid certificate.

volumes:
    common-storage:

Configuring the KCM user creation workflow

Prior to configuring the user workflow, make sure to set the REQUIRE_ACCOUNT_APPROVAL key to the appropriate authentication method.

For PIV/CAC, you would set it to ssl:

 guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            SSL_PRIMARY_URI: "https://kcm.example.net"
            SSL_CLIENT_AUTH_URI: "https://*.kcm.example.net"
            SSL_SUBJECT_BASE_DN: "ou=test department,o=u.s. government,c=us"
            POSTGRESQL_AUTO_CREATE_ACCOUNTS: "true"
            REQUIRE_ACCOUNT_APPROVAL: "ssl"

Once you have successfully configured, there will be a new "Use Certificate or Smart Card" link on the login screen of the application as seen below:

For additional details on user creation workflow, visit this page.

Installing CA Authority

For each end-user client device that will need access to Keeper Connection Manager, you may need to install the internal CA as a trusted authority into the user's browser. The installation of CA trusted authority varies by platform.

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. If unsure, choose all groups.

If you would like to automatically mapp 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.

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

(8) Copy the URL of the App Federation Metadata and paste it into the prompt on your KCM server.

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

Keeper Connection Manager can be configured to require SSL/TLS client authentication.

Client Certificate Overview

To implement device-based access security with Keeper Connection Manager, this can be accomplished using NGINX client certificates. A client certificate is installed into the web browser of your user's approved devices, and the server will only accept communication from a device with the client certificate installed.

The steps to activate this advanced level of protection is described in the steps below.

(1) Create a Certificate Authority (CA) Key

Generate a CA Key with a strong auto-generated passphrase. Make sure to store the passphrase in your Keeper vault.

openssl genrsa -des3 -out ca.key 4096

(2) Create a CA Certificate

A certificate is created with the CA Key. When answering the questions, you can leave the Common Name and Email empty. Save the information that you entered for Country, State, Locality, and Organization, because you may need these later when renewing the certificate.

openssl req -new -x509 -days 365 -key ca.key -out ca.crt

Side Note: to analyze the certificate parameters, you can run the below command.

openssl x509 -in ca.crt -noout -text

(3) Create a Client Key

For the end-user devices, a client key must be generated. You can decide if you would like to generate one key for all devices, or each user can generate their own key and request a certificate. The process is up to you. Generate a client key with a strong auto-generated passphrase. Make sure to store the passphrase in your Keeper vault.

openssl genrsa -des3 -out client.key 4096

(4) Create a CSR

For each Client Key, generate a CSR to create a signed certificate.

openssl req -new -key client.key -out client.csr

(5) Sign the CSR with the CA Key

openssl x509 -req -days 365 -in client.csr \
 -CA ca.crt -CAkey ca.key \
 -set_serial 01 -out client.crt

You'll need to enter the CA passphrase from Step 1 to sign the request.

At this point, you now have a signed Client Certificate (client.crt).

(6) Convert the Client Certificate to PKCS#12

To import the certificate into a web browser, a pfx file in PKCS#12 is typically required. Generate the client.pfx file using the command below. A passphrase will be required. This passphrase will be provided to each of the users who need to install the certificate, so it should be used specifically for this purpose.

openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.pfx

(7) Add to NGINX Config

The keeper/guacamole-ssl-nginx image can be configured to require SSL/TLS client authentication by specifying the CLIENT_CERTIFICATE_FILE environment variable. A user will only be able to connect to the KCM instance of NGINX using their browser if their browser has access to a private key that is signed by this certificate.

This variable is similar to the CERTIFICATE_FILE environment variable in that it points to a file within the container, but in this case it controls the certificate used to authenticate the client’s private key.

Example:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            CLIENT_CERTIFICATE_FILE: "/path/in/container/ca.crt"
        volumes:
            - "/local/path/to/keys:/path/in/container/"

After updating the configuration, restart the containers.

(8) Test the configuration

Before installing the client certificate on the user's machine, load up the Keeper Connection Manager login screen to ensure that a 403 error is sent:

(9) Install the Client Certificate

For each end-user client device that will need access to Keeper Connection Manager, you will need to install the client certificate into the user's browser or machine. The installation of client certificates varies by platform.

On Windows

Double-click or right-click the client certificate (client.pfx) from Step 6 and enter the client certificate passphrase.

Restart the browser.

The next time Keeper Connection Manager is loaded, you can approve the certificate.

On Mac OS - Chrome

Import the client.pfx file by double-clicking or loading into the Keychain login Certificates section. In the "Trust" section of the certificate, mark as Always Trust.

Restart the browser and load the Keeper Connection Manager login screen to select the certificate.

On Mac OS - Firefox

Open Firefox > Preferences > search for Certificates and select Your Certificates tab. Click "Import" and select the client.pfx certificate file. Complete the import.

After successful import, the Keeper Connection Manager login screen will load.

Optional Parameters

Additional environment variables are also available to modify SSL/TLS auth behavior further:

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. Transfer this metadata.xml file to your KCM server machine.

OneLogin Configuration

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

You must have OneLogin developer account.

Configure OneLogin

1. Log in to the OneLogin Dashboard, and click Administration. Then Applications > Add App.

2. Search for SAML, and select SAML Test Connector (IdP).

3. When prompted, change the Display Name of your app. Enter an application name and description. You can also upload a Keeper Connection Manager logo. Click save.

4. Go to the Configuration tab, Update 3 fields: Recipient, ACS (Consumer) URL Validator, and ACS (Consumer) URL with your KCM server URL and /api/ext/saml/callback on the end as shown below.

1. Click on the More Actions dropped-down menu. Select SAML Metadata to download and save the .XML file.

2. Under the Users tab on the top, find the users that need to log in using SSO, click into them and on the applications tab on the left, add the new SAML application to them.

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

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.

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 login page as shown below.

Auto Docker Install Method

Run the reconfigure command listed below and press enter to accept all the pre-populated selections until you get to the SAML prompt.

sudo ./kcm-setup.run reconfigure

Retreive your IdP Metadata

Instructions for setting up your identity provider and retrieving the XML metadata are found in the guides blow. Any SAML 2.0 identity provider is compatible.

Complete the Prompts

• Enter your SAML IdP URL.

• When asked about signed requests, if unsure, select no.

• Enter your SAML entity ID, and then the group attribute (this must match to your IdP's group attribute).

• Next, you're asked if you want SAML as the default login process. If you want SAML login to be an option (link) on the login page, select no. If you want SAML as the only possible method of authentication, select yes.

• Answer yes when asked if you want user accounts created automatically. If you select no, you'll need to create each account manually within KCM.

SSO Configuration is complete!

Docker Compose Install Method

If you installed Keeper Connection Manager using the Docker Compose Install method, this does not come preconfigured with SAML support. The instructions for activating SAML are below:

(1) On the local instance, stop the containers.

cd /path/to/docker-compose.yml
docker-compose stop

(2) Edit the docker-compose file

Using the custom docker method requires modification of docker-compose.yml file to add SAML support. As root, edit your docker-compose.yml file and find the "guacamole" section.

Create a volume mount for sharing the metadata.xml file with the container. If you already have a shared volume for this purpose, you can use that one. There is also another section needed which needs SAML environmental variables. A sample file is listed below.

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxxx"
            SAML_CALLBACK_URL: "https://demo.lurey.com"
            SAML_IDP_METADATA_URL: "file:///etc/guacamole/metadata.xml"
            SAML_ENTITY_ID: "https://demo.lurey.com"
            SAML_GROUP_ATTRIBUTE: "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
            ADDITIONAL_GUACAMOLE_PROPERTIES: "extension-priority: *, saml"
     volumes:
            - common-storage:/var/lib/guacamole
            - "/etc/kcm-setup/metadata.xml:/etc/guacamole/metadata.xml:ro"

Notes:

• Replace "/var/lib/guac_home" with the local path to your volume

• Replace "https://demo.lurey.com" in 2 spots with your Keeper Connection Manager login URL

• Only use this SAML group attribute if you're using Azure. Other identity providers will use a different Group attribute ID.

• If you want ALL users to login with SAML, then remove the ADDITIONAL_GUACAMOLE_PROPERTIES line. As written, it will give users the choice of password or SAML login.

(3) Create the local folder volume if it doesn't exist yet

(4) Copy the metadata.xml file from your local computer (downloaded from step 8 above) into the location of the volume mount referenced in the guacamole section of the docker-compose file.

(5) Restart the containers

sudo su
docker-compose up -d

Configuration is complete.

Complete

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:

Go to your Oracle Admin Console and navigate to the Identity Domains Overview page, then select Applications as depicted above.

Click on Add Application.

Select SAML as the application type.

Apply the appropriate settings to the Application Information as needed for your security posture. Click on Edit SSO Configuration. Download the Metadata and rename the file to metadata.xml. Set the Entity ID to the URL of your Connection Manager server. For example: https://kcm.somedomain.com. For the Assertion Consumer URL, add /api/ext/saml/callback to the end of the domain URL. For example: https://kcm.somedomain.com/api/ext/saml/callback. Next, set the Name ID Format to Email Address and the Name ID Value to Primary Email. Leave the Signed SSO setting as Assertion. Uncheck the box to Include Signing Certificate in Signature, and leave the Signature Hashing Algorithm as SHA-256.

Assign attributes for email as listed above mapped to the value User Name. Add another attribute for groups with the settings of Type Value Group Membership and a Condition of All groups.

Assign users and groups as appropriate to your SAML application. You'll need to assign at least one user for testing purposes.

Connection Manager Server Configuration

Upload the metadata.xml file to your KCM server and move it into the directory /etc/kcm-setup.

Run the reconfigure command after production hours on your Connection Manager server.

Say Y to the option when presented to setup SAML support.

Select 1 for Local Metadata file. Then input the path of your metadata file as /etc/kcm-setup/metadata.xml and press enter. Answer N to Does your SAML IDP require signed requests? Input your SAML entity ID as the URL of your Connection Manager instance. For example: https://kcm.somedomain.com. Then enter groups as the SAML group attribute.

Choose which setting best applies to your security posture with regard to the default authentication method. If you want Just-In-Time provisioning of users, then answer Y to Would you like user accounts to be automatically created for each successful login?

Click the SAML link to authenticate to the main sign on page.

Your user email address should display in the top right corner after authenticating.

PingIdentity Configuration

1. Login as an Administrator for PingIdentity. From the PingIdentity menu, click Applications > Add Application

2. Give the Application a name such as "KCM," select SAML and Save.

1. Next, you'll encounter the SAML configuration. Select Manually Enter, then add the URL of your KCM server to the ACS URLs box as follows: https://<YOUR DOMAIN>/api/ext/saml/callback

2. Then add the URL of your KCM server to the Entity ID box as follows: https://<YOUR DOMAIN> and press Save.

1. Next, Edit Attribute Mappings. Since saml_subject is immutable, leave it as is. Add an attribute named EMAIL that has a Mapping of Username, and an attribute named groups that has a Mapping of Group Names.

1. Then Edit Configuration and scroll down to SUBJECT NAMEID FORMAT and select the option urn:oasis:names:to:SAML:1.1:nameid-format:emailAddress. And hit Save.

1. On the Overview section, verify that Access is for All Users (or the group you specified). Leave the Signon URL as the Default Signon Page. And Enable the Application by clicking the slider at the top of the application.

1. Download the Metadata file from the Configuration tab, and ensure that it is named to metadata.xml.

1. Ensure that all users are added with a Username that matches the email address of a user in your Keeper Connection Manager. **When you add users to Keeper Connection Manager use the matching email address, but leave the password blank.

Video Example

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 set up Duo, see the DUO_* configuration parameters in the keeper/guacamole Docker image.

Docker Environment Variables

The image keeper/guacamole can be modified to support Duo using environment variables. See the DUO_* variables defined in the .

Generating the random 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:

Auto Docker or Docker Compose

When using the docker version of KCM, you can list the multiple LDAP servers in your docker-compose.yml file using the environment variable LDAP_SERVERS in the environment section of the guacamole service, as shown below:

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.

Docker Environmental Variables

To enable TOTP add the following lines to the "environment" section of the "guacamole" service in the docker-compose.yml file. Only the EXTENSIONS: totp line is required, the rest are optional.

For example:

TOTP with SAML / OIDC

Keeper Connection Manager supports the use of 2FA with TOTP in addition to supporting SAML or OIDC authentication. If TOTP is configured along with SAML, the user will be prompted for 2FA after successfully authenticating with the identity provider.

Multiple Hostnames/Configurations for SSL Termination

The keeper/guacamole-ssl-nginx image is specifically intended to provide SSL termination for the Guacamole image provided by Keeper for KCM. Historically, this image supported only a single hostname and configuration:

As of KCM 2.12.0, the keeper/guacamole-ssl-nginx image can be used with multiple hostnames and configurations via a special SERVERS environment variable that accepts YAML (or JSON).

The SERVERS variable must contain a YAML (or JSON) array of objects, where each object contains the name/value pairs of environment variables that should apply to that additional configuration. Any variable that is not specified is inherited from the top-level environment. For example:

The above configuration would result in an NGINX instance that handles both example.net and *.example.net hostnames equivalently. Both will get their own self-signed certificates because SELF_SIGNED is set to Y.

A more complex example:

The above configuration would result in an NGINX instance that generates and uses a self-signed certificate for *.example.net, but obtains a certificate for example.net from Let’s Encrypt.

IMPORTANT: The value of SERVERS must be a string, hence the | symbol within the above examples. If this symbol is omitted, then the YAML that follows is parsed as an object, and validation of the docker-compose.yml will fail, as all Docker environment variables must be strings.

NOTE: NGINX will use the first server as the default for any request that does not match any configured hostname. If any server declared in SERVERS should have this behavior, it must be the first server listed.

Keeper Connection Manager provides support for LDAP authentication.

Docker Environmental Variables

The image keeper/guacamole can be modified to support LDAP using environmental variables. See the LDAP_* variables defined in the .

Auto Docker and Docker Compose Install Method

If you installed Keeper Connection Manager using the Docker Install method, this does not come preconfigured with LDAP support. The instructions for activating LDAP are below:

(1) On the local instance, stop the containers.

Auto Docker Install:

Docker Compose Install:

(2) Edit the docker-compose file

Using the simple or custom docker method requires modification of docker-compose.yml file to add LDAP support. As root, edit your docker-compose.yml file and find the "guacamole" section.

Optional settings

(3) Restart the containers

Simple Install:

The containers should restart after the upgrade. If not run:

Custom Install:

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

In an environment where KCM users may be automatically created from an SSO system, such as SAML or OpenID or PIV/CAC, administrators may wish to more tightly control whether those users are allows to use KCM. To facilitate this, KCM provides administrators an approve/deny workflow to decide whether an individual user should be allowed to authenticate with KCM using that SSO method.

Configuring the KCM user creation workflow

To require approval for users signing in with a particular authentication method, use the require-account-approval property (or, for Docker, the REQUIRE_ACCOUNT_APPROVAL environment variable). This property accepts a comma-separated list of the names of all authentication methods that should require administrator approval. KCM supports the following authentication types:

For example, to require administrator approval for SAML and LDAP, you would specify:

The following examples shows a docker.yaml file with the SAML Authentication method enabled:

Once you have successfully configured and setup the authentication method, the corresponding SSO login method will be displayed on the logic screen of the application. In the following image, the instance has been configured to use the saml authentication method:

Users with at least one authentication method that needs to be approved or denied will be shown in the user list with a “Pending Login Request” badge next to their username:

Administrators can approve/deny access for that user via that authentication method by editing the user account in KCM:

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.

The EXTENSION_PRIORITY property specifies the order that extensions should be loaded relative to each other. In the following example, all other extensions take priority over 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"
            
            ## Optional Settings ##
            # Read Connections from LDAP
            LDAP_CONFIG_BASE_DN: "ou=connections,dc=example,dc=net"
            # Force all other extensions to take priority over LDAP
            EXTENSION_PRIORITY: "*, ldap" 

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"
            
            ## Optional Settings ##
            # Mapping Guacamole groups to LDAP DN's
            LDAP_GROUP_BASE_DN: "ou=groups,dc=example,dc=net"
            LDAP_GROUP_NAME_ATTRIBUTE: "cn"

Completing installation

Auto Docker Install Method

sudo ./kcm-setup.run stop
sudo ./kcm-setup.run upgrade

Docker Compose Install Method

docker-compose stop
docker-compose up -d

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.