Here's a step by step guide to use the integration:
Install the integration through HACS. You can add it automatically using the button below, or use the Github URL and type Integration in the manual Custom Repository add dialog.
The integration is currently configurable through YAML only. See the Configuration Guide for more details or pick your OIDC provider below:
 |
 |
 |
|---|---|---|
| Authentik | Authelia | Pocket ID |
By default, the integration assumes you configure Home Assistant as a public client and thus only specify the client_id and no client_secret. For example, your configuration might look like:
auth_oidc:
client_id: "example"
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.
Restart Home Assistant. You can do so by going to the Reparations/Update section in Home Assistant.
After restarting Home Assistant, you should now be able to get to the login screen. You can find it at <your HA URL>/auth/oidc/welcome. You will have to go there manually for now. For example, it might be located at http://homeassistant.local:8123/auth/oidc/welcome.
It should look like this:
If you have configured everything correctly, you should be redirected to your OIDC Provider after clicking the button. Please login there.
You should return to a screen like this:
Either click the automatic sign in button or copy the code. This screen will give you a one-time code to login that expires in 5 minutes.
If you would like to login automatically, click the button. It will log you in to your user in the current browser window.
If you would like to login using the code, go to your normal Home Assistant URL without any user logged in, such as on your mobile device/wall tablet/smart watch. You will now see the following screen:
If you don't, you likely see:
If so, click "OpenID Connect (SSO)" to get to the first screen. If you have configured a display name, that will show instead.
Enter your code into the single input field:
Upon clicking login, you should now login. If the code is wrong, you will see this instead:
You will be logged in after following this guide.
With the default configuration, a person entry will be created for every new OIDC user logging in. New OIDC users will get their own fresh user, linked to their persistent ID (subject) at the OpenID Connect provider. You may change your name, username or email at the provider and still have the same Home Assistant user profile.
You can link the user directly to one of these following URLs:
/auth/oidc/welcome(if you would like a nice welcome screen for your users)/auth/oidc/redirect(if you would like to just redirect them without a welcome screen)
For a seamless user experience, configure a new domain on your proxy to redirect to the /auth/oidc/welcome path or configure that path on your homelab dashboard or in your OIDC provider (such as in the app settings in Authentik). Users will then always start on the OIDC welcome page, which will allow them to visit the dashboard if they are already logged in.
Note: do not replace the standard path with a redirect to the OIDC screen. This breaks login with code.