For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /developers/auth_index.md.

身份验证

Home Assistant 拥有一个内置的身份验证系统,允许不同的用户与 Home Assistant 进行交互。身份验证系统由各个部分组成。

概述各部分如何交互

身份验证提供方

身份验证提供方用于让用户进行身份认证。采用何种认证方式以及使用哪个后端,由身份验证提供方自行决定。默认情况下,我们启用了内置的 Home Assistant 身份验证提供方,它会将用户安全地存储在你的配置目录中。

Home Assistant 将使用哪些身份验证提供方,是在 configuration.yaml 中指定的。可以同时启用多个同一身份验证提供方实例。在这种情况下,每个实例会通过一个唯一的标识符来识别。相同类型的身份验证提供方之间不会共享凭证。

凭证

凭证用于存储用户在特定身份验证提供方处的认证信息。它在用户成功认证时产生。它会允许系统在系统中找到该用户。如果用户不存在,则会创建一个新的用户。该用户不会被激活,而需要管理员(owner)的批准。

一个用户可以关联多个凭证。但是,对于每个特定的身份验证提供方,它只能拥有一个凭证。

用户

每个人都是系统中的用户。要以特定用户登录,可以通过与该用户关联的任意一个身份验证提供方进行认证。用户登录时,会获得一个刷新令牌(refresh token)和一个访问令牌(access token),用于向 Home Assistant 发起请求。

Owner

在引导(onboarding)过程中创建的用户会被标记为"owner"。owner 可以管理其他用户,并且始终拥有所有权限的访问权。

群组

用户属于一个或多个群组。群组身份是用户被授予权限的方式。

权限策略

这是描述某个群组可以访问哪些资源的权限策略。有关权限和策略的更多信息,请参阅 权限

访问令牌和刷新令牌

希望访问 Home Assistant 的应用程序会要求用户启动一个授权流程。当用户成功通过 Home Assistant 授权该应用程序时,该流程会产生一个授权码。此代码可用于获取访问令牌和刷新令牌。访问令牌的有效期有限,而刷新令牌会保持有效,直到用户删除它为止。

访问令牌用于访问 Home Assistant API。刷新令牌用于获取新的有效访问令牌。

刷新令牌类型

刷新令牌有三种不同的类型:

  • Normal:这些令牌在用户授权应用程序时生成。应用程序会代表用户持有这些令牌。
  • Long-lived Access Token:这些是支持长期访问令牌的刷新令牌。它们是在内部创建的,永远不会暴露给用户。
  • System:这些令牌仅限于系统用户(如 Home Assistant OS 和 Supervisor)生成和使用。它们永远不会暴露给用户。