One Time Service

Home Assistant Add-on

Gitlab Github Add-on Repo

Call a service with a one time token from outside Home Assistant!

“One Time Service” lets you create publically exposed tokens for one time usage, that will execute a Home Assistant service without any authentication. This is great, e.g. for visitors who don’t have an account on your Home Assistant instance.

Possible use cases:

  • Allow a visitor to unlock the door themselves if no one else is at home
  • Allow neighbors to notifiy you of emergencies by turning a smart RGB light red
  • Let your neighbors activate your vacuum cleaner when you are on vacation

Installation and configuration

Supervisor addon add repository

This button will add the add-on repository at https://git.leon.wtf/leon/leon.wtf-home-assistant-addons to your Home Assistant. You can then install and update One Time Service via the Add-on store.

The add-on provides a separate port with web server (by default at 1337/tcp) that can be used by a reverse proxy to make it available on the Internet. Meanwhile, the Home Assistant itself can remain behind the firewall. The add-on must be given the host name specified by the reverse proxy via the configuration variable public_token_base_url. One Time Service uses this base URL to create the One Time Tokens, which can then be distributed to others.

Usage

A service call is a possibly complex Home Assistant service call used for better reusability inside the add-on, e.g. if used in multiple tokens at once or if a token must be recreated on a regular basis. It is defined using Home Assistant’s native YAML syntax and can therefore be copied directly from the developer tools, for example.

A token is configured to execute a previously created service call and can optionally have a comment visible on the submission page, an upper limit for submissions, and/or an expiry time.

Define a new service call

Service call creation

Create a token from a service call

Token creation

Public token submission page

Token submission portal

One Time service can even be configured to send notifications to a Home Assistant notify entity once a Token has been submitted.

Insight into the development

The backend of the add-on was developed using Go. The dashboard is written in React, while the public submission portal is written in plain HTML and JavaScript. Pico CSS was used for styling.

Home Assistant add-ons are just Docker containers under the hood, which are managed by the Home Assistant Supervisor. Since Docker containers rely on the operating system kernel, they are architecture-dependent – in contrast to virtual machines. This is a particular problem with Home Assistant, as it is executed on multiple architectures. These include full-size computers with x86/amd64, but also, for example, the Raspberry Pi with armv7/armv8, both as 32- and 64-bit variants. It is therefore necessary to provide the add-on for all these architectures.

Gitlab CI/CD pipelines are used to build the Docker images so that the entire build process does not have to be carried out manually for every code change. Since I don’t have any multi-architecture runtimes available, I have to resort to cross-compilation. Fortunately, Docker allows this with the new BuildKit. With docker buildx a builder can be created that can generate a multi-arch manifest for multiple architectures. Currently the image registry.git.leon.wtf/leon/one-time-service/multiarch is created for linux/amd64, linux/arm64 and linux/arm/v7. Home Assistant automatically recognizes and installs the matching architecture to be used!

A blog entry on BuildKit will follow shortly!