docs(kanidm): add kanidm.md (#69)

2025-06-15 13:54:43 +03:00
parent 881a6cb0be
commit fbc47d11ef
1 changed files with 145 additions and 0 deletions
--- a/docs/provider-configurations/kanidm.md
+++ b/docs/provider-configurations/kanidm.md
@@ -0,0 +1,145 @@
+# Kanidm
+
+## Public client configuration
+
+[Home Assistant](https://github.com/home-assistant/core) `/var/lib/hass/configuration.yaml`
+
+```yaml
+auth_oidc:
+  client_id: "homeassistant"
+  discovery_url: "https://idm.example.org/oauth2/openid/homeassistant/.well-known/openid-configuration"
+  features:
+    automatic_person_creation: true
+  id_token_signing_alg: "ES256"
+  roles:
+    admin: "homeassistant_admins@idm.example.org"
+    user: "idm_all_persons@idm.example.org"
+```
+
+[Kanidm](https://github.com/kanidm/kanidm)
+
+1. Create your Kanidm account, if you don't have one already:
+
+```shell
+kanidm person create "your_username" "Your Username" --name "idm_admin"
+```
+
+2. Create a new Kanidm group for your HomeAssistant administrators (`homeassistant_admins`), and add your regular account to it:
+
+```shell
+kanidm group create "homeassistant_admins" --name "idm_admin"
+kanidm group add-members "homeassistant_admins" "your_username" --name "idm_admin"
+```
+
+3. Create a new OAuth2 application configuration in Kanidm (`homeassistant`), configure the redirect URL, and scope access:
+
+```shell
+kanidm system oauth2 create-public "homeassistant" "Home Assistant" "https://hass.example.org/auth/oidc/welcome" --name "idm_admin"
+kanidm system oauth2 add-redirect-url "homeassistant" "https://hass.example.org/auth/oidc/callback" --name "idm_admin"
+kanidm system oauth2 update-scope-map "homeassistant" "homeassistant_users" "email" "groups" "openid" "profile" --name "idm_admin"
+```
+
+[Kanidm Provision](https://github.com/oddlama/kanidm-provision) `state.json`
+
+```jsonc
+{
+  "groups": {
+    "homeassistant_admins": {
+      "members": ["your_username"]
+    }
+  },
+  "persons": {
+    "your_username": {
+      "displayName": "Your Username"
+    },
+  },
+  "systems": {
+    "oauth2": {
+      "homeassistant": {
+        "displayName": "Home Assistant",
+        "originLanding": "https://hass.example.org/auth/oidc/welcome",
+        "originUrl": "https://hass.example.org/auth/oidc/callback",
+        "public": true,
+        "scopeMaps": {
+          "homeassistant_users": ["email", "groups", "openid", "profile"]
+        }
+      }
+    }
+  }
+}
+```
+
+## Confidential client configuration
+
+[Home Assistant](https://github.com/home-assistant/core) `/var/lib/hass/configuration.yaml`
+
+```yaml
+auth_oidc:
+  client_id: "homeassistant"
+  client_secret: !secret oidc_client_secret
+  discovery_url: "https://idm.example.org/oauth2/openid/homeassistant/.well-known/openid-configuration"
+  features:
+    automatic_person_creation: true
+  id_token_signing_alg: "ES256"
+  roles:
+    admin: "homeassistant_admins@idm.example.org"
+    user: "idm_all_persons@idm.example.org"
+```
+
+[Kanidm](https://github.com/kanidm/kanidm)
+
+1. Create your Kanidm account, if you don't have one already:
+
+```shell
+kanidm person create "your_username" "Your Username" --name "idm_admin"
+```
+
+2. Create a new Kanidm group for your HomeAssistant administrators (`homeassistant_admins`), and add your regular account to it:
+
+```shell
+kanidm group create "homeassistant_admins" --name "idm_admin"
+kanidm group add-members "homeassistant_admins" "your_username" --name "idm_admin"
+```
+
+3. Create a new OAuth2 application configuration in Kanidm (`homeassistant`), configure the redirect URL, and scope access:
+
+```shell
+kanidm system oauth2 create "homeassistant" "Home Assistant" "https://hass.example.org/auth/oidc/welcome" --name "idm_admin"
+kanidm system oauth2 add-redirect-url "homeassistant" "https://hass.example.org/auth/oidc/callback" --name "idm_admin"
+kanidm system oauth2 update-scope-map "homeassistant" "homeassistant_users" "email" "groups" "openid" "profile" --name "idm_admin"
+```
+
+4. Get the `homeassistant` OAuth2 client secret from Kanidm:
+
+```shell
+kanidm system oauth2 show-basic-secret "homeassistant" --name "idm_admin" | xargs echo 'oidc_client_secret: {}' | tee --append "/var/lib/hass/secrets.yaml"
+```
+
+[Kanidm Provision](https://github.com/oddlama/kanidm-provision) `state.json`
+
+```jsonc
+{
+  "groups": {
+    "homeassistant_admins": {
+      "members": ["your_username"]
+    }
+  },
+  "persons": {
+    "your_username": {
+      "displayName": "Your Username"
+    },
+  },
+  "systems": {
+    "oauth2": {
+      "homeassistant": {
+        "displayName": "Home Assistant",
+        "originLanding": "https://hass.example.org/auth/oidc/welcome",
+        "originUrl": "https://hass.example.org/auth/oidc/callback",
+        "scopeMaps": {
+          "homeassistant_users": ["email", "groups", "openid", "profile"]
+        }
+      }
+    }
+  }
+}
+```