Home Assistant Auth.md

Home Assistant Auth

This page describes how Home Assistant authentication works in a few scenarios for background context in the discussion around Model Context Protocol authentication.

Users run an instance of Home Assistant software as a self hosted application in their local network.

Users authenticating to their Home Assistant Instance

See Authentication API for a more complete version of this.

Client users OAuth + Indie Auth extension to login to Home Assistant. The Home Assistant Web frontend or Mobile App is an OAuth client to the Home Assistant server.

• The Client ID is the users Home Assistant instance url e.g. https://www.my-application.io
• The redirect url is https://www.my-application.io/hass/auth_callback

sequenceDiagram
    participant C as User (Browser)
    participant M as Client (e.g. Web Frontend JS, Mobile App)
    participant A as Home Assistant
    C->>M: Login to Home Assistant
    M->>C: Authorize Url
    C->>A: Go to url and authorize
    A->>M: Authorization Code
    M->>A: Exchange Code for Tokens
    A->>M: Tokens
    M->>C: Continue
    C->>M: Use service
    M->>A: Authenticated request

Loading

• authorize url is http://your-instance.com/auth/authorize? client_id=https%3A%2F%2Fhass-auth-demo.glitch.me& redirect_uri=https%3A%2F%2Fhass-auth-demo.glitch.me%2F%3Fauth_callback%3D1 (also contains state w/ redirect url).

• auth callback url is https://hass-auth-demo.glitch.me/auth_callback? code=12345& state=http%3A%2F%2Fhassio.local%3A8123

• A token endpoint returns tokens given valid grants. The responses look the same as a typical OAuth endpoint (can return access tokens and refresh tokens, returns their expiration, can revoke tokens). {"access_token": "...", "expires_in": 1800, ...}

• Authenticated requests contain an authorization header Authorization: Bearer ABCDEFGH

User allowing Home Assistant access to 3P Cloud Services

Home Assistant allows users to integration with 3P services. In these scenarios the user would already be authenticated to Home Assistant from the previous flow.

sequenceDiagram
    participant C as User (Browser)
    participant M as Home Assistant
    participant A as 3P service
    C->>M: Add 3P integration (e.g. Nest)
    M->>C: Authorize Url
    C->>A: Go to url and authorize (e.g. .../authorize)
    A->>M: Authorization Code (/auth/external_callback)
    M->>A: Exchange Code for Tokens (e.g. .../token)
    A->>M: Tokens
    M->>C: Ready to use

Loading

Setting up an integration with a 3P cloud service typically requires:

• The user to creaet a Client ID and Secret with the 3P service (e.g. the user acts like a developer and creates a new Client ID and Secret, configures alowed redirect urls, etc) example.
• The user then configures Home Assistant with the Client ID and Secret (Application credentials)
• An alternative is there can also be a shared Client ID used by all Home Assistant assistant for the 3P service. This typically requires Nabu Casa (Home Assistant sponsoring company) arraging and acting as a proxy service for part of this flow on their server (sometimes requires some dev rel partnership, sometimes self service)