From e49724f281e0b740caa38b4effd57a36777c160d Mon Sep 17 00:00:00 2001
From: Paulus Schoutsen <balloob@gmail.com>
Date: Thu, 6 Sep 2018 12:17:08 +0200
Subject: [PATCH] Add external auth

---
 docs/frontend_external_auth.md | 60 ++++++++++++++++++++++++++++++++++
 website/i18n/en.json           |  1 +
 website/sidebars.json          |  3 +-
 3 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 docs/frontend_external_auth.md

diff --git a/docs/frontend_external_auth.md b/docs/frontend_external_auth.md
new file mode 100644
index 00000000..adcc99f2
--- /dev/null
+++ b/docs/frontend_external_auth.md
@@ -0,0 +1,60 @@
+---
+title: "External Authentication"
+---
+
+By default, the frontend will take care of its own authentication tokens. If none found, it will redirect the user to the login page and it will take care that the token is up to date.
+
+If you want to embed the Home Assistant frontend in an external app, you will want to store the authentication inside the app but make it available to the frontend. To support this, Home Assistant exposes an external authentication API.
+
+To activate this API, load the frontend with `?external_auth=1` appended to the URL. If this is passed in, Home Assistant will expect  either `window.externalApp` to be defined or `window.webkit.messageHandlers` containing the methods described below.
+
+## Get Access Token
+
+_This API has been introduced in Home Assistant 0.78._
+
+When the frontend loads, it will request an access token from the external authentication. It does so by calling one of the following methods with an options object. The options object defines the callback method to be called with the response.
+
+```js
+window.externalApp.getExternalAuth({
+  callback: 'externalAuthSetToken'
+});
+// or
+window.webkit.messageHandlers.getExternalAuth.postMessage({
+  callback: 'externalAuthSetToken'
+});
+```
+
+The response should contain an access token and the number of seconds that it will remain valid. Pass the response to the function defined in the options object.
+
+```js
+// To be called by external app
+window.externalAuthSetToken({
+  "access_token": "qwere",
+  "expires_in": 1800
+});
+```
+
+The frontend will call this method when the page first loads and whenever it needs a valid token but the previous received token has expired.
+
+## Revoke Token
+
+_This API has been introduced in Home Assistant 0.78._
+
+When the user presses the logout button on the profile page, the external app will have to [revoke the refresh token](auth_api.md#revoking-a-refresh-token), and log the user out.
+
+```js
+window.externalApp.revokeExternalAuth({
+  callback: 'externalAuthSetToken'
+});
+// or
+window.webkit.messageHandlers.revokeExternalAuth.postMessage({
+  callback: 'externalAuthSetToken'
+});
+```
+
+When done, the external app has to call the function defined in the options object.
+
+```js
+// To be called by external app
+window.externalAuthRevokeToken();
+```
diff --git a/website/i18n/en.json b/website/i18n/en.json
index 4bba9cd9..2f4a41da 100644
--- a/website/i18n/en.json
+++ b/website/i18n/en.json
@@ -98,6 +98,7 @@
     "Data": "Data",
     "frontend_development": "Frontend development",
     "Development": "Development",
+    "frontend_external_auth": "External Authentication",
     "frontend_index": "Home Assistant Frontend",
     "hassio_addon_communication": "Add-On Communication",
     "hassio_addon_config": "Add-On Configuration",
diff --git a/website/sidebars.json b/website/sidebars.json
index c89c1d0e..5bf6bdde 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -50,7 +50,8 @@
       "frontend_index",
       "frontend_architecture",
       "frontend_development",
-      "frontend_data"
+      "frontend_data",
+      "frontend_external_auth"
     ],
     "Extending the frontend": [
       "frontend_add_card",