hass-oidc-auth/docs/provider-configurations/keycloak.md

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).

After installing HACS, search for "OpenID Connect" in the HACS search box or click the button below:

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:

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