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>
6.8 KiB
title, sidebar_label, support_level
| title | sidebar_label | support_level |
|---|---|---|
| Integrate with Home Assistant | Home Assistant | 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.
:::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.companyis the FQDN of the Home Assistant installation.authentik.companyis 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" } ]}>
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
-
Log in to authentik as an administrator and open the authentik Admin interface.
-
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
- Strict:
-
Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's My applications page.
-
-
Click Submit to save the new application and provider.
Home Assistant configuration
- Install hass-openid following the instructions at https://github.com/cavefire/hass-openid
- To support the integration of Home Assistant with authentik, you'll need to update the
configuration.yamlfile of your Home Assistant deployment:
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
- 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.
:::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. :::
:::caution
Only prefixes starting with /auth need to be proxied (excluding prefixes starting with /auth/token). See this GitHub issue. 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
-
Log in to authentik as an administrator and open the authentik Admin interface.
-
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 (policy, group, or user) to manage the listing and access to applications on a user's My applications page.
-
-
Click Submit to save the new application and provider.
-
Create an outpost deployment for the provider you've created above, as described here. 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
- Configure trusted_proxies for the HTTP integration with the IP(s) of the Host(s) authentik is running on.
- If you don't already have it set up, install hass-auth-header using the installation guide.
- 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:
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.
- Within authentik, navigate to Directory > Users.
- Select Edit for the user then add the following configuration to the Attributes section. Be sure to replace
hassusernamewith 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. :::
additionalHeaders:
X-ak-hass-user: hassusername
- Then configure the Home Assistant custom component to use this header:
auth_header:
username_header: X-ak-hass-user