mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-19 15:26:59 +00:00
Tidying up some of the auth docs. (#7146)
* First pass at tidying up auth docs. Rearranged some of the images to enhance the flow and reorganised some of the steps for setting up MFAs. Submitting this as WIP for pull request. * Some more cleanup and changes to the text, mostly for clarity (IMHO). This should be all that is required for the moment, but some more info on Trusted Networks would be useful. I had a few subtle issues setting that up regarding proxies so I'll look at adding that if I figure out how to explain it succinctly. * ✏️ Tweaks * ✏️ Tweaks * ✏️ Tweaks
This commit is contained in:
Ian Slinger
Franck Nijhof
parent
1bfbc35199
commit
a2289c4d06
@ -10,39 +10,56 @@ sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Access to Home Assistant is secured by our authentication system. Each member of your household will get their own user account to log in and access Home Assistant.
|
||||
Our authentication system secures access to Home Assistant.
|
||||
|
||||
Home Assistant contains two different user types: the owner user account and normal users. The owner user account is created when you start Home Assistant for the first time. This account has some special privileges compared to the other users of the system:
|
||||
|
||||
- Manage users
|
||||
- Configure integrations and other settings (soon)
|
||||
- Configure Hass.io (soon)
|
||||
|
||||
## {% linkable_title Authentication %}
|
||||
|
||||
When a user wants to use Home Assistant, they have to log in. When navigating to the frontend without authentication, the user is asked for a login. The login page will always show you the website that you're logging in to.
|
||||
If you are starting Home Assistant for the first time, or you have logged out, you will be asked for credentials before you can log in.
|
||||
|
||||
<img src='/images/docs/authentication/login.png' alt='Screenshot of the login screen' style='border: 0;box-shadow: none;'>
|
||||
|
||||
When logging in, make sure that the URL in the URL bar is showing the address of your Home Assistant instance.
|
||||
## {% linkable_title User accounts %}
|
||||
|
||||
## {% linkable_title Profile %}
|
||||
When you start Home Assistant for the first time the _owner_ user account is created. This account has some special privileges and can:
|
||||
|
||||
Once you're logged in, you can access the profile page by clicking on the badge next to the Home Assistant title in the sidebar. Here you can change your preferred language or change your password. You can also log out.
|
||||
- Create and manage other user accounts.
|
||||
- Configure integrations and other settings (coming soon).
|
||||
- Configure Hass.io (coming soon).
|
||||
|
||||
<p class='note'>
|
||||
For the moment, other user accounts will have the same access as the owner account. In the future, non-owner accounts will be able to have restrictions applied.
|
||||
</p>
|
||||
|
||||
### {% linkable_title Your Account Profile %}
|
||||
|
||||
Once you're logged in, you can see the details of your account at the _Profile_ page by clicking on the circular badge next to the Home Assistant title in the sidebar.
|
||||
|
||||
<img src='/images/docs/authentication/profile.png' alt='Screenshot of the profile page' style='border: 0;box-shadow: none;'>
|
||||
|
||||
## {% linkable_title Multi-factor authentication %}
|
||||
You can:
|
||||
|
||||
As a user, you can setup multi-factor authentication with time-based one-time passwords. This is an extra challenge that you have to solve after you finish your login. You will be able to set up these challenges from the profile page once you're logged in.
|
||||
* Change the language you prefer Home Assistant to use.
|
||||
* Change your password.
|
||||
* Select the [theme](https://www.home-assistant.io/components/frontend/#defining-themes) for the interface of Home Assistant.
|
||||
* Enable or disable [multi-factor authentication](http://127.0.0.1:4000/docs/authentication/multi-factor-auth/).
|
||||
* Delete _Refresh Tokens_. These are created when you log in from a device. Delete them if you want to force the device to log out.
|
||||
* Create [Long Lived Access Tokens](https://developers.home-assistant.io/docs/en/auth_api.html#long-lived-access-token) so scripts can securely interact with Home Assistant.
|
||||
* Log out of Home Assistant.
|
||||
|
||||
<img src='/images/docs/authentication/mfa.png' alt='Screenshot of setting up multi-factor authentication' style='border: 0;box-shadow: none;'>
|
||||
### {% linkable_title Securing your login %}
|
||||
|
||||
_Make sure to choose a secure password!_ At some time in the future, you will probably want to access Home Assistant from outside your local network. This means you are also exposed to random black-hats trying to do the same. Treat the password like the key to your house.
|
||||
|
||||
|
||||
As an extra level of security, you can turn on [multi-factor authentication](http://127.0.0.1:4000/docs/authentication/multi-factor-auth/).
|
||||
|
||||
## {% linkable_title Other authentication techniques %}
|
||||
|
||||
Home Assistant provides several ways to authenticate. See the [Auth Providers](/docs/authentication/providers/) section.
|
||||
|
||||
## {% linkable_title Troubleshooting %}
|
||||
|
||||
### {% linkable_title Authentication failures from `127.0.0.1` %}
|
||||
|
||||
If you're seeting authentication failures from `127.0.0.1` and you're using the `nmap` device tracker, you should [exclude the Home Assistant IP](/components/device_tracker.nmap_tracker/#exclude) from being scanned.
|
||||
If you're seeing authentication failures from `127.0.0.1` and you're using the `nmap` device tracker, you should [exclude the Home Assistant IP](/components/device_tracker.nmap_tracker/#exclude) from being scanned.
|
||||
|
||||
### {% linkable_title Bearer token warnings %}
|
||||
|
||||
@ -56,7 +73,7 @@ If you see this, you need to add an [`api_password`](/components/http/#api_passw
|
||||
|
||||
### {% linkable_title Bearer token informational messages %}
|
||||
|
||||
If instead, you see the following, then this is a message for component developers, to tell them that they need to update how they authenticate to Home Assistant. As an end user you don't need to do anything:
|
||||
If you see the following, then this is a message for component developers, to tell them they need to update how they authenticate to Home Assistant. As an end user you don't need to do anything:
|
||||
|
||||
```txt
|
||||
INFO (MainThread) [homeassistant.components.http.auth] You need to use a bearer token to access /blah/blah from 192.0.2.4
|
||||
@ -70,30 +87,30 @@ While you should hopefully be storing your passwords in a password manager, if y
|
||||
* `auth_provider.homeassistant`
|
||||
* `onboarding`
|
||||
|
||||
When you start Home Assistant next you'll be required to set up authentication again.
|
||||
When you start Home Assistant next, you'll be required to set up authentication again.
|
||||
|
||||
### {% linkable_title Error: invalid client id or redirect url%}
|
||||
|
||||
<img src='/images/docs/authentication/error-invalid-client-id.png' alt='Screenshot of Error: invalid client id or redirect url'>
|
||||
|
||||
You have to use a domain name, not IP address to remote access Home Assistant; otherwise you will get **Error: invalid client id or redirect url** error on the login form. However, you can use the IP address to access Home Assistant in your home network.
|
||||
You have to use a domain name, not IP address, to remote access Home Assistant otherwise you will get **Error: invalid client id or redirect url** error on the login form. However, you can use the IP address to access Home Assistant in your home network.
|
||||
|
||||
It because we only allow using IP address as client ID when your IP address is one of internal network address (e.g., 192.168.0.1) or loopback address (e.g., 127.0.0.1).
|
||||
This is because we only allow an IP address as a client ID when your IP address is an internal network address (e.g., `192.168.0.1`) or loopback address (e.g., `127.0.0.1`).
|
||||
|
||||
If you don't have a valid domain name for your Home Assistant instance, you can modify the `hosts` file on your computer to fake one. For example, if you are on Windows, edit `C:\Windows\System32\Drivers\etc\hosts` file with administrator privilege, add following entry.
|
||||
If you don't have a valid domain name for your Home Assistant instance, you can modify the `hosts` file on your computer to fake one. On Windows, edit the `C:\Windows\System32\Drivers\etc\hosts` file with administrator privilege, or on Linux the `/etc/hosts` file, and add following entry:
|
||||
|
||||
```text
|
||||
12.34.56.78 hassbian.home
|
||||
```
|
||||
|
||||
(Please replace `12.34.56.78` with your Home Assistant's public IP address)
|
||||
Replace `12.34.56.78` with your Home Assistant's public IP address.
|
||||
|
||||
It will allow you to open Home Assistant instance by access `http://hassbian.home:8123/`
|
||||
This will allow you to open Home Assistant at `http://hassbian.home:8123/`
|
||||
|
||||
### {% linkable_title Stuck on Loading data %}
|
||||
|
||||
Some advert blocking software, such as Wipr, also blocks web sockets. If you're stuck on the Loading data screen, try disabling your ad blocker.
|
||||
Some ad blocking software, such as Wipr, also blocks web sockets. If you're stuck on the Loading data screen, try disabling your ad blocker.
|
||||
|
||||
### {% linkable_title Migrating from pre 0.77 %}
|
||||
|
||||
If you were using the authentication system before 0.77, you'll likely have `auth:` and `auth_providers:` defined. You'll need to remove these and let Home Assistant [handle it automatically](https://www.home-assistant.io/docs/authentication/providers/#configuring-auth-providers).
|
||||
If you were using the authentication system before 0.77, you'd likely have `auth:` and `auth_providers:` defined. You'll need to remove these and let Home Assistant [handle it automatically](https://www.home-assistant.io/docs/authentication/providers/#configuring-auth-providers).
|
||||
|
||||
@ -10,23 +10,28 @@ sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
<p class='note warning'>
|
||||
This is an advanced feature. If misconfigured, you will not be able to access Home Assistant anymore!
|
||||
</p>
|
||||
The Multi-factor Authentication (MFA) modules require you to solve a second challenge after you provide your password.
|
||||
|
||||
Besides the authentication providers, it's also possible to configure multi-factor authentication modules. These authentication modules will require the user to solve a second challenge besides just logging in. The idea is that you ask the user for something they know, their username/password, and something they have, like a time-based authentication token from their phone.
|
||||
A password can be compromised in a number of ways, for example, it can be guessed if it is a simple password. MFA provides a second level of defense by requiring:
|
||||
|
||||
The multi-factor authentication module can be used mixed-matched with authentication providers. After the normal authentication provider validation, the login flow will ask the user for additional challenge(s) if there are multi-factor authentication modules enabled for this user. If more than one multi-factor authentication module is enabled, the user can select one of them during the login.
|
||||
* something you know, like your username and password, and
|
||||
* something you have, like a one-time password sent to your phone.
|
||||
|
||||
The multi-factor authentication module has to be enabled for the user before it can be used in the login process. The user can go to the profile page enable it by himself.
|
||||
You can use MFA with any of the other authentication providers. If more than one MFA module is enabled, you can choose one when you log in.
|
||||
|
||||
## {% linkable_title Configuring multi-factor authentication modules %}
|
||||
You can turn MFA on and off in the [profile page](/docs/authentication/#your-account-profile) for your user account.
|
||||
|
||||
<p class='note warning'>
|
||||
By configuring your own instead of using the default configuration, you take full responsibility for the authentication of the system.
|
||||
</p>
|
||||
## {% linkable_title Available MFA modules %}
|
||||
|
||||
Multi-factor authentication modules are configured in your `configuration.yaml` file under the `homeassistant:` block:
|
||||
### {% linkable_title Time-based One-Time Password MFA module %}
|
||||
|
||||
[Time-based One-Time Password](https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm) (TOTP) is widely adopted in modern authentication systems.
|
||||
|
||||
Home Assistant generates a secret key which is synchronized with an app on your phone. Every thirty seconds or so the phone app generates a random six digit number. Because Home Assistant knows the secret key, it knows which number will be generated. If you enter the correct digits, then you're in.
|
||||
|
||||
#### {% linkable_title Setting up TOTP %}
|
||||
|
||||
Enable TOTP in your `configuration.yaml` like this:
|
||||
|
||||
```yaml
|
||||
homeassistant:
|
||||
@ -34,45 +39,37 @@ homeassistant:
|
||||
- type: totp
|
||||
```
|
||||
|
||||
## {% linkable_title Available multi-factor authentication modules %}
|
||||
If no `auth_mfa_modules` config section is defined in `configuration.yaml` a TOTP module named "Authenticator app" will be autoloaded.
|
||||
|
||||
Below is a list of the currently available auth providers.
|
||||
You will need an authenticator app on your phone. We recommend either [Google Authenticator](https://support.google.com/accounts/answer/1066447) or [Authy](https://authy.com/). Both are available for iOS or Android.
|
||||
|
||||
### {% linkable_title Time-based One-Time Password multi-factor authentication module %}
|
||||
After restarting Home Assistant, go to your [profile page](/docs/authentication/#your-account-profile) and there should be a "Multi-factor Authentication Modules" section.
|
||||
|
||||
[Time-based One-Time Password](https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm) is widely adopted in modern authentication system, it combines a secret key with the current timestamp using a cryptographic hash function to generate a one-time password. Whoever possessed the secret key will get same one-time password in certain time period. By verifying that password, Home Assistant knows the user have the right secret key.
|
||||
Click _Enable_ and a new secret key will be generated. Go to your phone app and enter the key, either by scanning the QR code or typing in the key below the QR code manually.
|
||||
|
||||
When trying to set up TOTP module, a QR code will show up. The user can scan it by an authenticator app, or set it up manually using the code showed in the UI. After setup, the user needs to input a six digit number generated in the authenticator app to verify the setup is good. If the verification keeps failing, you need to check whether the clock on Home Assistant is accurate.
|
||||
|
||||
There are several authenticator apps on the market, we recommend either [Google Authenticator](https://support.google.com/accounts/answer/1066447) or [Authy](https://authy.com/).
|
||||
<img src='/images/docs/authentication/mfa.png' alt='Screenshot of setting up multi-factor authentication' style='border: 0;box-shadow: none;'>
|
||||
|
||||
<p class='note warning'>
|
||||
Please treat the secret key like a password, never expose it to others.
|
||||
Please treat the secret key like a password - never expose it to others.
|
||||
</p>
|
||||
|
||||
By default one TOTP multi-factor auth module named "Authenticator app" will be auto loaded if no `auth_mfa_modules` config section defined in `configuration.yaml`.
|
||||
Your phone app will now start generating a different six-digit code every thirty seconds or so. Enter one of these into Home Assistant under the QR code where it asks for a _Code_. Home Assistant and your phone app are now in sync and you can now use the code displayed in the app to log in.
|
||||
|
||||
Example of configuration:
|
||||
#### {% linkable_title Using TOTP %}
|
||||
|
||||
```yaml
|
||||
homeassistant:
|
||||
auth_mfa_modules:
|
||||
- type: totp
|
||||
```
|
||||
Once TOTP is enabled, Home Assistant requires the latest code from your phone app before you can log in.
|
||||
|
||||
<p class='note'>
|
||||
TOTP is _time based_ so it relies on your Home Assistant clock being accurate. If the verification keeps failing, make sure the clock on Home Assistant is correct.
|
||||
</p>
|
||||
|
||||
### {% linkable_title Notify multi-factor authentication module %}
|
||||
|
||||
Notify MFA module using [notify component](https://www.home-assistant.io/components/notify/) to delivery a [HMAC-based One-Time Password](https://en.wikipedia.org/wiki/HMAC-based_One-time_Password_algorithm) to user configured target.
|
||||
The Notify MFA module uses the [notify component](https://www.home-assistant.io/components/notify/) to send you an [HMAC-based One-Time Password](https://en.wikipedia.org/wiki/HMAC-based_One-time_Password_algorithm). It is typically sent to your phone, but can be sent to any destination supported by a `notify` service. You use this password to log in.
|
||||
|
||||
User need first set up the MFA module by select one of the available notify service. A 6 digit one-time password will be sent by this notify service, user need to input it to verify the setup.
|
||||
#### {% linkable_title Setting up TOTP %}
|
||||
|
||||
During the login process, a 6 digit one-time password will be sent again, user need to input it to verify his/her identity. If the validation failed, a new one-time password will be sent again.
|
||||
|
||||
<p class='note'>
|
||||
Notify MFA module would not verify the one-time password delivery success, so that if user cannot received the message due any reason, he/she may not be login again. Edit or remove `[your_config_dir]/.storage/auth_module.notify` can disable notify MFA module to resolve the issue.
|
||||
</p>
|
||||
|
||||
Example of configuration
|
||||
Add Notify MFA to your `configuration.yaml` file like this:
|
||||
|
||||
```yaml
|
||||
homeassistant:
|
||||
@ -82,12 +79,12 @@ homeassistant:
|
||||
|
||||
Optional configuration variables:
|
||||
|
||||
- **exclude** (*Optional*): The list of notify services you do not want to include in.
|
||||
- **include** (*Optional*): The list of notify services you want to include in.
|
||||
- **message** (*Optional*): The message template
|
||||
- **exclude** (*Optional*): The list of notifying services you do not want to include.
|
||||
- **include** (*Optional*): The list of notifying services you want to include.
|
||||
- **message** (*Optional*): The message template.
|
||||
|
||||
```yaml
|
||||
# Example configure with message template
|
||||
# Example configuration, with a message template.
|
||||
homeassistant:
|
||||
auth_mfa_modules:
|
||||
- type: totp
|
||||
@ -95,3 +92,15 @@ homeassistant:
|
||||
- type: notify
|
||||
message: 'I almost forget, to get into my clubhouse, you need to say {}'
|
||||
```
|
||||
|
||||
After restarting Home Assistant, go to your [profile page](/docs/authentication/#your-account-profile) and there should be a "Multi-factor Authentication Modules" section. Click _Enable_ on the _Notify One-Time Password_ option.
|
||||
|
||||
Try logging out, then logging in again. You will be asked for the six-digit one-time password that was sent to your notify service. Enter the password to log in.
|
||||
|
||||
If the validation failed, a new one-time password will be sent again.
|
||||
|
||||
<p class='note'>
|
||||
The Notify MFA module can't tell if the one-time password was delivered successfully. If you don't get the notification, you won't be able to log in.
|
||||
|
||||
You can disable the Notify MFA module by editing or removing the file `[your_config_dir]/.storage/auth_module.notify`.
|
||||
</p>
|
||||
|
||||
@ -10,27 +10,24 @@ sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
<p class='note warning'>
|
||||
This is an advanced feature. If misconfigured, you will not be able to access Home Assistant anymore!
|
||||
When you log in, an _auth provider_ checks your credentials to make sure you are an authorized user.
|
||||
|
||||
<p class='note'>
|
||||
The authentication system has been changed recently. Previously there was a single "_API password_" to log in, but you can now choose from several auth providers.<br/> <br/>
|
||||
|
||||
To make the transition from API passwords easier, we've added a _Legacy API Password_ auth provider. This is enabled by default if you have an API password configured so you will still be able to log in.
|
||||
|
||||
However, this feature is deprecated and will be removed in a future release so you should set up one of the newer authentication techniques.
|
||||
</p>
|
||||
|
||||
When a user logs in, it needs to authenticate against an auth provider. An auth provider will check the users' credentials, and if credentials are linked to a user in the system, allows the user to log in.
|
||||
|
||||
By default, Home Assistant has enabled an auth provider that stores the users in the configuration directory. An owner account can manage these users from the frontend.
|
||||
|
||||
To make the transition from API password to authentication system easier, we've added a legacy API password auth provider. This enables users to log in with the API password. This authentication provider is enabled by default if a user has an API password configured.
|
||||
|
||||
## {% linkable_title Configuring auth providers %}
|
||||
|
||||
<p class='note warning'>
|
||||
Home Assistant automatically configures the standard auth providers and you **do not** need to specify `auth_providers` in your `configuration.yaml` file. Specifying `auth_providers` in your configuration will disable all auth providers that are not listed and can reduce your security or create difficulties logging in.
|
||||
Home Assistant automatically configures the standard auth providers so you don't need to specify `auth_providers` in your `configuration.yaml` file unless you are configuring more than one. Specifying `auth_providers` will disable all auth providers that are not listed, so you could reduce your security or create difficulties logging in if it is not configured correctly.
|
||||
</p>
|
||||
|
||||
<p class='note warning'>
|
||||
[Issue 16441](https://github.com/home-assistant/home-assistant/issues/16441): the legacy API password auth provider won't be automatically configured if your API password is located in a package. This is because Home Assistant processes the `auth_provider` during the `core` section loading, which is earlier than the `packages` processing.
|
||||
</p>
|
||||
|
||||
Authentication providers are configured in your `configuration.yaml` under the `homeassistant:` block:
|
||||
Authentication providers are configured in your `configuration.yaml` under the `homeassistant:` block. You can supply more than one, for example:
|
||||
|
||||
```yaml
|
||||
homeassistant:
|
||||
@ -41,13 +38,15 @@ homeassistant:
|
||||
|
||||
## {% linkable_title Available auth providers %}
|
||||
|
||||
Below is a list of currently available auth providers.
|
||||
|
||||
### {% linkable_title Home Assistant auth provider %}
|
||||
|
||||
This is the default auth provider which stores the users in your configuration directory. All passwords are stored hashed and with a salt, making it almost impossible for an attacker to figure out the password from the storage.
|
||||
This is the default auth provider. The first user created is designated as the _owner_ and can create other users.
|
||||
|
||||
Users for this auth provider can be managed via the UI by the owner. Navigate to the configuration panel and click on users.
|
||||
User details are stored in the `[your config]/.storage` directory. All passwords are stored hashed and with a salt, making it almost impossible for an attacker to figure out the password even if they have access to the file.
|
||||
|
||||
Users can be managed in Home Assistant by the owner. Go to the configuration panel and click on _Users_.
|
||||
|
||||
This is the entry in `configuration.yaml` for Home Assistant auth:
|
||||
|
||||
```yaml
|
||||
homeassistant:
|
||||
@ -55,14 +54,20 @@ homeassistant:
|
||||
- type: homeassistant
|
||||
```
|
||||
|
||||
If you don't specify any `auth_providers` section in the `configuration.yaml` file then this provider will be set up automatically.
|
||||
|
||||
### {% linkable_title Trusted Networks %}
|
||||
|
||||
With the trusted networks auth provider you can whitelist an IP range for which no authentication will be required. The user will be prompted to pick a user to log in as.
|
||||
The Trusted Networks auth provider defines a range of IP addresses for which no authentication will be required (also known as "whitelisting"). For example, you can whitelist your local network so you won't be prompted for a password if you access Home Assistant from inside your home.
|
||||
|
||||
When you log in from one of these networks, you will be asked which user account to use and won't need to enter a password.
|
||||
|
||||
<p class='note info'>
|
||||
The [multi-factor autentication module](../multi-factor-auth) will not participate in login process by using this auth provider.
|
||||
The [multi-factor authentication module](/authentication/multi-factor-auth/) will not participate in the login process if you using this auth provider.
|
||||
</p>
|
||||
|
||||
Here is an example in `configuration.yaml` to set up Trusted Networks:
|
||||
|
||||
```yaml
|
||||
homeassistant:
|
||||
auth_providers:
|
||||
@ -80,6 +85,10 @@ http:
|
||||
|
||||
### {% linkable_title Legacy API password %}
|
||||
|
||||
<p class='note warning'>
|
||||
This is a legacy feature for backwards compatibility and will be dropped in a future release. You should move to one of the other auth providers.
|
||||
</p>
|
||||
|
||||
Activating this auth provider will allow you to authenticate with the API password set in the HTTP component.
|
||||
|
||||
```yaml
|
||||
@ -92,3 +101,7 @@ http:
|
||||
```
|
||||
|
||||
Activating this auth provider will also allow you to provide the API password using an authentication header to make requests against the Home Assistant API. This feature will be dropped in the future in favor of long-lived access tokens.
|
||||
|
||||
<p class='note warning'>
|
||||
[Issue 16441](https://github.com/home-assistant/home-assistant/issues/16441): the legacy API password auth provider, won't be automatically configured if your API password is located in a package. This is because Home Assistant processes the `auth_provider` during the `core` section loading, which is earlier than the `packages` processing.
|
||||
</p>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user