Customization of the Keeper Connection Manager user interface
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.
- 5.Add additional display languages, or alter the translation strings of existing languages.
KCM extensions are standard Java
.jarfiles (this is essentially a
.zipfile) 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
.jarrelative to the root, as well.
Modifying your existing KCM installation with custom branding is easy, please follow the below steps as an example.
git clone https://github.com/Keeper-Security/kcm-branding.git
(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
/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
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 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.
The CSS files referenced in guac-manifest.json are appended to the application CSS when loaded, therefore they will override the CSS properties.
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">
SELECTORis a CSS selector that matches the elements within the KCM interface that serve as a basis for the modification, and
NAMEis any one of the following defined modifications:
Inserts the specified HTML immediately before any element matching the CSS selector.
Inserts the specified HTML immediately after any element matching the CSS selector.
Replaces any element matching the CSS selector with the specified HTML.
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.
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.
Replaces the entire contents of any element matching the CSS selector with the specified HTML.
<meta name="after" content=".login-ui .login-dialog">
<h2>Welcome to our Keeper Connection Manager Demo</h2>
Please be sure to read our <a href="#">privacy
policy</a> before continuing.
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.
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.jsoncannot be found in the
.jararchive. Ensure that all files and folders are zipped up properly.