fix(guacamole): let Ingress sign in as the Home Assistant user (#3089)

* fix(guacamole): let Ingress sign in as the Home Assistant user

The ingress nginx config hardcodes `proxy_set_header REMOTE_USER guacadmin`,
added in ce80bbea so that the auth-header extension auto-logs-in out of the
box. The side effect is that every Ingress session authenticates as guacadmin,
whoever is logged into Home Assistant.

Add a `login_with_ha_user` option. The header value becomes a `%%ingress_user%%`
placeholder, substituted in 90-ingress.sh the way calibre_web already does it:
`guacadmin` by default, or `$http_x_remote_user_name` — the Home Assistant
username the Supervisor already sends as `X-Remote-User-Name` on every ingress
request — when the option is on. Left off, the rendered config is byte-for-byte
what it is today.

Closes #3087

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(guacamole): warn when auth-header is reachable through the published port

The auth-header extension trusts any REMOTE_USER header, and 8080/tcp is
published straight to Tomcat, bypassing the Ingress nginx that sets that
header. With both in place, anyone who can reach the host port can log in
as any Guacamole user, including guacadmin. This predates #3087 but the new
SSO section makes auth-header more likely to be enabled.

Print a SECURITY RISK warning at startup when EXTENSIONS contains
auth-header and the port is published, and turn the README note into a
warning callout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

guacamole/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.6.0-bullseye-4 (24-09-2026)
+- Ingress: new `login_with_ha_user` option to sign in with your Home Assistant username instead of always `guacadmin` (#3087)
+- Startup log and README warn when the `auth-header` extension is enabled while port 8080 is published, since that port bypasses Ingress and lets anyone log in as any user
+
 - Migrate legacy add-on configuration map names to current app configuration terminology.
 ## 1.6.0-bullseye-3 (13-03-2026)
 - Fix PROXY_ALLOWED_IPS_REGEX default from invalid regex "*" to ".*"

guacamole/README.md

@@ -47,6 +47,7 @@ The default username is `guacadmin` with password `guacadmin`. It is strongly re
 |--------|------|---------|-------------|
 | `EXTENSIONS` | str | `auth-totp` | Guacamole extensions to enable (e.g., `auth-totp`, `history-recording-storage`) |
 | `recording_search_path` | str | `/config/recordings` | Directory added to `guacamole.properties` as the `recording-search-path` used by the history recording storage extension |
+| `login_with_ha_user` | bool | `false` | Log in through Ingress as your Home Assistant username instead of always `guacadmin` (needs the `auth-header` extension) |
 | `TZ` | str | | Timezone (e.g., `Europe/London`) |
 
 ### Example Configuration
@@ -57,6 +58,29 @@ recording_search_path: "/config/recordings"
 TZ: "Europe/London"
 ```
 
+### Home Assistant single sign-on
+
+Set `EXTENSIONS: "auth-header"` and `login_with_ha_user: true`, then create a Guacamole user for
+each Home Assistant username that should have access. Ingress then signs each person in as their
+own Home Assistant user instead of always `guacadmin`. A Home Assistant user with no matching
+Guacamole account gets the normal login form instead.
+
+Notes:
+
+- The option feeds the `auth-header` extension through its default header, `REMOTE_USER`. If you
+  previously added an `http-auth-header:` line to `/config/guacamole.properties`, remove it, or
+  the extension will keep reading the header you named there and this option will do nothing.
+- Stick to plain ASCII usernames. Accented or non-Latin characters have to survive nginx, Tomcat
+  and Java without an agreed encoding, and they are not guaranteed to match the Guacamole account.
+
+> [!WARNING]
+> **Security risk: `auth-header` with the published port.** Guacamole's header authentication
+> trusts whoever sends the `REMOTE_USER` header, and port `8080/tcp` (host port `4822` by default)
+> goes straight to Guacamole, bypassing the Ingress proxy. While `auth-header` is enabled, anyone
+> who can reach that port can send the header themselves and log in as any user, including
+> `guacadmin`. The add-on prints a `SECURITY RISK` warning in its startup log in that case. Clear
+> the port in the add-on's Network settings and use Ingress only, or remove `auth-header`.
+
 ### Database Setup
 
 The addon automatically configures a PostgreSQL database for storing Guacamole configurations, users, and connections. The database files are stored in `/config/postgres` and are automatically created on first startup.

guacamole/config.yaml

@@ -97,10 +97,11 @@ schema:
     - name: match(^[A-Za-z0-9_]+$)
       value: str?
   EXTENSIONS: str?
+  login_with_ha_user: bool?
   recording_search_path: str?
   TZ: str?
 slug: guacamole
 udev: true
 url: https://github.com/alexbelgium/hassio-addons
-version: "1.6.0-bullseye-3"
+version: "1.6.0-bullseye-4"
 video: true

guacamole/rootfs/etc/cont-init.d/90-ingress.sh

@@ -8,6 +8,7 @@ set -e
 declare port
 declare certfile
 declare ingress_interface
+declare ingress_user
 declare ingress_port
 declare keyfile
 
@@ -33,6 +34,24 @@ ingress_interface=$(bashio::addon.ip_address)
 sed -i "s/%%port%%/${ingress_port}/g" /etc/nginx/servers/ingress.conf
 sed -i "s/%%interface%%/${ingress_interface}/g" /etc/nginx/servers/ingress.conf
 
+# The auth-header extension reads REMOTE_USER. Default to guacadmin, which is what
+# this add-on has always sent; with login_with_ha_user, send the Home Assistant
+# username that the Supervisor puts in X-Remote-User-Name on every ingress request.
+ingress_user='guacadmin'
+if bashio::config.true 'login_with_ha_user'; then
+    # shellcheck disable=SC2016
+    ingress_user='$http_x_remote_user_name'
+    bashio::log.info "Ingress logs in with the Home Assistant username"
+fi
+sed -i "s|%%ingress_user%%|${ingress_user}|g" /etc/nginx/servers/ingress.conf
+
+# auth-header trusts any REMOTE_USER header, and the published port reaches Tomcat without nginx
+if [[ "$(bashio::config 'EXTENSIONS')" == *auth-header* ]] && bashio::var.has_value "$(bashio::addon.port 8080)"; then
+    bashio::log.warning "SECURITY RISK: the auth-header extension is enabled and port 8080 is published on host port $(bashio::addon.port 8080)."
+    bashio::log.warning "Anyone who can reach that port can send a REMOTE_USER header and log in as any Guacamole user, including guacadmin."
+    bashio::log.warning "Disable the port in the add-on Network settings and use Ingress, or remove auth-header from EXTENSIONS."
+fi
+
 # Implement SUBFOLDER value
 if [ -f /etc/s6-overlay/s6-rc.d/svc-autostart/run ]; then sed -i "1a SUBFOLDER=$(bashio::addon.ingress_url)" /etc/s6-overlay/s6-rc.d/svc-autostart/run; fi
 if [ -f /etc/services.d/guacamole/run ]; then sed -i "2a SUBFOLDER=$(bashio::addon.ingress_url)" /etc/services.d/guacamole/run; fi

guacamole/rootfs/etc/nginx/servers/ingress.conf

@@ -13,7 +13,7 @@ server {
        proxy_set_header Connection "Upgrade";
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
-       proxy_set_header REMOTE_USER guacadmin;
+       proxy_set_header REMOTE_USER %%ingress_user%%;
     }
 }