【HA的认证和授权机制】第2篇--API

Mirukuteii

【HA的认证和授权机制】第2篇--API

• HA = Home-Assistant
• 翻译自HA官方开发者文档，中英文对照，老少咸宜。

---

认证API(Authentication API)

---

此页面将描述我们开发的应用程序，通过授权接入HA实例所需的步骤。
This page will describe the steps required for your application to authorize against and integrate with Home Assistant instances.

每个用户都有属于自己的HA实例，它可以让每个用户控制自己的数据。但是，我们也希望第三方开发人员能够轻松创建出允许用户接入HA实例的应用程序。为此，我们采用了带有OAuth 2 IndieAuth扩展包的OAuth 2 规范来生成客户端。
Each user has their own instance of Home Assistant which gives each user control over their own data. However, we also wanted to make it easy for third party developers to create applications that allow users to integrate with Home Assistant. To achieve this, we have adopted the OAuth 2 specification combined with the OAuth 2 IndieAuth extension for generating clients.

译者注:
IndieAuth的维基百科
IndieAuth是一种标准的分散式身份验证协议，使用OAuth 2.0，使服务能够验证由URL表示的用户的身份，并获取在用户控制下访问资源所需要的访问令牌。

客户端(Clients)

在用户通过我们开发的应用程序授权实例之前，我们首先要准备好客户端。在传统的OAuth2中，服务器需要在用户授权之前生成客户端。但是，由于每个服务器都属于用户，因此我们采用了与IndieAuth略有不同的方法。
Before you can ask the user to authorize their instance with your application, you will need a client. In traditional OAuth2, the server needs to generate a client before a user can authorize. However, as each server belongs to a user, we've adopted a slightly different approach from IndieAuth.

我们使用的客户端ID是我们应用程序的网站。重定向URI必须与客户端ID具有相同的主机和端口。例如：

• 客户端ID： https://www.my-application.io
• 重定向URI： https://www.my-application.io/hass/auth_callback

The client ID you need to use is the website of your application. The redirect url has to be of the same host and port as the client ID. For example:

• client id: https://www.my-application.io
• redirect uri: https://www.my-application.io/hass/auth_callback

如果我们需要与客户端ID不同的重定向URI（例如，构建原生APP），则可以将跳转网址的HTML标签添加到应用程序网站（客户端ID）的源代码中，作为认可的重定向URI。例如：
If you require a different redirect url (ie, if building a native app), you can add an HTML tag to the content of the website of your application (the client ID) with an approved redirect url. For example:

<link rel='redirect_uri' href='hass://auth'>

HA将扫描网站的前10kB内容以获取这些标签。
Home Assistant will scan the first 10kB of a website for these tags.

授权(Authorize)

为了便于大家阅读，下面所有的示例URL都被拆散开来，带有额外的空格和换行。在实际的网址中，请不要这样写。
All example URLs here are shown with extra spaces and new lines for clarity. Those should not be in the final url.

授权URL应包含client_id和redirect_uri作为参数。
The authorize url should contain client_id and redirect_uri as query parameters.

译者注
URL格式：
协议://用户名:密码@子域名.域名.顶级域名:端口号/目录/文件名.文件后缀?参数=值#标志

http://your-instance.com/auth/authorize?
    client_id=ABCDE&
    redirect_uri=https%3A%2F%2Fexample.com%2Fhass_callback

我们还可以选择添加state参数，这将添加到重定向uri中。该参数非常适合保存我们要进行身份认证的HA实例URL。例：
Optionally you can also include a state parameter, this will be added to the redirect uri. The state is perfect to store the instance url that you are authenticating with. Example:

http://your-instance.com/auth/authorize?
    client_id=ABCDE&
    redirect_uri=https%3A%2F%2Fexample.com%2Fhass_callback&
    state=http%3A%2F%2Fhassio.local%3A8123

