As a Home Assistant enthusiast, I’ve been using it extensively for numerous home automation projects. However, when exposing your Home Assistant instance to the internet, security becomes paramount. Everything related to your home becomes exposed, making strong authentication essential.

I wanted an additional security layer to authenticate users and restrict access to my family. The solution? Setting up OAuth authentication using the popular and proven oauth2-proxy project.

image

Initial Setup

My working Home Assistant setup includes:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1

homeassistant:
  auth_providers:
    - type: homeassistant
    - type: trusted_networks

You’ll need this nginx directive to use use_x_forwarded_for:

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Everything runs as Docker containers on a Raspberry Pi 5, working well to protect and access the web-exposed Home Assistant instance.

But then came the challenge: connecting the Home Assistant companion app to this SSO-protected instance…

Problem #1: Delegating Authentication to SSO

Home Assistant doesn’t provide any authentication method other than username/password, as documented in their authentication providers documentation.

This has been an ongoing debate in the Home Assistant community, with discussions like this one and this open letter generating frustration. Unfortunately, no officially supported SSO option exists in 2025.

Solution: I adopted the hass-auth-header plugin from HACS. This plugin overwrites authentication JavaScript files to auto-login users from HTTP headers generated by oauth2-proxy and passed upstream by nginx.

You need these nginx directives to pass the authenticated user email to Home Assistant:

auth_request_set $auth_email $upstream_http_x_auth_request_email;
proxy_set_header X-Forwarded-Preferred-Username $auth_email;

You also need to create Home Assistant users with their matching email as the username.

Problem #2: Companion App Authentication

Using the iOS companion app, it automatically redirects to your authentication screen (Google in my case). However, I encountered this error:

Access blocked: This request is blocked by Google’s rules
This request does not comply with Google’s policy regarding the use of secure browsers.
Error 403: disallowed_useragent

This standard message appears when an app tries to open the Google sign-in page in an insecure WebView instead of a real browser.

Solution: Switch the OAuth provider from Google to GitHub, which is easy to set up following the oauth2-proxy GitHub configuration. GitHub will expose the primary email of the logged user. You just have to update your oauth-proxy email allowlist via authenticated_emails_file proxy option.

Problem #3: Still Not Connecting via SSO

The solution came from this comment.

image

Although you may get an error connecting your public hostname, you can ignore them, connect using your local instance ip, and then go to the companion app settings to set your public host back.

Problem #4: WebSocket Errors

Even after switching to a compatible provider, you might encounter WebSocket errors. This typically comes from your reverse proxy nginx configuration.

Solution: Add these nginx directives to allow WebSocket compatibility and reverse proxy WebSocket handshake:

proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";

Conclusion

While Home Assistant doesn’t officially support SSO, the community has found creative solutions. The combination of oauth2-proxy, hass-auth-header, and proper nginx configuration makes it possible to secure your Home Assistant instance with SSO while maintaining compatibility with the companion app.

The journey involves several challenges, but the end result is a more secure Home Assistant setup that doesn’t compromise on functionality or user experience.