Add auth docs (#6068)

* Add auth docs

* Minor tweak

* ✏️ Spelling

* ✏️ Spelling

* ✏️ Spelling and grammar

* Remove impossible

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.
+
+<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 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.
+
+<img src='/images/docs/authentication/profile.png' alt='Screenshot of the profile page' style='border: 0;box-shadow: none;'>
+
+## {% 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.

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
+---
+
+<p class='note warning'>
+This is an advanced feature. If misconfigured, you will not be able to access Home Assistant anymore!
+</p>
+
+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.

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
+---
+
+<p class='note warning'>
+This is an advanced feature. If misconfigured, you will not be able to access Home Assistant anymore!
+</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'>
+By configuring your own instead of using the default configuration, you take full responsibility for the authentication of the system.
+</p>
+
+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.

source/_includes/asides/docs_navigation.html

@@ -41,6 +41,13 @@
           <li>{% active_link /docs/configuration/platform_options/ Entity component platform options %}</li>
         </ul>
       </li>
+      <li>
+        <b>{% active_link /docs/authentication/ Authentication %}</b>
+        <ul>
+          <li>{% active_link /docs/authentication/providers/ Auth Providers %}</li>
+          <li>{% active_link /docs/authentication/multi-factor-auth/ Multi Factor Auth %}</li>
+        </ul>
+      </li>
       <li>
         <b>Core objects</b>
         <ul>