diff --git a/README.md b/README.md index 66e7e4d..f2a9b70 100644 --- a/README.md +++ b/README.md @@ -61,13 +61,13 @@ After installing HACS, search for "OpenID Connect" in the HACS search box or cli [![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) -Next, setup your OIDC provider. You can find setup guides for common providers here: +Next, set up your OIDC provider. You can find setup guides for common providers here: | | | | |:-----------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------:| | [authentik](./docs/provider-configurations/authentik.md) | [Authelia](./docs/provider-configurations/authelia.md) | [Pocket ID](./docs/provider-configurations/pocket-id.md) | -You can also find additional provider guides in the [the Provider Configurations folder](./docs/provider-configurations). If your provider isn't specified, you can use either a **public client** (recommended) or **confidential client** with the callback url set to `/auth/oidc/callback`. +You can also find additional provider guides in the [the Provider Configurations folder](./docs/provider-configurations). If your provider isn't specified, you can use either a **public client** (recommended) or **confidential client** with the callback URL set to `/auth/oidc/callback`. Finally, choose your preferred configuration style (UI or YAML). After configuration, you should automatically be sent to the OIDC login page(s) if you open Home Assistant (web or app). @@ -86,13 +86,13 @@ Many configuration options are available through this method, but some advanced Alternatively, you can configure the integration using YAML. You can find a full configuration guide for YAML here: [YAML Configuration Guide](./docs/configuration.md). ## Contributions -Contibutions are very welcome! If you program in Python or have worked with Home Assistant integrations before, please try to contribute. You can find more information in the [Contribution Guide](./CONTRIBUTING.md). +Contributions are very welcome! If you program in Python or have worked with Home Assistant integrations before, please try to contribute. You can find more information in the [Contribution Guide](./CONTRIBUTING.md). ### Security issue? -Please see [SECURITY.md](./SECURITY.md) for more information on how to submit your security issue securely. You can find previously found vulnerablities and their corresponding security advisories at the [Security Advisories page](https://github.com/christiaangoossens/hass-oidc-auth/security/advisories). +Please see [SECURITY.md](./SECURITY.md) for more information on how to submit your security issue securely. You can find previously found vulnerabilities and their corresponding security advisories at the [Security Advisories page](https://github.com/christiaangoossens/hass-oidc-auth/security/advisories). ## Background -If you would like to read the background/open letter that lead to this component, you can find it at https://github.com/orgs/home-assistant/discussions/48. It is currently one of the most upvoted feature requests for Home Assistant. +If you would like to read the background/open letter that led to this component, you can find it at https://github.com/orgs/home-assistant/discussions/48. It is currently one of the most upvoted feature requests for Home Assistant. ## License Distributed under the MIT license with no warranty. You are fully liable for configuring this integration correctly to keep your Home Assistant installation secure. Use at your own risk. The full license can be found in [LICENSE.md](./LICENSE.md) @@ -109,4 +109,4 @@ Distributed under the MIT license with no warranty. You are fully liable for con [issues-shield]: https://img.shields.io/github/issues/christiaangoossens/hass-oidc-auth.svg?style=for-the-badge [issues-url]: https://github.com/christiaangoossens/hass-oidc-auth/issues [license-shield]: https://img.shields.io/github/license/christiaangoossens/hass-oidc-auth.svg?style=for-the-badge -[license-url]: https://github.com/christiaangoossens/hass-oidc-auth/blob/master/LICENSE.txt +[license-url]: https://github.com/christiaangoossens/hass-oidc-auth/blob/master/LICENSE.md diff --git a/docs/configuration.md b/docs/configuration.md index 66a7b5b..33245cd 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,7 +4,7 @@ If you want to use the (limited) UI configuration method, please see [the README # YAML Configuration -You can configure this integration using YAML in your `configuration.yaml` file. All features of the integrations will always be available within the YAML configuration. +You can configure this integration using YAML in your `configuration.yaml` file. All features of the integration will always be available within the YAML configuration. By default, only two fields are required: @@ -14,7 +14,7 @@ auth_oidc: 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 its discovery URL (ending in `.well-known/openid-configuration`). You don't have to configure other settings in most cases, as they have secure defaults set. If your provider requires manually configuring the callback URL, use `/auth/oidc/callback`. ## Provider Configurations @@ -89,7 +89,7 @@ auth_oidc: ### Disabling registration for new users This integration does not allow disabling registration for new users, as there is no way to abort registration that late in the process while providing a good user experience. -You can however set both roles to groups that only contain certain users or to a non-existant group. +You can however set both roles to groups that only contain certain users or to a non-existent group. ```yaml auth_oidc: @@ -154,7 +154,7 @@ Here's a table of all options that you can set: | `discovery_url` | `string` | Yes | | The OIDC well-known configuration URL. | | `display_name` | `string` | No | `"OpenID Connect (SSO)"` | The name to display on the login screen, both for the Home Assistant screen and the OIDC welcome screen. | | `id_token_signing_alg` | `string` | No | `RS256` | The signing algorithm that is used for your id_tokens. -| `groups_scope` | `string` | No | `groups` | Override the default grups scope with another scope of your choice. | +| `groups_scope` | `string` | No | `groups` | Override the default groups scope with another scope of your choice. | | `additional_scopes`|`list of strings`| No | `empty list` | Add additional scopes to request for custom identity provider configurations in addition to the automatic `openid` and `profile` scopes and the `groups_scope` configuration option | | `features.automatic_user_linking` | `boolean`| No | `false` | Automatically links users to existing Home Assistant users based on the OIDC username claim. Disabled by default for security. When disabled, OIDC users will get their own new user profile upon first login. | | `features.automatic_person_creation` | `boolean` | No | `true` | Automatically creates a person entry for new user profiles created by this integration. Recommended if you would like to assign presence detection to OIDC users. | @@ -166,5 +166,5 @@ Here's a table of all options that you can set: | `claims.groups` | `string` | No | `groups` | The claim to use to obtain the user's group(s). | | `roles.admin` | `string` | No | `admins` | Group name to require for users to get the 'admin' role in Home Assistant. Defaults to 'admins', the default group name for admins in Authentik. Doesn't do anything if no groups claim is found in your token. | | `roles.user` | `string` | No | | Group name to require for users to get the 'user' role in Home Assistant. Defaults to giving all users this role, unless configured. | -| `network.tls_verify` | `boolean` | No | `true` | Verify TLS certificate. You may want to set this set to `false` when testing locally. | +| `network.tls_verify` | `boolean` | No | `true` | Verify TLS certificate. You may want to set this to `false` when testing locally. | | `network.tls_ca_path` | `string` | No | | Path to file containing a private certificate authority chain. | diff --git a/docs/faq.md b/docs/faq.md index 4b2c2d5..31006a4 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,7 +14,7 @@ The core values for this integration are: ## Is the integration stable? -Yes, this integration has been tested in production environments for multiple years and has almost full automated test coverage to test both security and regressions. Security issues as well as dependency updates are actively monitored through automated pipelines and [a security policy is available here](./SECURITY.md). +Yes, this integration has been tested in production environments for multiple years and has almost full automated test coverage to test both security and regressions. Security issues as well as dependency updates are actively monitored through automated pipelines and [a security policy is available here](../SECURITY.md). ## What does this integration not do (yet)?