feat: Embedded SDK

.github/workflows/embedded-sdk-release.yml

@@ -0,0 +1,23 @@
+name: Embedded SDK Release
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    defaults:
+      run:
+        working-directory: superset-embedded-sdk
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: "16"
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run ci:release
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/embedded-sdk-test.yml

@@ -0,0 +1,23 @@
+name: Embedded SDK PR Checks
+
+on:
+  pull_request:
+    paths:
+      - "superset-embedded-sdk/**"
+    types: [synchronize, opened, reopened, ready_for_review]
+
+jobs:
+  embedded-sdk-test:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-20.04
+    defaults:
+      run:
+        working-directory: superset-embedded-sdk
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: "16"
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build

superset-embedded-sdk/.gitignore

@@ -0,0 +1,3 @@
+bundle
+dist
+lib

superset-embedded-sdk/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Contributing to the Superset Embedded SDK
+
+The superset-embedded-sdk directory is a self contained sub-project in the Superset codebase.
+
+This is because the SDK has different requirements from other parts of the Superset codebase:
+Namely, we need to export a lightweight frontend library that can be used in as many environments as possible.
+Having separate configs allows for better separation of concerns and allows the SDK code to remain simple.
+
+## Testing
+
+The functions used in the sdk so far are very closely tied to browser behavior,
+and therefore are not easily unit-testable. We have instead opted to test the sdk behavior using end-to-end tests.
+This way, the tests can assert that the sdk actually mounts the iframe and communicates with it correctly.
+
+At time of writing, these tests are not written yet, because we haven't yet put together the demo app that they will leverage.
+### Things to e2e test once we have a demo app:
+
+**happy path:**
+
+fetch valid guest token and pass it to the sdk, verify that the dashboard shows up
+
+**security:**
+
+it should fail if you pass a fake guest token
+it should fail if your guest token doesn't have permission to access this resource
+it should apply rls filters correctly
+it should not apply rls filters to a dataset that isn't included
+
+**edge cases:**
+
+what happens if superset is offline
+what happens if the superset domain is invalid or incorrect
+what happens if dashboard id doesn't exist
+
+## Publishing
+
+To publish a new version, first determine whether it will be a major/minor/patch version according to [semver rules](https://semver.org/).
+Run `npm version [major|minor|patch]`, and include the resulting version change in your PR.
+
+Building the package and publishing to npm will be handled by github actions automatically on merge to master,
+provided that the currently specified package version isn't already published.
+
+## Building
+
+Builds are handled by CI, so there is no need to run the build yourself unless you are curious about it.
+
+The library is built in two modes: one for consumption by package managers
+and subsequent build systems, and one for consumption directly by a web browser.
+
+Babel is used to build the sdk into a relatively modern js package in the `lib` directory.
+This is used by consumers who install the embedded sdk via npm, yarn, or other package manager.
+
+Webpack is used to bundle the `bundle` directory,
+for use directly in the browser with no build step e.g. when importing via unpkg.
+
+Typescript outputs type definition files to the `dist` directory.
+
+Which of these outputs is used by the library consumer is determined by our package.json's `main`, `module`, and `types` fields.

superset-embedded-sdk/README.md

@@ -0,0 +1,90 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Superset Embedded SDK
+
+The Embedded SDK allows you to embed dashboards from Superset into your own app,
+using your app's authentication.
+
+Embedding is done by inserting an iframe, containing a Superset page, into the host application.
+
+## Embedding a Dashboard
+
+Using npm:
+
+```sh
+npm install --save @superset-ui/embedded-sdk
+```
+
+```js
+import { embedDashboard } from "@superset-ui/embedded-sdk";
+
+embedDashboard({
+  id: "abc123", // given by the Superset embedding UI
+  supersetDomain: "https://superset.example.com",
+  mountPoint: document.getElementById("my-superset-container"), // any html element that can contain an iframe
+  fetchGuestToken: () => fetchGuestTokenFromBackend(),
+});
+```
+
+You can also load the Embedded SDK from a CDN. The SDK will be available as `supersetEmbeddedSdk` globally:
+
+```html
+<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>
+
+<script>
+  supersetEmbeddedSdk.embedDashboard({
+    // ... here you supply the same parameters as in the example above
+  });
+</script>
+```
+
+## Authentication/Authorization with Guest Tokens
+
+Embedded resources use a special auth token called a Guest Token to grant Superset access to your users,
+without requiring your users to log in to Superset directly. Your backend must create a Guest Token
+by requesting Superset's `POST /security/guest_token` endpoint, and pass that guest token to your frontend.
+
+The Embedding SDK takes the guest token and use it to embed a dashboard.
+
+### Creating a Guest Token
+
+From the backend, http `POST` to `/security/guest_token` with some parameters to define what the guest token will grant access to.
+Guest tokens can have Row Level Security rules which filter data for the user carrying the token.
+
+The agent making the `POST` request must be authenticated with the `can_grant_guest_token` permission.
+
+Example `POST /security/guest_token` payload:
+
+```json
+{
+  "user": {
+    "username": "stan_lee",
+    "first_name": "Stan",
+    "last_name": "Lee"
+  },
+  "resources": [{
+    "type": "dashboard",
+    "id": "abc123"
+  }],
+  "rls": [
+    { "clause": "publisher = 'Nintendo'" }
+  ]
+}
+```

superset-embedded-sdk/babel.config.js

@@ -0,0 +1,26 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+module.exports = {
+  presets: [
+    "@babel/preset-typescript",
+    "@babel/preset-env"
+  ],
+  sourceMaps: true,
+};