From 819b3fb679cb5f8978a4fce55188f8da2ede9393 Mon Sep 17 00:00:00 2001 From: Niklas Richter Date: Mon, 27 Apr 2026 15:23:30 +0200 Subject: [PATCH] Add Keycloak configuration guide and refine setup instructions (#291) Added a comprehensive guide for configuring Keycloak integration with Home Assistant, including installation, configuration steps, and necessary mappers. --- docs/configuration.md | 1 + docs/provider-configurations/keycloak.md | 77 ++++++++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 docs/provider-configurations/keycloak.md diff --git a/docs/configuration.md b/docs/configuration.md index 1cf6db5..2be6aab 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -26,6 +26,7 @@ Here are some documentation links for specific providers that you may want to fo * [Kanidm](./provider-configurations/kanidm.md) * [Microsoft Entra ID](./provider-configurations/microsoft-entra.md) * [Zitadel](./provider-configurations/zitadel.md) +* [Keycloak](./provider-configurations/keycloak.md) _Missing a provider? Submit your guide using a PR._ diff --git a/docs/provider-configurations/keycloak.md b/docs/provider-configurations/keycloak.md new file mode 100644 index 0000000..b2ef00b --- /dev/null +++ b/docs/provider-configurations/keycloak.md @@ -0,0 +1,77 @@ +# Keycloak + + +## Step 1. Install the integration + +Make sure that you have fully installed the latest release of the integration. The easiest way to install the integration is through [the Home Assistant Community Store (HACS)](https://hacs.xyz/). + +After installing HACS, search for "OpenID Connect" in the HACS search box or click the button below: + +[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=christiaangoossens&repository=hass-oidc-auth&category=Integration) + +## Step 2. Configure Keycloak + +1. Log in to your Keycloak Admin Console and select the Realm you want to use. +2. Navigate to **Clients** and click **Create client**. + * **Client ID**: `homeassistant` (or a name of your choice). + * **Client Authentication**: Turn **ON** if you want to use a Client Secret (Confidential Client), or leave **OFF** for a Public Client. + * **Valid redirect URIs**: `https:///auth/oidc/callback` + * Save the client. If you enabled Client Authentication, go to the **Credentials** tab and copy your **Client Secret**. + +*(If you are using the UI configuration in Home Assistant, you can stop here and proceed to Step 3. Group and role mapping is only supported via `configuration.yaml`.)* + +3. Navigate to **Groups** and create the groups you want to use for Home Assistant access. + * Example: `homeassistant` (for standard users) and `homeassistantadmin` (for administrators). + * Assign your users to these groups. + +### Step 2.1 Configure the Group Mapper (YAML only) + +By default, Keycloak does not send a user's groups in the OIDC token in a format that Home Assistant expects. You must create a specific mapper: + +> [!NOTE] +> If you name the scope something other than `groups`, you have to set `claims.groups` to the correct name and `groups_scope` to the new name in your Home Assistant configuration. + +1. In Keycloak, go to **Client Scopes**. Create a dedicated scope `groups` and assign it to your `homeassistant` client as a Default Scope. +2. Click into the scope and go to the **Mappers** tab. +3. Click **Configure a new mapper** (or Add mapper -> By configuration) and select **Group Membership**. +4. Configure the mapper exactly as follows: + * **Name**: `groups` + * **Token Claim Name**: `groups` + * **Full group path**: **OFF** *(Important: This ensures Home Assistant receives `homeassistant` instead of the full path `/users/homeassistant`, if you use nested groups)*. + * **Add to ID token**: **ON** + * **Add to access token**: **ON** + * **Add to userinfo**: **ON** +5. Save the mapper. + +## Step 3. Home Assistant Configuration + +You can configure this via the UI, or by using `configuration.yaml`. + +### Option A: Configuration via UI (Simple) + +The UI flow is the easiest way to get started. Note that the UI does not currently offer group/role customization for OpenID Connect (SSO), so the group mapper setup from Keycloak is not needed. + +1. Go to **Settings** -> **Devices & Services** in Home Assistant. +2. Click **Add Integration** and search for **OpenID Connect**. +3. As OIDC Provider select **OpenID Connect (SSO)**. +4. Follow the UI flow and enter the following details: + * **Discovery URL**: `https:///realms//.well-known/openid-configuration` + * **Client ID**: The Client ID you created in Keycloak (e.g., `homeassistant`). + * **Client Secret**: The Client Secret from Keycloak (if Client Authentication was enabled). +5. Finish the setup in the UI. + +### Option B: Configuration via `configuration.yaml` (Advanced / Group Mapping) + +Here is the minimal `configuration.yaml` setup for Keycloak if you want to use group-based role mapping: + +```yaml +auth_oidc: + client_id: "homeassistant" + client_secret: !secret oidc_client_secret # Remove this line if Client Authentication is OFF in Keycloak + discovery_url: "https:///realms//.well-known/openid-configuration" + + roles: + # These must exactly match the group names you created in Keycloak + user: homeassistant + admin: homeassistantadmin +```