Guacamole-Custom-Login

A modern Apache Guacamole branding extension that replaces the default login screen with a clean dark-theme UI. Supports local username/password authentication, OIDC/SSO (via guacamole-auth-sso), or both simultaneously — fully configurable without recompiling Java.

Built on top of the original branding concept from Zer0CoolX/guacamole-customize-loginscreen-extension, rewritten from scratch for Guacamole 1.5+/1.6+.

---

Features

• Modern dark UI — centered card layout, CSS custom properties for easy retheming
• Local auth (username + password) — show or hide independently
• OIDC / SSO (via guacamole-auth-sso) — button is automatically detected, moved into the card, and centered; configurable label
• Custom logo — drop in any PNG
• Custom title — overrides the AngularJS-rendered app name and browser tab title
• Optional subtitle — secondary line beneath the title
• "or" divider — injected automatically when both auth methods are active

---

Repository structure

Guacamole-Custom-Login/
├── src/                          # Editable source files
│   ├── guac-manifest.json        # Extension manifest (namespace, file refs)
│   ├── css/
│   │   └── modern-login.css      # Full UI override
│   ├── js/
│   │   ├── login-config.js       # ← edit this to configure the extension
│   │   └── modern-login.js       # DOM enhancer (runs in the browser)
│   ├── images/
│   │   └── logo.png              # Replace with your own logo (PNG)
│   └── translations/
│       └── en.json               # APP.NAME fallback (used before JS runs)
├── extensions/                   # Mount this into the container
│   └── branding.jar              # Pre-built; regenerated by build.py
├── build.py                      # Packages src/ → branding.jar

---

Quick start

If you don't care about providing a custom logo or hiding buttons individually, you can just use the pre-built branding.jar.

Otherwise, keep on reading.

1. Configure

Open src/js/login-config.js and set your values:

window.guacBrandingConfig = {

    // Show username/password form (set false for SSO-only)
    showLocalAuth: true,

    // Show SSO button (requires guacamole-auth-sso-*.jar in extensions/)
    showOidcAuth: true,

    // Label on the SSO button (null = keep the extension's default text)
    oidcButtonText: "Sign in with SSO",

    // Title shown below the logo (also sets the browser tab title)
    appTitle: "Remote Access Portal",

    // Optional subtitle line (null to hide)
    appSubtitle: null,
};

2. Replace the logo (optional)

Replace src/images/logo.png with your own PNG. Any size works; the CSS constrains it to 60 × 60 px.

3. Build

python3 build.py

The script packages src/ into branding.jar and prints a summary. No Java or Maven required.

4. Deploy

1. Copy the freshly built jar into Guacamole's extensions dir.
2. Restart Guacamole

Tip

If you are operating Guacamole as Docker container, please read the following on how to install custom extensions:

https://github.com/Haxxnet/Compose-Examples/tree/main/examples/guacamole#custom-extensions

---

Retheming

All colours are CSS custom properties defined at the top of src/css/modern-login.css. Edit the :root block and rebuild:

:root {
    --gb-bg:       #0d1117;   /* page background */
    --gb-card:     #161b22;   /* login card */
    --gb-accent:   #2563eb;   /* primary button + focus rings */
    --gb-text:     #e6edf3;   /* primary text */
    /* ... */
}

---

Auth mode reference

showLocalAuth	showOidcAuth	Result
true	false	Username/password only
false	true	SSO button only
true	true	Both, with an "or" divider
false	false	Empty card (don't do this)

---

How it works

Guacamole extensions are JAR files (ZIP archives) containing CSS, JavaScript, images, and a guac-manifest.json that tells Guacamole how to load them. This extension injects CSS and two JS files that run inside the browser:

• login-config.js — exposes a plain window.guacBrandingConfig object (loaded first, no dependencies).
• modern-login.js — uses a MutationObserver to wait for AngularJS to render the login form, then applies all visibility rules, moves the .sso-providers element into the card, inserts the divider, and overwrites the title text.

No Java compilation is needed. Editing src/ and running python3 build.py is all it takes to produce a new branding.jar.

---

Requirements

Component	Version
Apache Guacamole	1.5 or later
guacamole-auth-sso	Same version as Guacamole (OIDC only)
Python	3.6+ (build script only)
Docker + Compose	Any recent version (if using compose)

---

Credits

Based on the original branding extension concept by Zer0CoolX. Rewritten for modern Guacamole with OIDC support.