From ce9d0751ea33de74cc136ad414e205729a9de7be Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Fri, 24 Aug 2018 17:07:45 +0200 Subject: [PATCH] Add auth docs (#6068) * Add auth docs * Minor tweak * :pencil2: Spelling * :pencil2: Spelling * :pencil2: Spelling and grammar * Remove impossible --- source/_docs/authentication.markdown | 37 ++++++++ .../authentication/multi-factor-auth.markdown | 19 ++++ .../_docs/authentication/providers.markdown | 86 ++++++++++++++++++ source/_includes/asides/docs_navigation.html | 7 ++ source/images/docs/authentication/login.png | Bin 0 -> 38191 bytes source/images/docs/authentication/profile.png | Bin 0 -> 57806 bytes 6 files changed, 149 insertions(+) create mode 100644 source/_docs/authentication.markdown create mode 100644 source/_docs/authentication/multi-factor-auth.markdown create mode 100644 source/_docs/authentication/providers.markdown create mode 100644 source/images/docs/authentication/login.png create mode 100644 source/images/docs/authentication/profile.png diff --git a/source/_docs/authentication.markdown b/source/_docs/authentication.markdown new file mode 100644 index 00000000000..9ebb653c51a --- /dev/null +++ b/source/_docs/authentication.markdown @@ -0,0 +1,37 @@ +--- +layout: page +title: "Authentication" +description: "Guide on authentication in Home Assistant." +date: 2018-08-23 09:40 +redirect_from: /components/auth/ +sidebar: true +comments: false +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. + +Home Assistant contains two different user types: the owner user account and normal users. The owner user account is created when you start Home Assitant 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. + +Screenshot of the login screen + +When logging in, make sure that the URL in the URL bar is showing the address of your Home Assistant instance. + +## {% linkable_title Profile %} + +Once you're logged in, you can access the profile page to change your user preferences. Here you can change your preferred language or password. You can also log out. You can access the profile page by clicking on your user badge in the sidebar. + +Screenshot of the profile page + +## {% linkable_title Multi-factor authentication %} (soon) + +As a user, you can setup multi-factor authentication like 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. diff --git a/source/_docs/authentication/multi-factor-auth.markdown b/source/_docs/authentication/multi-factor-auth.markdown new file mode 100644 index 00000000000..751f2010569 --- /dev/null +++ b/source/_docs/authentication/multi-factor-auth.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Multi-factor authentication" +description: "Guide on configuring different multi-factor authentication providers." +date: 2018-08-23 09:40 +redirect_from: /components/auth/ +sidebar: true +comments: false +sharing: true +footer: true +--- + +

+This is an advanced feature. If misconfigured, you will not be able to access Home Assistant anymore! +

+ +Besides the normal authentication providers, it's also possible to configure multi-factor authentication providers. These authentication providers 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. + +This feature is currently a work in progress and no configurable multi-factor authentication providers are currently available. diff --git a/source/_docs/authentication/providers.markdown b/source/_docs/authentication/providers.markdown new file mode 100644 index 00000000000..1a190543355 --- /dev/null +++ b/source/_docs/authentication/providers.markdown @@ -0,0 +1,86 @@ +--- +layout: page +title: "Authentication Providers" +description: "Guide on configuring different auth providers." +date: 2018-08-23 09:40 +redirect_from: /components/auth/ +sidebar: true +comments: false +sharing: true +footer: true +--- + +

+This is an advanced feature. If misconfigured, you will not be able to access Home Assistant anymore! +

+ +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 %} + +

+By configuring your own instead of using the default configuration, you take full responsibility for the authentication of the system. +

+ +Authentication providers are configured in your `configuration.yaml` under the `homeassistant:` block: + +```yaml +homeassistant: + auth_providers: + - type: homeassistant + - type: legacy_api_password +``` + +## {% 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. + +Users for this auth provider can be managed via the UI by the owner. Navigate to the configuration panel and click on users. + +```yaml +homeassistant: + auth_providers: + - type: homeassistant +``` + +### {% linkable_title Trusted Network %} + +With the trusted network 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. + +```yaml +homeassistant: + auth_providers: + - type: trusted_networks + +# Temporary, this will be moved to be part of auth provider config +# https://github.com/home-assistant/home-assistant/issues/16149 +http: + trusted_networks: + - 127.0.0.1 + - ::1 + - 192.168.0.0/24 + - fd00::/8 +``` + +### {% linkable_title Legacy API password %} + +Activating this auth provider will allow you to authenticate with the API password set in the HTTP component. + +```yaml +homeassistant: + auth_providers: + - type: legacy_api_password + +http: + api_password: !secret http_password +``` + +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. diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index 8256e7e1e1a..4c9aef28624 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -41,6 +41,13 @@
  • {% active_link /docs/configuration/platform_options/ Entity component platform options %}
    • +
  • + {% active_link /docs/authentication/ Authentication %} + +
  • Core objects