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

chore: use 2 space yaml (#61)

Browse Source 
and make clear that other id token signing algs are possible
This commit is contained in:
Merlijn
2025-04-04 11:56:51 +02:00
committed by GitHub
parent 178cd4df49
commit 881a6cb0be
2 changed files with 29 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
docs/configuration.md
View File

@@ -7,8 +7,8 @@ For now, this integration is configured using YAML in your `configuration.yaml`
```yaml ```yaml
auth_oidc: auth_oidc:
client_id: "" client_id: ""
discovery_url: "" discovery_url: ""
``` ```
The default settings assume that you configure Home Assistant as a **public client**, without a client secret. If so, you should only need to provide the `client_id` from your OIDC provider and it's discovery URL (ending in `.well-known/openid-configuration`). The default settings assume that you configure Home Assistant as a **public client**, without a client secret. If so, you should only need to provide the `client_id` from your OIDC provider and it's discovery URL (ending in `.well-known/openid-configuration`).
@@ -30,9 +30,9 @@ If you want to configure Home Assistant as a **confidential client**, you should
```yaml ```yaml
auth_oidc: auth_oidc:
client_id: "" client_id: ""
client_secret: !secret oidc_client_secret client_secret: !secret oidc_client_secret
discovery_url: "" discovery_url: ""
``` ```
You should use the Home Assistant secrets helper (`!secret`) to make sure you store secrets securely. See https://www.home-assistant.io/docs/configuration/secrets/ for more information. You should use the Home Assistant secrets helper (`!secret`) to make sure you store secrets securely. See https://www.home-assistant.io/docs/configuration/secrets/ for more information.
@@ -46,17 +46,17 @@ If your provider isn't listed above, you might want to configure OIDC settings y
```yaml ```yaml
auth_oidc: auth_oidc:
client_id: "" client_id: ""
discovery_url: "" discovery_url: ""
id_token_signing_alg: <HS256 or RS256> id_token_signing_alg: <HS256, RS256, ES256, ...>
groups_scope: <groups scope> groups_scope: <groups scope>
claims: claims:
display_name: <display name claim from your provider> display_name: <display name claim from your provider>
username: <username claim from your provider> username: <username claim from your provider>
groups: <groups claim from your provider> groups: <groups claim from your provider>
roles: roles:
admin: <group name to use for admins> admin: <group name to use for admins>
user: <group name to use for users> user: <group name to use for users>
``` ```
If you configure the user role, OIDC users that have neither configured group name will be rejected! If you configure the admin role, users with that role will receive administrator rights in Home Assistant automatically upon login. If you configure the user role, OIDC users that have neither configured group name will be rejected! If you configure the admin role, users with that role will receive administrator rights in Home Assistant automatically upon login.
@@ -66,9 +66,9 @@ If you would like to change the default name on the OIDC welcome screen and Home
```yaml ```yaml
auth_oidc: auth_oidc:
client_id: "" client_id: ""
discovery_url: "" discovery_url: ""
display_name: "Example" display_name: "Example"
``` ```
This will show the provider on the login screen as: "Login with Example". This will show the provider on the login screen as: "Login with Example".
@@ -78,10 +78,10 @@ If you already have users created within Home Assistant and would like to re-use
```yaml ```yaml
auth_oidc: auth_oidc:
client_id: "someValueForTheClientId" client_id: "someValueForTheClientId"
discovery_url: "https://example.com/application/o/application/.well-known/openid-configuration" discovery_url: "https://example.com/application/o/application/.well-known/openid-configuration"
features: features:
automatic_user_linking: true automatic_user_linking: true
``` ```
Upon login, OIDC users will then automatically be linked to the HA user with the same username. It's recommended to **only enable this temporarily** as it may pose a security risk. You should disable it after linking all your users, as existing links will still work if you disable it, but no new links will be created. Upon login, OIDC users will then automatically be linked to the HA user with the same username. It's recommended to **only enable this temporarily** as it may pose a security risk. You should disable it after linking all your users, as existing links will still work if you disable it, but no new links will be created.
@@ -99,16 +99,16 @@ You can either make the CA known to the entire operating system or configure onl
```yaml ```yaml
auth_oidc: auth_oidc:
network: network:
tls_ca_path: /path/to/private-ca.pem tls_ca_path: /path/to/private-ca.pem
``` ```
If you want to deactivate the validation of all TLS certificates for test purposes, you can do this via `network.tls_verify: false`: If you want to deactivate the validation of all TLS certificates for test purposes, you can do this via `network.tls_verify: false`:
```yaml ```yaml
auth_oidc: auth_oidc:
network: network:
tls_verify: false tls_verify: false
``` ```
> [!CAUTION] > [!CAUTION]

4
docs/usage.md
View File

@@ -19,8 +19,8 @@ By default, the integration assumes you configure Home Assistant as a **public c
```yaml ```yaml
auth_oidc: auth_oidc:
client_id: "example" client_id: "example"
discovery_url: "https://example.com/.well-known/openid-configuration" discovery_url: "https://example.com/.well-known/openid-configuration"
``` ```
When registering Home Assistant at your OIDC provider, use `<your HA URL>/auth/oidc/callback` as the callback URL and select 'public client'. You should now get the `client_id` and `issuer_url` or `discovery_url` to fill in. When registering Home Assistant at your OIDC provider, use `<your HA URL>/auth/oidc/callback` as the callback URL and select 'public client'. You should now get the `client_id` and `issuer_url` or `discovery_url` to fill in.