# hass-oidc-auth: putting single sign-on in front of Home Assistant > hass-oidc-auth is a Home Assistant custom integration that turns the dashboard into an OpenID Connect relying party, so a homelab can use authentik, Authelia, Pocket ID or any other OIDC provider for login. Its stated priorities are specification adherence, minimal patching of Home Assistant core, and accessibility, and it installs through HACS. **christiaangoossens/hass-oidc-auth** — OpenID Connect authentication provider for Home Assistant - Repository: https://github.com/christiaangoossens/hass-oidc-auth - Stars: 1,129 · Forks: 62 - Language: Python - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/christiaangoossens-hass-oidc-auth ## What the integration adds to Home Assistant Home Assistant ships with its own local authentication, and for a single household that is usually enough. The integration changes that by making the dashboard an OpenID Connect client, also called a relying party, so that login happens at an identity provider you control and the rest of your stack can share one session. The README is precise about the role it plays, the client or relying party side only, which means it does not issue tokens or hold user records of its own. That distinction matters when you plan the deployment, because you still need something like authentik, Authelia, Pocket ID or Keycloak to be the other end of the flow, and this integration is the piece that lets Home Assistant talk to it. The result is described as a single sign-on environment across a self-hosted stack, and the short version in the README is blunt about the goal, that logging in should just work every time for everyone in the household. ## Three values, and how each one shows up in the code The project states three core values and each one is testable rather than decorative. Security means strict adherence to the OpenID Connect core specification in the client role, to RFC 6749 for OAuth 2, to RFC 7519 for JSON Web Tokens, to RFC 7636 for PKCE and to RFC 9700 on OAuth 2 security practices, and the automated test suite is said to include security tests. Stability means patching the Home Assistant core as little as possible, because the failure mode that matters is a Home Assistant update that leaves you unable to log in at all. Accessibility means the integration should work for everyone with the default settings regardless of which authentication method a person prefers, which is a concrete constraint on the design of the login screen rather than a slogan. A reader evaluating the project can hold all three of those against the code and the documentation and see whether they hold. ## Installing it through HACS The installation path goes through the Home Assistant Community Store, and the README calls that the easiest way in. You install HACS, open it, search for OpenID Connect in the search box, and add the integration. After that the work is on the provider side, and the repository ships dedicated guides for three of them, authentik, Authelia and Pocket ID, with a folder for additional provider configurations. The generic instructions cover the rest: register the application with your provider as a public client, which the README recommends, or as a confidential client, and set the callback URL to the path below: ```text /auth/oidc/callback ``` That single path is the whole integration point between the provider and Home Assistant, and getting it wrong is the most common reason a first attempt fails, since the provider will refuse a redirect that does not match exactly. Once the provider is configured, opening Home Assistant in the browser or in the mobile app should send you straight to the provider login page. ## Configuring through the interface or through YAML There are two configuration styles and the project recommends the interface for people starting out. The path is Settings, then Devices and Services, then Add Integration, then OpenID Connect or SSO Authentication, and the README walks through the prompts. The YAML route exists for everything else, with a full configuration guide in the documentation. The interesting part is that the two are not equivalent, and the README says so: many options are reachable through the interface, but some advanced features are only available in YAML, and the reason given is that it keeps the setup process in the interface simple. That is a reasonable trade for a beginner and a frustrating one for somebody who has configured an identity provider before and wants to paste a block. The choice of style should be made before you start, not after the third attempt at a setting that does not appear in the interface. ## The Python package and its test suite The project is a Python package that is built as a wheel containing the custom_components/auth_oidc package, using the hatchling build backend and managed with uv, with a lock file committed. The declared runtime needs Python 3.14.5 or later, and the runtime dependencies are small and telling: aiofiles for asynchronous file access, jinja2 for rendering, and joserfc for the JSON web token and key handling that any OIDC client needs. The development group pulls in the Home Assistant package itself, pylint and ruff for linting, and a pytest setup with pytest-asyncio and pytest-cov, with the coverage flag wired into the pytest options. A pytest plugin for custom components is included, which is the standard way to test a Home Assistant integration against a real instance harness, and the presence of that plugin says more about the testing rigour than the badge does. ## Why a Node toolchain sits in a Python project The package manifest at the root is small and contains only a stylesheet build, with the Tailwind command line and the Tailwind package as the only dependencies, and two scripts, one that compiles the input stylesheet into the static style file of the integration and one that watches it. The reason is that the login screen is part of the integration, so it ships as static assets inside the custom component, and those assets are generated with Tailwind rather than hand written. For a contributor this means a Node toolchain is needed only to change the styling, and the watch script makes that a one-line loop, while everyone else never touches it. The front end also has to satisfy the accessibility goal, which is the harder constraint, since a login page has to work with a keyboard, with a screen reader and with a password manager, and the layout is the part most likely to regress without a test. ## Where the approach does not reach There are three honest limits. The first is that a custom component is not part of Home Assistant, so it lives outside the guarantees that the core project gives its own integrations, and the stability goal of minimal patching reduces the risk of a break without removing it. The second is that the integration is only a client, so there is no path to a working login without an identity provider somewhere, and a provider that speaks only OAuth 2 without OIDC will not do, because the token and discovery handling is what makes this an OIDC integration. The third is the trust question, because installing a custom component from a community store is a decision a security conscious user makes knowingly, and the project answers it partly with the security policy, the security tests and the emphasis on specification adherence rather than by being a core component. ## Licence, releases and the maintenance signals The project is released under the MIT licence, with a LICENSE.md file in the repository root, and the metadata for the package records the same licence. The release history is short and recent, v1.2.1 and v1.2.0 both published on 2026-08-19 and v1.1.1 on 2026-06-08, with the last push on 2026-10-19, so the project is active and the version numbers are still low. Several files in the tree are worth a look for what they imply about how the project is run. There is a renovate configuration, which is how the dependency updates are automated, a pysentry configuration for dependency vulnerability scanning, a code of conduct, a funding file, a security policy, and a set of discussion categories for announcements, polls, questions and feature requests. The documentation folder carries the YAML guide, the FAQ and the provider guides, and the FAQ is where the README sends anybody deciding whether the integration fits, which is a sensible place for that material to live. ## Conclusion hass-oidc-auth fits a Home Assistant user who already runs an identity provider and wants one login across a homelab, and it fits anyone who would rather not keep separate local accounts in a dashboard that holds keys and presence sensors. It does not fit a household with no identity provider to point at, since the integration is only a client, and it does not fit someone unwilling to install a custom component into Home Assistant. Before adopting it, read the FAQ in the documentation for the fit questions, register the callback path on your provider, and decide whether the UI flow covers your needs, because several advanced options exist only in the YAML configuration. ## FAQ ### How do I install the Home Assistant OpenID Connect integration? Through the Home Assistant Community Store. Install HACS, search for OpenID Connect, add the integration, then set up your provider and configure it from the Integrations panel or from YAML. ### Which identity providers does hass-oidc-auth document? authentik, Authelia and Pocket ID each have their own guide in the provider configurations folder of the documentation, and any OIDC provider can be used with either a public or a confidential client. ### What callback URL do I register with my identity provider? The path /auth/oidc/callback, appended to the address your Home Assistant instance is reachable at. The provider must be given exactly that value. ### Should I use a public or a confidential client? The README recommends a public client. A confidential client is also supported if a provider requires it, and the choice is part of registering the application with the provider. ### Which specifications does the implementation follow? The OpenID Connect core specification in the client and relying party role, RFC 6749 for OAuth 2, RFC 7519 for JSON Web Tokens, RFC 7636 for PKCE and RFC 9700 on OAuth 2 security practices, with security tests in the automated test suite. ### Which licence is hass-oidc-auth released under? The MIT licence, with the terms in the LICENSE.md file at the repository root and the same licence recorded in the package metadata. ## Sources - [christiaangoossens/hass-oidc-auth on GitHub](https://github.com/christiaangoossens/hass-oidc-auth) - [Issues](https://github.com/christiaangoossens/hass-oidc-auth/issues) - [License: MIT](https://github.com/christiaangoossens/hass-oidc-auth/blob/main/LICENSE) - [README](https://github.com/christiaangoossens/hass-oidc-auth/blob/main/README.md) - [Releases](https://github.com/christiaangoossens/hass-oidc-auth/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/christiaangoossens-hass-oidc-auth