Remote UI

With our Remote UI feature you are able to connect remotely to your Home Assistant instance. As a user, the only configuration step that you need is to enable it from the cloud configuration panel. Once enabled, Home Assistant will generate a security certificate for secure communication and provide you with a url that is accessible while away from home.

To get started, open Home Assistant, go to the cloud page in the configuration panel. Find the remote box and enable the toggle. The first time you enable it, Home Assistant Cloud will have to generate and validate the certificate. This can take up to 60 seconds. This feature requires Home Assistant 0.90 or later.

Screenshot of the remote configuration card.

This URL will only be accessible when your local instance is connected to the remote UI server. By default Home Assistant will maintain a connection when remote connections are allowed. When not connected, the remote URL will not be accessible.

You may find yourself in a situation where you are away from home and want to access your instance, but it is not connected to your remote UI server. In this case you can navigate to Remote UI portal to get your instance online. You can also use this page if you forgot your url.

Automating availability of the remote UI

As a Home Assistant user, you might like to automate things. We understand! The cloud component exposes two service to enable and disable the remote connection: cloud/remote_connect and cloud/remote_disconnect. That way you can turn on the remote connection only when you leave the house and need it.

How it works

The remote UI encrypts all communication between your browser and your local instance. Encryption is provided by a Let’s Encrypt certificate. Under the hood, your local Home Assistant instance is connected to one of our custom built UI proxy servers. Our UI proxy servers operate at the TCP level and will forward all encrypted data to the local instance.

Routing is made possible by the Server Name Indication (SNI) extension on the TLS handshake. It contains for which hostname an incoming request is destined, and we forward it to the matching local instance. To be able to route multiple simultaneous requests all data will be routed via a TCP multiplexer. The local Home Assistant instance will receive the TCP packets, demultiplex them, decrypt them with the SSL certificate and forward them to the HTTP component.

The source code is available on GitHub:

  • SniTun - End-to-End encryption with SNI proxy on top of a TCP multiplexer
  • hass-nabucasa - Cloud integration in Home Assistant

Caveats

We are currently not forwarding the IP address of the incoming request. Because of this, we are unable to support Home Assistant instances that have configured 127.0.0.1 or ::1 as trusted networks. It also means that if you use IP bans, the remote connection will be banned as a whole instead of just the address from which the incorrect passwords were entered. We are currently exploring a solution for this issue.

Security

Making a secure solution is a challenge. In this section we want to discuss the things we do to improve security, what weaknesses there are in our approach, and how we plan to solve them.

Our approach is secure because:

  • All data is encrypted between your browser and your local instance. The local instance has generated and owns the certificate and so only the local instance will be able to decrypt the incoming traffic.
  • Once a user is communicating with their Home Assistant instance, they will have to log in with their local credentials. These credentials are only stored locally and cannot be impersonated by anyone.

Before we talk about weaknesses, know that we will never abuse any weakness unless forced by a government entity. Our approach has one single weakness that is unavoidable: since we own the domain that hosts the remote connection, we are able to issue our own certificate and man-in-the-middle attack (MITM) remote connections. This would allow us to see all data passing through, including authentication tokens.

It is not going to be possible to avoid MITM attacks. However, it is possible to spot them:

  • You can validate that there is no MITM happening by making sure that the certificate fingerprints matches with the local instance certificate fingerprint. You can find the fingerprint by looking at the certificate info in the cloud configuration page inside Home Assistant.
  • Let’s Encrypt takes part of the experimental internet security standard Certificate Transparency (CT). The standard creates a system of public logs that will record all certificates issued, allowing local Home Assistant instances to spot if their certificate is being impersonated. We’re exploring how to automatically audit this on the local instance.