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>

guacamole/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 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)
+
 - 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,25 @@ 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.
+- Guacamole's header authentication trusts whoever sends the `REMOTE_USER` header, and this add-on
+  also publishes port `8080/tcp` straight to Guacamole, bypassing the Ingress proxy. Do not publish
+  that port while the `auth-header` extension is enabled — anyone who can reach it can send the
+  header themselves and log in as any user.
+
 ### 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,17 @@ 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
+
 # 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%%;
     }
 }