public/hass-oidc-auth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Keycloak configuration guide and refine setup instructions (#291)

Browse Source 
Added a comprehensive guide for configuring Keycloak integration with Home Assistant, including installation, configuration steps, and necessary mappers.
This commit is contained in:
Niklas Richter
2026-04-27 15:23:30 +02:00
committed by GitHub
parent 8205c846f6
commit 819b3fb679
2 changed files with 78 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/provider-configurations/keycloak.md Normal file
View File

@@ -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://<your HA URL>/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://<your-keycloak-domain>/realms/<your-realm>/.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://<your-keycloak-domain>/realms/<your-realm>/.well-known/openid-configuration"
roles:
# These must exactly match the group names you created in Keycloak
user: homeassistant
admin: homeassistantadmin
```