Add authentication docs

docs/architecture_entities.md

@@ -3,7 +3,7 @@ title: "Entity Architecture"
 sidebar_label: Entity
 ---
 
-![Architecture overview of Hass.io](/img/en/architecture/entities_architecture.svg)
+![Architecture overview of Hass.io](/img/en/architecture/entities_architecture.png)
 
 ## Configuration
 

docs/auth_api.md

@@ -0,0 +1,88 @@
+---
+title: "Authentication API"
+sidebar_label: API
+---
+
+> This is experimental. It is not persisted and is not yet intended for production.
+
+This page will describe the steps required to fetch an access token for a user and how to refresh it. We follow the OAuth 2 specification.
+
+## Requirements
+
+A client needs to be created inside Home Assistant before a client can request users to authorize it or fetch a new access token. The only way currently to create a client is programmatically:
+
+```python
+client = await hass.auth.async_create_client(
+    'Example client',
+    redirect_uris=['http://www.example.com/hass_callback'],
+    no_secret=True,
+)
+print(client.id)
+```
+
+## Authorize
+
+[![Authorization flow sequence diagram](/img/en/auth/authorize_flow.png)](https://www.websequencediagrams.com/?lz=dGl0bGUgQXV0aG9yaXphdGlvbiBGbG93CgpVc2VyIC0-IENsaWVudDogTG9nIGludG8gSG9tZSBBc3Npc3RhbnQKABoGIC0-IFVzZXI6AEMJZSB1cmwgAD4JACgOOiBHbyB0bwAeBWFuZCBhAC0ICgBQDgB1DACBFw5jb2RlAHELAE4RZXQgdG9rZW5zIGZvcgAoBgBBGlQAJQUK&s=qsd)
+
+ - The authorize url should contain `client_id`, `redirect_uri` and, if available, `client_secret` as query parameters. Example: `http://your-instance.com/auth/authorize?client_id=ABCDE&client_secret=QWERTY&redirect_uri=https%3A%2F%2Fexample.com%2Fhass_callback`
+ - The user will navigate to this link, log into Home Assistant and authorize the client.
+ - Once authorized, the user will be redirected back to the passed in redirect uri with the authorization code as part of the query parameters. Example: https://example.com/hass_callback?code=12345
+ - This authorization code can be exchanged for tokens by sending it to the token endpoint (see next section).
+ - As specified in the OAuth 2 specification, it is possible to pass an optional state string to the authorize url using the `state` query parameter. This string will be added as query parameter to the redirect url.
+
+## Token
+
+The token endpoint returns tokens given valid grants. This grant is either an authorization code retrieved from the authorize endpoint or a refresh token.
+
+All interactions with this endpoint need to be HTTP POST requests to `http://your-instance.com/auth/token` with the request body encoded in `application/x-www-form-urlencoded`.
+
+### Authorization code
+
+Use the grant type `authorization_code` to retrieve the tokens after a user has successfully finished the authorize step. The request body is:
+
+```
+grant_type=authorization_code&code=12345
+```
+
+The return response will be an access and refresh token:
+
+```json
+{
+    "access_token": "ABCDEFGH",
+    "expires_in": 1800,
+    "refresh_token": "IJKLMNOPQRST",
+    "token_type": "Bearer"
+}
+```
+
+### Refresh token
+
+Use the grant type `refresh_token` to retrieve an access token using a refresh token. The request body is:
+
+```
+grant_type=refresh_token&refresh_token=QWERTY
+```
+
+The return response will be an access token:
+
+```json
+{
+    "access_token": "ABCDEFGH",
+    "expires_in": 1800,
+    "token_type": "Bearer"
+}
+```
+
+## Making authenticated requests
+
+Once you have an access token, you can make authenticated requests to the Home Assistant APIs.
+
+For the websocket connection, pass the access token in the [authentication message](http://localhost:3000/docs/en/external_api_websocket.html#authentication-phase).
+
+For HTTP requests, pass the token type and access token as the authorization header:
+
+```
+Authorization: Bearer ABCDEFGH
+```
+
+If the access token is no longer valid, you will get a response with HTTP status code 401 unauthorized. This means that you will need to refresh the token. If the refresh token doesn't work, the tokens are no longer valid and the client should ask the user to authorize again.

docs/auth_index.md

@@ -0,0 +1,40 @@
+---
+title: "Authentication"
+sidebar_label: Introduction
+---
+
+> This is an experimental and unfinished API introduced in Home Assistant 0.69 and later. This is not enabled by default, it's not persisted to disk and should not be used in production.
+
+Home Assistant has a built-in authentication system allowing different users to interact with Home Assistant. The authentication system consist of various parts.
+
+![Overview of how the different parts interact](/img/en/auth/architecture.png)
+
+## Authentication providers
+
+An authentication provider is used for users to authenticate themselves. It's up to the authentication provider to choose the method of authentication and the backend to use. By default we enable the built-in Home Assistant authentication provider which stores the users securely inside your configuration directory.
+
+The authentication providers that Home Assistant will use are specified inside `configuration.yaml`. It is possible to have multiple instances of the same authentication provider active. In that case, each will be identified by a unique identifier. Authentication providers of the same type will not share credentials.
+
+## Credentials
+
+Credentials store the authentication of a user with a specific authentication provider. It is produced when a user successfully authenticates. It will allow the system to find the user in our system. If the user does not exist, a new user will be created. This user will not be activated but will require approval by the owner.
+
+It is possible for a user to have multiple credentials linked to it. However, it can only have a single credential per specific authentication provider.
+
+## Users
+
+Each person is a user in the system. To log in as a specific user, authenticate with any of the authentication providers that are linked to this user. When a user logs in, it will get a refresh and an access token to make requests to Home Assistant.
+
+### Owner
+
+The first user to log in to Home Assistant will be marked as the owner. This user is able to manage users.
+
+## Clients
+
+Clients are applications that users use to access the Home Assistant API. Each client has a client identifier, a redirect uri and an optional client secret. The redirect uri is used to redirect the user after it has successfully authorized.
+
+## Access and refresh tokens
+
+The client will be provided with an authorization code when a user successfully authorizes with Home Assistant. This code can be used to retrieve an access and a refresh token. The access token will have a limited lifetime while refresh tokens will remain valid until a user deletes it.
+
+The access token is used to access the Home Assistant APIs. The refresh token is used to retrieve a new valid access token.

docs/external_api_websocket.md

@@ -76,7 +76,7 @@ If authentication is necessary, the server sends out `auth_required`.
 }
 ```
 
-This means that the next message from the client should be an auth message:
+This means that the next message from the client should be an auth message. You can authorize with either an API password (legacy auth) or an access token.
 
 ```json
 {
@@ -85,6 +85,16 @@ This means that the next message from the client should be an auth message:
 }
 ```
 
+or
+
+```json
+{
+  "type": "auth",
+  "access_token": "ABCDEFGH"
+}
+```
+
+
 If the client supplies valid authentication, the authentication phase will complete by the server sending the `auth_ok` message:
 
 ```json

website/i18n/en.json

@@ -16,6 +16,9 @@
     "asyncio_categorizing_functions": "Categorizing Functions",
     "asyncio_index": "Asynchronous Programming",
     "asyncio_working_with_async": "Working with Async",
+    "auth_api": "Authentication API",
+    "API": "API",
+    "auth_index": "Authentication",
     "config_entries_config_flow_handler": "Config Flow Handlers",
     "config_entries_index": "Config Entries",
     "configuration_yaml_index": "Configuration.yaml",
@@ -90,6 +93,7 @@
     "Backend": "Backend",
     "Misc": "Misc",
     "Entities": "Entities",
+    "Authentication": "Authentication",
     "Configuration.yaml": "Configuration.yaml",
     "Config Entries": "Config Entries",
     "Data Entry Flow": "Data Entry Flow",

website/sidebars.json

@@ -13,6 +13,10 @@
       "entity_switch",
       "entity_weather"
     ],
+    "Authentication": [
+      "auth_index",
+      "auth_api"
+    ],
     "Configuration.yaml": [
       "configuration_yaml_index"
     ],