79 lines
4.3 KiB
Markdown
79 lines
4.3 KiB
Markdown
# OIDC Auth for Home Assistant
|
|
|
|
> [!CAUTION]
|
|
> This is an alpha release. I give no guarantees about code quality, error handling or security at this stage. Please treat this repo as a proof of concept for now and only use it on development HA installs.
|
|
|
|
Provides an OIDC implementation for Home Assistant.
|
|
|
|
### Background
|
|
If you would like to read the background/open letter that lead to this component, please see https://community.home-assistant.io/t/open-letter-for-improving-home-assistants-authentication-system-oidc-sso/494223. It is currently one of the most upvoted feature requests for Home Assistant.
|
|
|
|
## How to use
|
|
### Installation
|
|
|
|
Add this repository to [HACS](https://hacs.xyz/).
|
|
|
|
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=christiaangoossens&repository=hass-oidc-auth&category=Integration)
|
|
|
|
Update your `configuration.yaml` file with
|
|
|
|
```yaml
|
|
auth_oidc:
|
|
client_id: ""
|
|
discovery_url: ""
|
|
```
|
|
|
|
Register your client with your OIDC Provider (e.g. Authentik/Authelia) as a public client and get the client_id. Then, use the obtained client_id and discovery URLs to fill the fields in `configuration.yaml`.
|
|
|
|
For example:
|
|
```yaml
|
|
auth_oidc:
|
|
client_id: "someValueForTheClientId"
|
|
discovery_url: "https://example.com/application/o/application/.well-known/openid-configuration"
|
|
```
|
|
|
|
Afterwards, restart Home Assistant.
|
|
|
|
### Login
|
|
You should now be able to see a second option on your login screen ("OpenID Connect (SSO)"). It provides you with a single input field.
|
|
|
|
To start, go to one of to one of these URLs (you may also set these as application URLs in your OIDC Provider):
|
|
- `/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)
|
|
|
|
So, for example, you may start at http://homeassistant.local:8123/auth/oidc/welcome.
|
|
|
|
> [!TIP]
|
|
> You can use a different device to login instead. Open the `/auth/oidc/welcome` link on device A and then type the obtained code into the normal HA login on device B (can also be the mobile app) to login.
|
|
|
|
## Development
|
|
This project uses the Rye package manager for development. You can find installation instructions here: https://rye.astral.sh/guide/installation/.
|
|
Start by installing the dependencies using `rye sync` and then point your editor towards the environment created in the `.venv` directory.
|
|
|
|
### Help wanted
|
|
If you have any tips or would like to contribute, send me a message. You are also welcome to contribute a PR to fix any of the TODOs.
|
|
|
|
Currently, this is a pre-alpha, so I welcome issues but I cannot guarantee I can fix them (at least within a reasonable time). Please turn on watch for this repository to remain updated. When the component is in a beta stage, issues will likely get fixed more frequently.
|
|
|
|
### TODOs
|
|
|
|
- [X] Basic flow
|
|
- [X] Implement a final link back to the main page from the finish page
|
|
- [X] Improve welcome screen UI, should render a simple centered Tailwind UI instructing users that you should login externally to obtain a code.
|
|
- [X] Improve finish screen UI, showing the code clearly with instructions to paste it into Home Assistant.
|
|
- [ ] Implement error handling on top of this proof of concept (discovery, JWKS, OIDC)
|
|
- [ ] Make id_token claim used for the group (admin/user) configurable
|
|
- [ ] Make id_token claim used for the username configurable
|
|
- [ ] Make id_token claim used for the name configurable
|
|
- [ ] Add instructions on how to deploy this with Authentik & Authelia
|
|
- [X] Configure Github Actions to automatically lint and build the package
|
|
- [ ] Configure Dependabot for automatic updates
|
|
- [ ] Configure tests
|
|
- [ ] Consider use of setup UI instead of YAML (see https://github.com/christiaangoossens/hass-oidc-auth/discussions/6)
|
|
|
|
Currently waiting on HA feature additions:
|
|
|
|
- [ ] Update the HA frontend code to allow a redirection to be requested from an auth provider instead of manually opening welcome page (possibly after https://github.com/home-assistant/frontend/pull/23204)
|
|
- [ ] Implement this redirection logic to open a new tab on desktop (#23204 uses popup)
|
|
- [ ] Implement this redirection logic to open a Android Custom Tab (Android) / SFSafariViewController (iOS), instead of opening the link in the HA webview
|