Home Assistant Authentication System

Starting on release 0.77 Home Assistant use by default its own authentication system and it will require you to create the owner’s user account in the first access to the frontend. With this system, every user of Home Assistant could and should have its own user account which can be created by the owner’s user account. Let’s see how.

Owner user account

As I mentioned above, the first time you access the Home Assistant interface after installing or upgrading to version 0.77 or later, you will be asked to create the owner’s user account. This account has some special privileges compared to other users of the system such as managing users or configuring integrations and other settings (coming soon).

To create this account you only need to enter a name, a username and a password when prompted and done.

 

Authentication

After you have created an user account, you will be prompted to enter the username and password of the account you wish to log in to when you access the Home Assistant frontend again.

When you sign in, make sure that the address bar URL displays the address of your Home Assistant instance.

 

User profile

Once you are logged in, you can access the profile page by clicking on the user badge next to the Home Assistant title in the left sidebar. Here you can change the interface language, your account password, log out or enable the two-factor authentication.

 

Two-factor authentication

In the ‘Multi-factor Authentication Modules’ section of the user profile page, you can enable the two-factor authentication. This feature will increase the security of your user account and require you to enter a time-based code generated by an application such as Google Authenticator or Authy after intruding your username and password when you log in.

It’s not difficult to enable this feature, and now I’ll show you how to do it using Google Authenticator, but keep in mind that if it’s misconfigured, you won’t be able to access Home Assistant anymore.

You need to have at least one multi-factor authentication module configured in your configuration.yaml file under the homeassistant: auth_mfa_modules: block.

homeassistant:
  auth_mfa_modules:
    - type: totp

If more than one multi-factor authentication module is enabled, the user can select one of them during login.

totp is a time-based password module that supports Google Authenticator and Authy and is configured by default, so you don’t need to touch the configuration.yaml file to use Google Authenticator.

What you need to do is install Google Authenticator on your iPhone or Android phone if you don’t already have it.

Then click on the ‘ENABLE’ button in the ‘Multi-factor Authentication Modules’ section and scan the QR code with the Google Authenticator app. Google Authenticator will show you a code that you must enter on the ‘Set up two-factor authentication using TOTP’ pop-up.

If you enter the code correctly you should get a success message.

However, if you get an invalid code error consistently check that you have set the time zone of your Home Assistant instance correctly.

You can find a list of compatible time zones on wikipedia.org/wiki/List_of_tz_database_time_zones and then set your time zone in your configuration.yaml.

For instance:

homeassistant:
  time_zone: Europe/London

From now on, you’ll be prompted to enter the code that is displayed in Google Authenticator when you sign in to Home Assistant.

 

Adding more user accounts

One of the privileges of the owner account is the creation of new user accounts. You will find this option under ‘Configuration > Users’.

Here you can add a user by assigning their name, username and password.

From the view user page you can delete the user account if necessary.

 

Recovering the owner account

If you ever lose the password of the owner account the only way to recover access as an owner is to delete all authentication data. To do this, you must shut down Home Assistant and delete the following files from the .storage/ folder in your configuration folder:

• auth
• auth_provider.homeassistant
• onboarding

 

---

Some handy links

Home Assistant : Authentication
Home Assistant : Multi-factor authentication
Home Assistant : UTC & Time zone awareness

How to install Home Assistant on an Orange Pi Zero