a714c781a6
website/docs: Reduce redundant usage of badges. Move badge logic to components. - Fix JSX class name warning. - Remove duplicate titles. - Flesh out `support_level` frontmatter.
77 lines
3.8 KiB
Markdown
77 lines
3.8 KiB
Markdown
---
|
|
title: Integrate with Home Assistant
|
|
sidebar_label: Home Assistant
|
|
support_level: community
|
|
---
|
|
|
|
## What is Home Assistant
|
|
|
|
> Open source home automation that puts local control and privacy first. Powered by a worldwide community of tinkerers and DIY enthusiasts. Perfect to run on a Raspberry Pi or a local server.
|
|
>
|
|
> -- https://www.home-assistant.io/
|
|
|
|
:::caution
|
|
You might run into CSRF errors, this is caused by a technology Home-assistant uses and not authentik, see [this GitHub issue](https://github.com/goauthentik/authentik/issues/884#issuecomment-851542477).
|
|
:::
|
|
:::caution
|
|
Only prefixes starting with `/auth` need to be proxied (excluding prefixes starting with `/auth/token`), see [this GitHub issue](https://github.com/BeryJu/hass-auth-header/issues/212). This can be configured in the reverse proxy (e.g. nginx, Traefik) or in authentik Provider's **Unauthorized Paths**.
|
|
:::
|
|
:::note
|
|
For Home Assistant to work with authentik, a custom integration needs to be installed for Home Assistant.
|
|
:::
|
|
|
|
## Preparation
|
|
|
|
The following placeholders are used in this guide:
|
|
|
|
- `hass.company` is the FQDN of the Home Assistant installation.
|
|
- `authentik.company` is the FQDN of the authentik installation.
|
|
|
|
:::note
|
|
This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application.
|
|
:::
|
|
|
|
## authentik configuration
|
|
|
|
1. Create a **Proxy Provider** under **Applications** > **Providers** using the following settings:
|
|
|
|
- **Name**: Home Assistant
|
|
- **Authentication flow**: default-authentication-flow
|
|
- **Authorization flow**: default-provider-authorization-explicit-consent
|
|
- **External Host**: Set this to the external URL you will be accessing Home Assistant from
|
|
- **Internal Host**: `http://hass.company:8123`
|
|
|
|
2. Create an **Application** under **Applications** > **Applications** using the following settings:
|
|
|
|
- **Name**: Home Assistant
|
|
- **Slug**: homeassistant
|
|
- **Provider**: Home Assistant (the provider you created in step 1)
|
|
|
|
3. Create an outpost deployment for the provider you've created above, as described [here](https://docs.goauthentik.io/docs/add-secure-apps/outposts/index.md). Deploy this Outpost either on the same host or a different host that can access Home Assistant. The outpost will connect to authentik and configure itself.
|
|
|
|
## Home Assistant configuration
|
|
|
|
1. Configure [trusted_proxies](https://www.home-assistant.io/integrations/http/#trusted_proxies) for the HTTP integration with the IP(s) of the Host(s) authentik is running on.
|
|
2. If you don't already have it set up, https://github.com/BeryJu/hass-auth-header, using the installation guide.
|
|
3. There are two ways to configure the custom component.
|
|
1. To match on the user's authentik username, use the following configuration:
|
|
```yaml
|
|
auth_header:
|
|
username_header: X-authentik-username
|
|
```
|
|
2. Alternatively, you can associate an existing Home Assistant username to an authentik username.
|
|
1. Within authentik, navigate to **Directory** > **Users**.
|
|
2. Select **Edit** for the user then add the following configuration to the **Attributes** section. Be sure to replace `hassusername` with the Home Assistant username.
|
|
:::note
|
|
This configuration will add an additional header for the authentik user which will contain the Home Assistant username and allow Home Assistant to authenticate based on that.
|
|
:::
|
|
```yaml
|
|
additionalHeaders:
|
|
X-ak-hass-user: hassusername
|
|
```
|
|
3. Then configure the Home Assistant custom component to use this header:
|
|
```yaml
|
|
auth_header:
|
|
username_header: X-ak-hass-user
|
|
```
|