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:
Provide alternative authentication methods and sources of connection/user data.
Provide event listeners that will be notified as Guacamole performs tasks such as authentication and tunnel connection.
Theme or brand the user interface through additional CSS files and static resources.
Extend KCM's JavaScript code by providing JavaScript that will be loaded automatically.
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:
(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.
(3) Copy the file into the /etc/kcm-setup folder or any path on the server.
(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:
(5) Restart the container
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.
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:
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:
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:
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.
Last updated
