Docker - restrict dashboard binding interface to enable modern authentication

[FuNK3Y]

Describe your request

ESPHome should be considered as a sensitive infrastructure component. It exposes secrets and enables flashing arbitrary code to devices.

While it can be protected by username & password, it is cumbersome and does not align with current standards (oidc & oauth).

Modern authentication can already be deferred to a reverse proxy (like TLS termination). But because ESPHome needs direct network visibility to managed devices (such as mDNS discovery), its dashboard also ends up being exposed on the network without protection.

My proposal is to add the ability to bind the ESPHome dashboard to a specific network interface. This ensures the dashboard is only reachable through a reverse proxy, even when the container participates in multiple networks for device discovery.

Why the uncertainty?

There is no category for docker related improvement

Use cases

Expose & protect ESPHome through a reverse proxy, while having it connected to macvlan/ipvlan networks for mdns discovery. Here is a docker compose sample:

default is a bridge network only accessible by docker containers within the same compose
devices is an ipvlan - in the same segment as the esphome devices

services:
  traefik:
    image: traefik:latest
    volumes: 
      - /var/run/docker.sock:/var/run/docker.sock
      - ./traefik:/config
    ports:
      - 80:80
      - 443:443
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped
    command:
      - --accesslog=true
      - --api
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --providers.docker.network=${COMPOSE_PROJECT_NAME}_default
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --entryPoints.websecure.asDefault=true
      - --certificatesresolvers.default.acme.httpchallenge=true
      - --certificatesresolvers.default.acme.httpchallenge.entrypoint=web
      - --certificatesresolvers.default.acme.storage=/config/acme.json
      - --entrypoints.websecure.http.tls.certresolver=default
      - --entrypoints.web.http.redirections.entrypoint.to=websecure

  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:latest
    restart: unless-stopped
    command:
      - --upstream=static://202
      - --http-address=0.0.0.0:4180
      - --skip-provider-button=true
      - --reverse-proxy=true
      - --provider=entra-id
      - --oidc-issuer-url=${OIDC_ISSUER}
      - --client-id=${OIDC_CLIENT_ID}
      - --client-secret=${OIDC_CLIENT_SECRET}
      - --redirect-url=https://oauth.${DOMAIN}/oauth2/callback
      - --whitelist-domain=.${DOMAIN}
      - --cookie-domain=.${DOMAIN}
      - --email-domain=${DOMAIN}
      - --cookie-secret=${COOKIE_SECRET}
    labels:
      - traefik.enable=true
      - traefik.http.routers.oauth2-proxy.rule=Host(`oauth.${DOMAIN}`) || PathPrefix(`/oauth2/`)
      - traefik.http.services.oauth2-proxy.loadbalancer.server.port=4180
      - traefik.http.middlewares.oauth.forwardauth.address=http://oauth2-proxy:4180/
      - traefik.http.middlewares.oauth.forwardauth.trustForwardHeader=true

  esphome:
    image: esphome/esphome:latest
    volumes:
      - ./esphome:/config
      - /etc/localtime:/etc/localtime:ro
    networks:
      default:
      devices:
    environment:
      - DASHBOARD_LISTENING_NETWORK_INTERFACE=eth0
    restart: unless-stopped
    labels:
      - traefik.enable=true
      - traefik.http.routers.esphome.middlewares=oauth
      - traefik.http.services.esphome.loadbalancer.server.port=6052

networks:
  devices:
    driver: ipvlan
    driver_opts:
      parent: eth1.20
    ipam:
      driver: default
      config:
        - subnet: 192.168.64.0/24
          ip_range: 192.168.64.248/29

What areas might this affect?

Docker only. ESPHome already offers the ability to restrict the dashboard listening address.

Anything else?

I already made the required PR esphome/esphome#11876 & esphome/esphome-docs#5666. There are several ways to implement this - happy to take feedbacks!

[FuNK3Y]

As this is not getting traction, I found a dirty workaround: set a very complex username & password for the dashboard and inject the Authorization header at the reverse proxy.

  esphome:
    image: esphome/esphome:latest
    environment:
      - USERNAME=something
      - PASSWORD=complex
...
    labels:
      - traefik.http.routers.esphome.middlewares=esphome_auth
      - traefik.http.middlewares.esphome_auth.headers.customrequestheaders.Authorization=Basic c29tZXRoaW5nOmNvbXBsZXg= #base64 of something:complex
...