用户将被导航到此链接，在提示下登录并授权我们的应用程序。一旦授权，用户将被重新导航到重定向uri的网址，其中授权码和状态将作为新的URL的参数的一部分。例：
The user will navigate to this link and be presented with instructions to log in and authorize your application. Once authorized, the user will be redirected back to the passed in redirect uri with the authorization code and state as part of the query parameters. Example:

https://example.com/hass_callback?
    code=12345&
    state=http%3A%2F%2Fhassio.local%3A8123

此授权码可以发送到令牌端点用来交换令牌（请参阅下一节）。
This authorization code can be exchanged for tokens by sending it to the token endpoint (see next section).

令牌(Token)

令牌端点收到有效授权后发放令牌。此授权来自于授权端点收到的授权码或是一个刷新令牌。
The token endpoint returns tokens given valid grants. This grant is either an authorization code retrieved from the authorize endpoint or a refresh token.

想要和令牌端点的交互，必须通过HTTP POST请求的方式，将application/x-www-form-urlencoded格式编码的请求主体，发送到http://your-instance.com/auth/token。
All interactions with this endpoint need to be HTTP POST requests to http://your-instance.com/auth/token with the request body encoded in application/x-www-form-urlencoded.

授权码(Authorization code)

对令牌端点的所有请求中，必须包含客户端ID，并且这个客户端ID必须与曾经将用户重定向到授权端点时使用的客户但ID完全相同。
All requests to the token endpoint need to contain the exact same client ID as was used to redirect the user to the authorize endpoint.

在用户成功完成授权步骤后，应使用授权类型authorization_code取得令牌。请求正文是：
Use the grant type authorization_code to retrieve the tokens after a user has successfully finished the authorize step. The request body is:

grant_type=authorization_code&
code=12345&
client_id=https%3A%2F%2Fwww.home-assistant.io%2Fios

返回的响应将会是访问令牌和刷新令牌：
The return response will be an access and refresh token:

{
    "access_token": "ABCDEFGH",
    "expires_in": 1800,
    "refresh_token": "IJKLMNOPQRST",
    "token_type": "Bearer"
}

访问令牌是一个可以用来访问API的短期令牌。刷新令牌可用于获取新的访问令牌。expires_in的值表示访问令牌的有效期，单位为秒。
The access token is a short lived token that can be used to access the API. The refresh token can be used to fetch new access tokens. The expires_in value is seconds that the access token is valid.

刷新令牌(Refresh token)

当我们已经通过授权类型authorization_code取得刷新令牌后，就可以使用它来获取新的访问令牌。请求正文是：
Once you have retrieved a refresh token via the grant type authorization_code, you can use it to fetch new access tokens. The request body is:

grant_type=refresh_token&
refresh_token=IJKLMNOPQRST

The return response will be an access token:

{
    "access_token": "ABCDEFGH",
    "expires_in": 1800,
    "token_type": "Bearer"
}

发送身份认证请求(Making authenticated requests)

获得访问令牌后，我们可以向HA API发送身份验证的请求。
Once you have an access token, you can make authenticated requests to the Home Assistant APIs.

对于websocket连接，请在身份认证消息中传递访问令牌。
For the websocket connection, pass the access token in the authentication message.

对于HTTP请求，请将令牌类型和访问令牌作为授权标头传递：
For HTTP requests, pass the token type and access token as the authorization header:

Authorization: Bearer ABCDEFGH

如果访问令牌不再有效，我们将获得HTTP状态代码401未授权的响应结果。这意味着我们需要刷新令牌。如果刷新令牌不起作用，则令牌不再有效，该用户无法再登录。我们应该清除用户的数据并提示用户再次进行授权。
If the access token is no longer valid, you will get a response with HTTP status code 401 unauthorized. This means that you will need to refresh the token. If the refresh token doesn't work, the tokens are no longer valid and so the user is no longer logged in. You should clear the user's data and ask the user to authorize again.

wqqs

前排支持!

mobster

认真阅读

neroxps

感谢M大翻译文章

咸味土豆

感谢大佬分享。

狮心哥哥

连图都翻了，厉害。