From fb614a9f0b405c055d743381c66d6c61a3fd1363 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Wed, 24 Oct 2018 17:43:58 +0200 Subject: [PATCH 1/3] Add docs for signed path --- docs/auth_api.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/auth_api.md b/docs/auth_api.md index e2e00345..58fdd8ee 100644 --- a/docs/auth_api.md +++ b/docs/auth_api.md @@ -219,3 +219,34 @@ If the access token is no longer valid, you will get a response with HTTP status [oauth2-spec]: https://tools.ietf.org/html/rfc6749 [indieauth-spec]: https://indieauth.spec.indieweb.org/ [indieauth-clients]: https://indieauth.spec.indieweb.org/#client-identifier + +## Signed paths + +Sometimes you want a user to make a GET request to Home Assistant to download data. In this case the normal auth system won't do, as we can't link the user to an API with the auth header attached to it. In that case, a signed path can help. + +A signed path is a normal path on our server, like `/api/states`, but with an attached secure authentication signature. The user is able to navigate to this path and will be authorised as the access token that created the signed path. Signed paths can be created via the websocket connection and are meant to be shortlived. The default expiration is 30 seconds. + +To get a signed path, send the following command: + +```js +{ + "type": "auth/sign_path", + "path": "/api/states", + // optional, expiration time in seconds. Defaults to 30 seconds + "expires": 20 +} +``` + +The response will contain the signed path: + +```js +{ + "path": "/api/states?authSig=ABCDEFGH" +} +``` + +Some things to note about a signed path: + + - If the refresh token is deleted, the signed url is no longer valid. + - If the user is deleted, the signed url is no longer valid (because the refresh token will be deleted). + - If Home Assistant is restarted, the signed url is no longer valid. From 40a7174266a0d0bd46f72eb5768dcb3c3a653cd4 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Wed, 24 Oct 2018 17:49:59 +0200 Subject: [PATCH 2/3] Add extra note about expiration time --- docs/auth_api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/auth_api.md b/docs/auth_api.md index 58fdd8ee..fc8da74b 100644 --- a/docs/auth_api.md +++ b/docs/auth_api.md @@ -250,3 +250,4 @@ Some things to note about a signed path: - If the refresh token is deleted, the signed url is no longer valid. - If the user is deleted, the signed url is no longer valid (because the refresh token will be deleted). - If Home Assistant is restarted, the signed url is no longer valid. + - Access is only validated when the request is received. If a response takes longer than the expiration time (ie, downloading a large file), the download will continue after the expiration date has past. From e4db9e8c4978500ec3a9b6b29e4b8ce12889bc6e Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Wed, 24 Oct 2018 19:06:34 +0200 Subject: [PATCH 3/3] Spelling --- docs/auth_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/auth_api.md b/docs/auth_api.md index fc8da74b..e5fb7f1c 100644 --- a/docs/auth_api.md +++ b/docs/auth_api.md @@ -250,4 +250,4 @@ Some things to note about a signed path: - If the refresh token is deleted, the signed url is no longer valid. - If the user is deleted, the signed url is no longer valid (because the refresh token will be deleted). - If Home Assistant is restarted, the signed url is no longer valid. - - Access is only validated when the request is received. If a response takes longer than the expiration time (ie, downloading a large file), the download will continue after the expiration date has past. + - Access is only validated when the request is received. If a response takes longer than the expiration time (ie, downloading a large file), the download will continue after the expiration date has passed.