Repository files navigation

A smallHome Assistant integration tooptionally proxy select web traffic through a Home Assistant instance.

Typical usecases are Lovelace cards (e.g.FrigateCard) that cannot directlyaccess resources required (either because the browser may not be on the samenetwork as the backend resources, or because the browser may not allowMixedContent).

There are two main styles of proxying:

• Statically proxying a set of URL patterns (e.g. Accessinghttps://$HA_INSTANCE/api/hass_web_proxy/v0/?url=http%3A%2F%2Fcam-back-yard.mydomain.io will result in a request tohttp://cam-back-yard.mydomain.io).
• Accept Home Assistantaction calls to selectively allow proxying, for use in automations orhass-web-proxy-integration aware Lovelace cards that dynamically select what to proxy.

Add this repository as a custom repository for HACS:

• NavigateHACS -> Integrations -> [Three dots menu] -> Custom repositories
• Repository:https://github.com/dermotduffy/hass-web-proxy-integration/
• Category:Integration
• ClickADD

Download the integration via HACS as normal:

• Click+ EXPLORE & DOWNLOAD REPOSITORIES
• Search forHome Assistant Web Proxy
• ClickDOWNLOAD

Install the integration to your Home Assistant instance:

• NavigateSettings -> Devices & Services
• Click+ Add INTEGRATION
• Search and installHome Assistant Web Proxy
• ClickFINISH

The integration does not proxy anything by default. There are two methods to actuallyproxy:

With this method, the user manually configures static URL patterns to allow proxying for.

Visit the options configuration for the integration:

• NavigateSettings -> Devices & Services
• Click throughHome Assistant Web Proxy in the list of installed integrations
• ClickCONFIGURE
• Click+ ADD to add a URL pattern that should be allowed proxy through the integration(e.g.https://cam-*.mydomain.io to allow proxying any hostname that starts withcam- in themydomain.io domain)
• ClickSUBMIT

Result:

• If the example target to proxy ishttp://cam-back-yard.mydomain.io, first URL encodeit tohttp%3A%2F%2Fcam-back-yard.mydomain.io
• Visitinghttps://$HA_INSTANCE/api/hass_web_proxy/v0/?url=http%3A%2F%2Fcam-back-yard.mydomain.iowill proxy through Home Assistant for authenticated Home Assistant users.

With this method, the user, Home Assistant automation or Lovelace cards, can dynamicallyrequest a URL be proxied:

• Call thehass_web_proxy.create_proxied_url action:

action:hass_web_proxy.create_proxied_urldata:url_pattern:https://cam-*.mydomain.iourl_id:id-that-can-optionally-be-used-to-delete-later

Result:

• If the example target to proxy ishttp://cam-back-yard.mydomain.io, first URL encodeit tohttp%3A%2F%2Fcam-back-yard.mydomain.io
• Visitinghttps://$HA_INSTANCE/api/hass_web_proxy/v0/?url=http%3A%2F%2Fcam-back-yard.mydomain.iowill proxy through Home Assistant for authenticated Home Assistant users.
• The service call will return a dictionary with aurl_id parameter referringto the created proxied URL.

To delete the proxied URL:

• Call thehass_web_proxy.delete_proxied_url action:

action:hass_web_proxy.delete_proxied_urldata:url_id:id-that-can-optionally-be-used-to-delete-later

action:hass_web_proxy.create_proxied_urldata:[...]

action:hass_web_proxy.delete_proxied_urldata:[...]

No URLs are proxied by default.

However, any user, automation or Javascript with authenticated access to theHome Assistant instance could callhass_web_proxy.create_proxied_url to createa dynamically proxied URL, thus exposing arbitrary resources "behind" HomeAssistant to anything/anyone that can access Home Assistant itself.Depending on the setup, this may present an access escalation beyond what wouldusually be accessible. In particular, wide exposure could occur if the user,automation or Javascript setallow_unauthenticated in the dynamically proxiedURL request, which would allow arbitrary internet traffic to be proxied via theHome Assistant instance regardless of whether or not they have valid usercredentials on the HA instance.

All proxying is done by the integration which runs as part of the Home Assistantprocess itself. As such, this proxy is not expected to be particularlyperformant and excessive usage could slow Home Assistant itself down. This isunlikely to be noticeable in practice for casual usage.