mirror of
https://github.com/goauthentik/authentik
synced 2026-04-28 02:18:11 +02:00
6ed5cb5249
* website/integrations: rename "Create with Provider" to "New Application" The application list page now uses a split-button labeled "New Application" instead of the old "Create with Provider" dropdown. Update all 113 integration guides to match. * website/docs: update flow, stage, and policy button labels - "Create" → "New Flow", "New Stage", "New Policy" for trigger buttons - "Finish" → "Create Flow", "Create Stage", "Create Policy" for submit - "Create and bind stage" → "New Stage" / "Bind Existing Stage" - "Create" (binding submit) → "Create Stage Binding" * website/docs: update provider button labels - "Create" → "New Provider" for trigger buttons - "Create with Provider" → "New Application" in RAC docs - "Create" → "New Property Mapping", "New RAC Endpoint", "New Prompt" for related entity creation * website/docs: update directory button labels - "Create" → "New Source" for federation/social login pages - "Create" → "New Role", submit → "Create Role" - "Create" → "New Invitation" - Policy binding submit → "Create Policy Binding" * website/docs: update endpoint device and system management button labels - "Create" → "New Endpoint Connector", "New Enrollment Token", "New Device Access Group", "New Flow" - Submit → "Create Device Access Group" - "Create" → "New Notification Rule", "New Notification Transport" - Binding submit → "Create Policy Binding" * Reorganize policy documentation * website/docs: address policy docs review feedback * post-rebase * website/docs: Reorganize policy documentation -- Revisions (#21601) * apply suggestions * Fix escaped. * Fix whitespace. * Update button label. * Fix phrasing. * Fix phrasing. * Clean up stragglers. * Format. --------- Co-authored-by: Dominic R <dominic@sdko.org>
157 lines
6.8 KiB
Markdown
157 lines
6.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/
|
|
|
|
:::info
|
|
To integrate Home Assistant with authentik, a custom integration needs to be installed in 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.
|
|
|
|
:::info
|
|
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.
|
|
:::
|
|
|
|
## Configuration methods
|
|
|
|
It is possible to configure Home Assistant to use OIDC or a proxy provider for authentication. Below are the steps to configure each method.
|
|
|
|
import TabItem from "@theme/TabItem";
|
|
import Tabs from "@theme/Tabs";
|
|
|
|
<Tabs
|
|
defaultValue="oidc"
|
|
values={[
|
|
{ label: "OIDC", value: "oidc" },
|
|
{ label: "Proxy Provider", value: "proxy" }
|
|
]}>
|
|
<TabItem value="oidc">
|
|
|
|
## authentik configuration
|
|
|
|
To support the integration of Home Assistant with authentik, you need to create an application/provider pair in authentik.
|
|
|
|
### Create an application and provider in authentik
|
|
|
|
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
|
2. Navigate to **Applications** > **Applications** and click **New Application** to open the application wizard.
|
|
- **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
|
|
- **Choose a Provider type**: select **OAuth2/OpenID** as the provider type.
|
|
- Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later.
|
|
- **Signing Key**: Select any available signing key.
|
|
- **Redirect URIs**:
|
|
- Strict: `http://hass.company:8123/auth/openid/callback`
|
|
|
|
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
|
|
|
3. Click **Submit** to save the new application and provider.
|
|
|
|
## Home Assistant configuration
|
|
|
|
1. Install hass-openid following the instructions at https://github.com/cavefire/hass-openid
|
|
2. To support the integration of Home Assistant with authentik, you'll need to update the `configuration.yaml` file of your Home Assistant deployment:
|
|
|
|
```yaml showLineNumbers title="/config/configuration.yaml"
|
|
openid:
|
|
client_id: <authentik_client_ID>
|
|
client_secret: <authentik_client_secret>
|
|
configure_url: "https://authentik.company/application/o/<application_slug>/.well-known/openid-configuration"
|
|
scope: "openid profile email"
|
|
username_field: "preferred_username"
|
|
block_login: false
|
|
```
|
|
|
|
3. Restart Home Assistant
|
|
|
|
:::info
|
|
You must create OIDC users in Home Assistant before they can log in using OIDC.
|
|
:::
|
|
|
|
## Configuration verification
|
|
|
|
To verify the integration with Home Assistant, log out and attempt to log back in using the **OpenID/OAuth2 authentication** button. You should be redirected to the authentik login page. Once authenticated, you should be redirected to the Home Assistant dashboard.
|
|
|
|
</TabItem>
|
|
<TabItem value="proxy">
|
|
|
|
:::caution
|
|
Using a proxy provider might produce CSRF errors. This is caused by a technology that Home Assistant uses and not authentik. For more information 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**.
|
|
:::
|
|
|
|
## authentik configuration
|
|
|
|
To support the integration of Home Assistant using `hass-auth-headers` with authentik, you need to create an application/provider pair in authentik.
|
|
|
|
### Create an application and provider in authentik
|
|
|
|
1. Log in to authentik as an administrator and open the authentik Admin interface.
|
|
2. Navigate to **Applications** > **Applications** and click **New Application** to open the application wizard.
|
|
- **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
|
|
- **Choose a Provider type**: select **Proxy** as the provider type.
|
|
- **External Host**: Set this to the external URL you will be accessing Home Assistant from.
|
|
- **Internal Host**: `http://hass.company:8123`
|
|
|
|
- **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
|
|
|
|
3. Click **Submit** to save the new application and provider.
|
|
|
|
4. Create an outpost deployment for the provider you've created above, as described [here](https://docs.goauthentik.io/docs/add-secure-apps/outposts/). 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, install [hass-auth-header](https://github.com/BeryJu/hass-auth-header) using the installation guide.
|
|
3. There are two ways to configure the custom component:
|
|
|
|
### Match on user's authentik username
|
|
|
|
To match on the user's authentik username, use the following configuration:
|
|
|
|
```yaml
|
|
auth_header:
|
|
username_header: X-authentik-username
|
|
```
|
|
|
|
### Associate existing Home Assistant username
|
|
|
|
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.
|
|
|
|
:::info
|
|
This configuration adds an extra header for the authentik user, containing the Home Assistant username, which allows Home Assistant to authenticate the user accordingly.
|
|
:::
|
|
|
|
```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
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|