- 
+ 
OpenID Connect for Home Assistant
@@ -81,6 +81,8 @@ Many configuration options are available through this method, but some advanced
2. Click Add Integration and select **OpenID Connect/SSO Authentication**.
3. Follow the prompts on screen carefully.
+
+
### Configuration by YAML
Alternatively, you can configure the integration using YAML. You can find a full configuration guide for YAML here: [YAML Configuration Guide](./docs/configuration.md).
diff --git a/logo.png b/docs/logo.png
similarity index 100%
rename from logo.png
rename to docs/logo.png
diff --git a/docs/provider-configurations/authelia.md b/docs/provider-configurations/authelia.md
index 5612729..cae2646 100644
--- a/docs/provider-configurations/authelia.md
+++ b/docs/provider-configurations/authelia.md
@@ -1,6 +1,22 @@
# Authelia
-## Public client configuration
+> [!TIP]
+> This guide describes configuring Authelia using the UI method. You can also configure Authelia by hand with YAML. Instructions for configuring any provider using YAML can be found here: [YAML Configuration Guide](../configuration.md).
+
+
+## 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/). You can find usage instructions for HACS here: https://hacs.xyz/docs/use/.
+
+After installing HACS, search for "OpenID Connect" in the HACS search box or click the button below:
+
+[](https://my.home-assistant.io/redirect/hacs_repository/?owner=christiaangoossens&repository=hass-oidc-auth&category=Integration)
+
+## Step 2. Configure Authelia
+
+You can choose between configuring Authelia as a public or confidential client.
+
+### Public client configuration
> [!NOTE]
> This configuration strictly requires a HTTPS redirect uri.
@@ -17,24 +33,11 @@ identity_providers:
public: true
require_pkce: true
pkce_challenge_method: 'S256'
- authorization_policy: 'two_factor'
redirect_uris:
- 'https://hass.example.com/auth/oidc/callback'
- scopes:
- - 'openid'
- - 'profile'
- - 'groups'
- id_token_signed_response_alg: 'RS256'
```
-Home Assistant `configuration.yaml`
-```yaml
-auth_oidc:
- client_id: "homeassistant"
- discovery_url: "https://auth.example.com/.well-known/openid-configuration"
-```
-
-## Confidential client configuration:
+### Confidential client configuration:
Authelia `configuration.yml`
```yaml
@@ -49,21 +52,43 @@ identity_providers:
public: false
require_pkce: true
pkce_challenge_method: 'S256'
- authorization_policy: 'two_factor'
redirect_uris:
- 'https://hass.example.com/auth/oidc/callback'
- scopes:
- - 'openid'
- - 'profile'
- - 'groups'
- id_token_signed_response_alg: 'RS256'
token_endpoint_auth_method: 'client_secret_post'
```
-Home Assistant `configuration.yaml`
-```yaml
-auth_oidc:
- client_id: "homeassistant"
- client_secret: "insecure_secret"
- discovery_url: "https://auth.example.com/.well-known/openid-configuration"
-```
+## Step 3. Home Assistant configuration
+
+The recommended setup method for beginners is through the "Integrations" panel within the Home Assistant UI. You can also use YAML setup, for which you can find the configuration guide here: [YAML Configuration Guide](../configuration.md).
+
+1. Open Home Assistant and go to **Settings -> Devices & Services**.
+2. Click Add Integration and select **OpenID Connect/SSO Authentication**.
+
+
+
+3. Now click "Authelia" and continue to the next screen
+4. Set the discovery URL to `https://
/.well-known/openid-configuration` and click **Submit**
+
+
+
+5. Your URL will be tested. You may see an error, such as the picture below. Check your URL and verify that Home Assistant can access your Authelia installation. Change the URL or retry.
+
+
+
+6. If your discovery URL is tested succesfully, you will see something like this and you can continue with the **Submit** button to continue.
+
+
+
+
+7. You will then be prompted to fill in the client details, the **Client ID** and the **Client Secret** (if you used the Public Client type in the Authelia configuration, there is no Client Secret required). Paste them in the relevant input boxes and continue setup with **Submit**.
+
+
+
+8. You will then be asked about **Groups & Role Configuration** and **User Linking**. Configure these options as you wish or leave the defaults in place. You can also change these settings later by opening the integration settings and clicking the reconfiguration icon.
+
+
+
+
+## Done!
+
+You should now automatically see the welcome screen upon opening your Home Assistant URL. On the welcome screen you can choose to either start login through SSO or to use an alternative login method, which will bring you back to the normal Home Assistant username/password login screen.
\ No newline at end of file
diff --git a/docs/provider-configurations/authentik.md b/docs/provider-configurations/authentik.md
index 60bb15c..c3cad69 100644
--- a/docs/provider-configurations/authentik.md
+++ b/docs/provider-configurations/authentik.md
@@ -1,40 +1,63 @@
-# Authentik
+# authentik
-## Public client configuration
-Under construction.
+> [!TIP]
+> This guide describes configuring authentik using the UI method. You can also configure authentik by hand with YAML. Instructions for configuring any provider using YAML can be found here: [YAML Configuration Guide](../configuration.md).
-## Confidential client configuration
-1. From the admin interface, go to `Applications > Providers` and click on `Create`
-2. Select `OAuth2/OpenID Provider` and click `Next`
-3. Fill the following details:
- - Name: `Home Assistant Provider`
- - Authorization flow: `default-provider-authorization-explicit-consent`
- - Client type: `Confidential`
- - Client ID: `homeassistant`
- - Client Secret: **Copy this value**
- - Redirect URIs/Origins: Click on `Add entry` (You can use either DNS, Internal/External IP or localhost)
- - Strict: https://hass.example.com/auth/oidc/callback
-4. Click `Finish` to save the provider configuration
-5. Open the created Provider
-6. On the Assigned to application section click on `Create`:
- - Name: `Home Assistant`
- - Slug: `home-assistant`
- - Provider: `Home Assistant Provider`
-
- Then save the configuration
+## Step 1. Install the integration
-## Home Assistant configuration
+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/). You can find usage instructions for HACS here: https://hacs.xyz/docs/use/.
-> [!IMPORTANT]
-> For HTTPS configuration make sure to have a public valid SSL certificate (i.e. LetsEncrypt), if not, use HTTP instead (more insecure) or add your Authentik CA certificate to `network.tls_ca_path`.
+After installing HACS, search for "OpenID Connect" in the HACS search box or click the button below:
-After installing this HACS addon, edit your `configuration.yaml` file and add:
-```yaml
-auth_oidc:
- client_id: "homeassistant"
- client_secret: "client_secret"
- discovery_url: "https://auth.example.com/application/o/home-assistant/.well-known/openid-configuration"
-```
+[](https://my.home-assistant.io/redirect/hacs_repository/?owner=christiaangoossens&repository=hass-oidc-auth&category=Integration)
-Restart Home Assistant and go to https://hass.example.com/auth/oidc/welcome
\ No newline at end of file
+## Step 2. Configure authentik
+
+1. Log in to authentik as an administrator and open the authentik Admin interface.
+
+2. Navigate to **Applications > Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.)
+
+ - **Application**: provide a descriptive name, an optional group for the type of application, the policy engine mode, and optional UI settings.
+ - Choose a **Provider Type**: select **OAuth2/OpenID Connect** as the provider type.
+ - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations.
+ - Note the **Client ID**, **Client Secret**, and **slug** values because they will be required later.
+ - Set a `Strict` redirect URI to `https:///auth/oidc/callback`.
+ - Select any available signing key (to use the RS256 `id_token_signing_alg`)
+ - Configure Bindings (optional): you can create a binding (policy, group, or user) to manage the listing and access to applications on a user's **My applications** page.
+
+## Step 3. Home Assistant configuration
+
+The recommended setup method for beginners is through the "Integrations" panel within the Home Assistant UI. You can also use YAML setup, for which you can find the configuration guide here: [YAML Configuration Guide](../configuration.md).
+
+1. Open Home Assistant and go to **Settings -> Devices & Services**.
+2. Click Add Integration and select **OpenID Connect/SSO Authentication**.
+
+
+
+3. Now click "Authentik" and continue to the next screen
+4. Set the discovery URL to `https:///application/o//.well-known/openid-configuration` using the **slug** from the earlier authentik configuration step and click **Submit**
+
+
+
+5. Your URL will be tested. You may see an error, such as the picture below. Check your URL and verify that Home Assistant can access your authentik installation. Change the URL or retry.
+
+
+
+6. If your discovery URL is tested succesfully, you will see something like this and you can continue with the **Submit** button to continue.
+
+
+
+
+7. You will then be prompted to fill in the client details, the **Client ID** and the **Client Secret** (if you used the Public Client type in authentik, there is no Client Secret required). Paste them in the relevant input boxes and continue setup with **Submit**.
+
+
+
+8. You will then be asked about **Groups & Role Configuration** and **User Linking**. Configure these options as you wish or leave the defaults in place. You can also change these settings later by opening the integration settings and clicking the reconfiguration icon.
+
+
+
+
+## Done!
+
+You should now automatically see the welcome screen upon opening your Home Assistant URL. On the welcome screen you can choose to either start login through SSO or to use an alternative login method, which will bring you back to the normal Home Assistant username/password login screen.
\ No newline at end of file
diff --git a/docs/provider-configurations/pocket-id.md b/docs/provider-configurations/pocket-id.md
index 742d0f7..a26314b 100644
--- a/docs/provider-configurations/pocket-id.md
+++ b/docs/provider-configurations/pocket-id.md
@@ -1,8 +1,23 @@
# Pocket ID
-## Public client configuration
+> [!TIP]
+> This guide describes configuring Pocket ID using the UI method. You can also configure Pocket ID by hand with YAML. Instructions for configuring any provider using YAML can be found here: [YAML Configuration Guide](../configuration.md).
+
+
+## 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/). You can find usage instructions for HACS here: https://hacs.xyz/docs/use/.
+
+After installing HACS, search for "OpenID Connect" in the HACS search box or click the button below:
+
+[](https://my.home-assistant.io/redirect/hacs_repository/?owner=christiaangoossens&repository=hass-oidc-auth&category=Integration)
+
+## Step 2. Configure Pocket ID
+
+You can choose between configuring Pocket ID as a public or confidential client.
+
+### Public client configuration
-### Pocket ID configuration
1. Login to Pocket ID and go to `OIDC Clients`
2. Click on `Add OIDC Client`
@@ -16,19 +31,8 @@
5. Click on `Show more details` and note down your `Client ID` and `OIDC Discovery URL` since you will need them later.
-### Home Assistant configuration
-1. Add following configuration in Home Assistant's configuration.yaml:
-```yaml
-auth_oidc:
- client_id:
- discovery_url: (for example: https://id.example.com/.well-known/openid-configuration)
-```
+### Confidential client configuration:
-2. Restart Home Assistant and go to your Home Assistant OIDC URL (for example: https://hass.example.com/auth/oidc/welcome)
-
-## Confidential client configuration
-
-### Pocket ID configuration
1. Login to Pocket ID and go to `OIDC Clients`
2. Click on `Add OIDC Client`
@@ -43,16 +47,39 @@ auth_oidc:
- `Client ID`
- `Client secret`
- `OIDC Discovery URL`
-
-### Home Assistant configuration
-1. Add following configuration in Home Assistant's configuration.yaml:
-```yaml
-auth_oidc:
- client_id:
- client_secret:
- discovery_url: (for example: https://id.example.com/.well-known/openid-configuration)
-```
-2. Restart Home Assistant and go to your Home Assistant OIDC URL (for example: https://hass.example.com/auth/oidc/welcome)
+## Step 3. Home Assistant configuration
+
+The recommended setup method for beginners is through the "Integrations" panel within the Home Assistant UI. You can also use YAML setup, for which you can find the configuration guide here: [YAML Configuration Guide](../configuration.md).
+
+1. Open Home Assistant and go to **Settings -> Devices & Services**.
+2. Click Add Integration and select **OpenID Connect/SSO Authentication**.
+
+
+
+3. Now click "Pocket ID" and continue to the next screen
+4. Set the discovery URL to `https:///.well-known/openid-configuration` and click **Submit**
+
+
+
+5. Your URL will be tested. You may see an error, such as the picture below. Check your URL and verify that Home Assistant can access your Pocket ID installation. Change the URL or retry.
+
+
+
+6. If your discovery URL is tested succesfully, you will see something like this and you can continue with the **Submit** button to continue.
+
+
+7. You will then be prompted to fill in the client details, the **Client ID** and the **Client Secret** (if you used the Public Client type in the Pocket ID configuration, there is no Client Secret required). Paste them in the relevant input boxes and continue setup with **Submit**.
+
+
+
+8. You will then be asked about **Groups & Role Configuration** and **User Linking**. Configure these options as you wish or leave the defaults in place. You can also change these settings later by opening the integration settings and clicking the reconfiguration icon.
+
+
+
+
+## Done!
+
+You should now automatically see the welcome screen upon opening your Home Assistant URL. On the welcome screen you can choose to either start login through SSO or to use an alternative login method, which will bring you back to the normal Home Assistant username/password login screen.
\ No newline at end of file
diff --git a/docs/ui-config-steps/client-details.png b/docs/ui-config-steps/client-details.png
new file mode 100644
index 0000000..22a8618
Binary files /dev/null and b/docs/ui-config-steps/client-details.png differ
diff --git a/docs/ui-config-steps/discovery-url-failure.png b/docs/ui-config-steps/discovery-url-failure.png
new file mode 100644
index 0000000..1b8c8d7
Binary files /dev/null and b/docs/ui-config-steps/discovery-url-failure.png differ
diff --git a/docs/ui-config-steps/discovery-url-success.png b/docs/ui-config-steps/discovery-url-success.png
new file mode 100644
index 0000000..9a5341b
Binary files /dev/null and b/docs/ui-config-steps/discovery-url-success.png differ
diff --git a/docs/ui-config-steps/discovery-url.png b/docs/ui-config-steps/discovery-url.png
new file mode 100644
index 0000000..60b7815
Binary files /dev/null and b/docs/ui-config-steps/discovery-url.png differ
diff --git a/docs/ui-config-steps/ui-configuration.gif b/docs/ui-config-steps/ui-configuration.gif
new file mode 100644
index 0000000..b4fe40f
Binary files /dev/null and b/docs/ui-config-steps/ui-configuration.gif differ
diff --git a/docs/ui-config-steps/ui-reconfigure.gif b/docs/ui-config-steps/ui-reconfigure.gif
new file mode 100644
index 0000000..bde3176
Binary files /dev/null and b/docs/ui-config-steps/ui-reconfigure.gif differ