Custom Branding

Customization of the Keeper Connection Manager user interface

Keeper Connection Manager supports customization of the front-end user interface CSS and injection of custom Javascript. In this guide, we will demonstrate how to modify the web application to display customized branding and execute custom Javascript code.

Overview

Keeper Connection Manager provides the ability to develop "Extensions" which can add custom enhancements to the overall platform. This page covers a basic example which can be easily modified for branding and UI changes.

Extensions to Keeper Connection Manager can:

  1. Provide alternative authentication methods and sources of connection/user data.

  2. Provide event listeners that will be notified as Guacamole performs tasks such as authentication and tunnel connection.

  3. Theme or brand the user interface through additional CSS files and static resources.

  4. Extend KCM's JavaScript code by providing JavaScript that will be loaded automatically.

  5. Add additional display languages, or alter the translation strings of existing languages.

Extension format

KCM extensions are standard Java .jar files (this is essentially a .zip file) which contain all classes and resources required by the extension, as well as the KCM extension manifest. There is no set structure to an extension except that the manifest must be in the root of the archive. Java classes and packages, if any, will be read from the .jar relative to the root, as well.

Example Branding Extension

Modifying your existing KCM installation with custom branding is easy, please follow the below steps as an example.

(1) On the instance running Keeper Connection Manager or your workstation, retrieve the example repository or download as a zip file. Example:

git clone https://github.com/Keeper-Security/kcm-branding.git
cd kcm-branding

(2) Zip up the contents of the branding folder into a file called kcm-branding.jar. The name of the file is arbitrary, as long as it is a unique name. KCM will load any extension that is placed into the target folder.

zip -r kcm-branding.jar guac-manifest.json css/ html/ js/ resources/ translations/

(3) Copy the file into the /etc/kcm-setup folder or any path on the server.

sudo cp kcm-branding.jar /etc/kcm-setup/

(4) In your docker-compose.yml file (e.g. /etc/kcm-setup/docker-compose.yml) there are 2 changes needed:

  • In the "guacamole" section add a reference to the Jar file which volume mounts the file directly from the host into the guacamole instance. The name of the file does not matter, as KCM will pull all jar files and process them.

  • Add the environment variable USE_DEFAULT_BRANDING with a value of "N".

Here's an example section:

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ...
            USE_DEFAULT_BRANDING: "N"
        volumes:
            ...
            - "/etc/kcm-setup/kcm-branding.jar:/etc/guacamole/extensions/kcm-branding.jar:ro"

(5) Restart the container

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

That's it. After the service starts up, the branding on your KCM page will be all new, and there will be a popup alert when you load the page.

Example Javascript
Example HTML/CSS modification

For iterating on more changes, simply edit the resources, zip up the file, copy the zip file to the target folder and restart your KCM container.

Technical Details

CSS

The CSS files referenced in guac-manifest.json are appended to the application CSS when loaded, therefore they will override the CSS properties.

Javascript

The Javascript files referenced in guac-manifest.json are appended to the application Javascript when loaded.

HTML modification

The existing HTML structure of KCM's interface can be modified through special "patch" HTML files declared by the html property in guac-manifest.json. These files are HTML fragments and are identical to any other HTML file except that they contain KCM-specific meta tags that instruct KCM to modify its own HTML in a particular way. Each meta tag takes the following form:

<meta name="NAME" content="SELECTOR">

where SELECTOR is a CSS selector that matches the elements within the KCM interface that serve as a basis for the modification, and NAME is any one of the following defined modifications:

before

Inserts the specified HTML immediately before any element matching the CSS selector.

after

Inserts the specified HTML immediately after any element matching the CSS selector.

replace

Replaces any element matching the CSS selector with the specified HTML.

before-children

Inserts the specified HTML immediately before the first child (if any) of any element matching the CSS selector. If a matching element has no children, the HTML simply becomes the entire contents of the matching element.

after-children

Inserts the specified HTML immediately after the last child (if any) of any element matching the CSS selector. If a matching element has no children, the HTML simply becomes the entire contents of the matching element.

replace-children

Replaces the entire contents of any element matching the CSS selector with the specified HTML.

For example, to add a welcome message and link to some corporate privacy policy (a fairly common need), you would add an HTML file like the following:

<meta name="after" content=".login-ui .login-dialog">

<div class="welcome">
    <h2>Welcome to our Keeper Connection Manager Demo</h2>
    <p>
        Please be sure to read our <a href="#">privacy
        policy</a> before continuing.
    </p>
</div>

After the extension is installed and KCM is restarted, the "welcome" div and its contents will automatically be inserted directly below the login dialog (the only element that would match .login-ui .login-dialog) as if they were part of KCM's HTML in the first place.

Troubleshooting

If the page loads blank after applying the extension, check the logs. For example:

sudo ./kcm-setup.run logs -f guacamole

If you see a null pointer exception, it's probably because one of the resources referenced in guac-manifest.json cannot be found in the .jar archive. Ensure that all files and folders are zipped up properly.

PreviousDynamic ConnectionsNextAdd Your Logo

Last updated

Was this helpful?