DOCSP-4666: [Charts] As a dashboard author, I can enable or disable Signed Auth for a chart (#153)

* DOCSP-4666: [Charts] As a dashboard author, I can enable or disable Signed Auth for a chart

Author: steveren

source/build-charts.txt

@@ -33,3 +33,4 @@ To build a new chart:
       /sort-limit-data
       /customize-charts
       /sample-mode
+      /embedding-charts

source/data-sources.txt

@@ -20,6 +20,8 @@ source that the chart uses.
 To view, add, or remove data sources, click :guilabel:`Data Sources` on
 the top navigation bar.
 
+.. _data-sources-view:
+
 Data Sources View
 -----------------
 
@@ -201,6 +203,59 @@ To remove a data source:
    Any charts using the deleted data source will need to be
    reconfigured using a different data source or deleted.
 
+.. _data-source-embedding:
+
+Enable or Disable Embedding
+---------------------------
+
+As a data source ``Owner``, you can allow other people to
+:ref:`embed charts <embedding-charts>` which use your data source
+in external web pages. In order to allow a chart to be embedded
+in an external web page, you must enable embedding both on the
+data source and the individual chart.
+
+Embedding is disabled by default for all data sources. To enable
+embedding for a data source:
+
+1. Navigate to your :ref:`Data Sources View <data-sources-view>` page.
+
+#. Click the ellipsis (:guilabel:`...`) button on the far right side
+   of the desired data source.
+
+#. Select :guilabel:`Embedding Options` from the dropdown menu.
+
+#. Toggle the switch in the top right corner to :guilabel:`On`.
+
+#. Select either:
+
+   a. :guilabel:`Verified Signature only`. This option requires
+      embedded charts to include a :ref:`secret embedding key
+      <verified-signature>` with each request sent to the data source.
+      Without a verified signature, the chart will not render. This
+      option allows the chart owner to ensure that the chart is used
+      only in its intended context.
+
+      Generating a verified signature for authorized users to include
+      with their embedded charts requires some server-side code.
+      Examples in several languages and platforms are available with
+      the :ref:`verified signature documentation <verified-signature>`.
+
+   #. :guilabel:`Unauthenticated or Verified Signature`. This option
+      allows the chart to be viewed either with or without a verified
+      signature, so that anyone with the link may view the embedded
+      chart. It is simpler to implement than the verified signature
+      only option, but it is less secure. It should only be used for
+      charts which display non-sensitive data.
+
+After enabling embedding for a data source, you can enable embedding
+for individual charts which use that data source.
+
+.. note::
+
+   If you change the embedding option for a data source from
+   :guilabel:`On` to :guilabel:`Off`, all embedded charts which use
+   that data source will stop rendering immediately.
+
 .. class:: hidden
 
    .. toctree::

source/embedding-charts.txt

@@ -0,0 +1,155 @@
+.. _embedding-charts:
+
+========================================
+Embedding Charts in Your Web Application
+========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+As a dashboard Author, you can embed charts into your own web sites,
+allowing people who are not Charts users to see your visualizations.
+You can either require a verified signature to accompany each data
+request, or allow anyone with the chart's identifying information to
+embed it in a web page.
+
+If you want strict control over who can embed your charts, use the
+:ref:`Verified Signature <require-authentication>` option. If your data
+is non-sensitive and you prefer a simpler embedding solution, use the
+:ref:`Unauthenticated Access <allow-unauthenticated>` option. 
+
+.. _embedding-procedure:
+
+Procedure
+---------
+
+From your dashboard tab, select the dashboard containing the chart you
+wish to make embeddable. From the dashboard, click the ellipsis
+(:guilabel:`...`) button at the top-right of the chart to access its
+embedding information. Select :guilabel:`Embed Chart` from the dropdown
+menu.
+
+If you have not already enabled embedding for the data source this
+uses, and if you are the data source owner, you have the opportunity to
+do so now. Click the :guilabel:`Enable embedding options` link.
+
+.. figure:: /images/charts/embed-chart-options.png
+   :figwidth: 507px
+   :alt: Embed a chart
+
+Once the data source has embedding enabled, you can choose to allow
+unauthenticated access or restrict access to those with a
+:ref:`verified signature <require-authentication>`.
+
+.. figure:: /images/charts/embed-chart.png
+   :figwidth: 507px
+   :alt: Embed a chart
+
+.. _allow-unauthenticated:
+
+Allow Unauthenticated Access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To allow anyone with the chart link to embed the chart in a web page,
+select the :guilabel:`Unauthenticated` tab and toggle the switch marked
+:guilabel:`Enable unauthenticated access` to :guilabel:`On`. The HTML
+code necessary to embed the chart appears in the modal window. This
+HTML snippet is ready to copy and paste into an external web page.
+
+.. figure:: /images/charts/embed-chart2.png
+   :figwidth: 508px
+   :alt: Embed unauthenticated chart
+
+.. _require-authentication:
+
+Require Authentication for Access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For increased security, you can require a verified signature to
+accompany each data request for an embedded chart. Select the
+:guilabel:`Verified Signature` tab and toggle the :guilabel:`Enable
+signed authentication acces` switch to :guilabel:`On`.
+
+.. figure:: /images/charts/embed-chart3.png
+   :figwidth: 508px
+   :alt: Embed authenticated chart
+
+In addition to the HTML iframe, the verified signature option requires
+some server-side code in order to work. The HTML snippet above shows
+what the iframe needs to look like, but it is not usable as-is.
+Your web application must use a secret embedding key to sign the URL
+and include a timestamp.
+
+.. _verified-signature:
+
+Verified Signature Generation
+-----------------------------
+
+To grant data access for embedded charts which require authentication,
+you must obtain an embedding key from the :guilabel:`Admin Settings`
+page.
+
+.. note::
+
+   You must be a :ref:`Project Owner <dashboard-permissions>` to access
+   the :guilabel:`Admin Settings` page. For users with the
+   :ref:`Project Owner <dashboard-permissions>` role, the
+   :guilabel:`Admin Settings` link appears in the top right corner of
+   the charts UI. As a non-admin user, you can still use embedded
+   charts, but you will need to ask a Project Owner for a key.
+
+Once you have a key, you can create the server-side code required to
+generate the verified signature which must accompany a data request
+from an embedded chart. Code examples of how to generate a verified
+signature are available for the following languages and platforms:
+
+- `Node.js <https://github.com/mongodb/charts-embedding-examples/tree/master/node>`__
+- `C# <https://github.com/mongodb/charts-embedding-examples/tree/master/c-sharp>`__
+- `Java <https://github.com/mongodb/charts-embedding-examples/tree/master/java>`__
+- `Python <https://github.com/mongodb/charts-embedding-examples/tree/master/python>`__
+- `MongoDB Stitch <https://github.com/mongodb/charts-embedding-examples/tree/master/stitch>`__
+
+Embedded Charts Error Codes
+---------------------------
+
+If an embedded chart fails to render, an error code is displayed:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Error Code
+     - Error Cause
+
+   * - ``-1``
+     - Unknown error.
+
+   * - ``1``
+     - Invalid tenant ID. Check the ``tenant`` field in the iframe
+       HTML and make sure it matches what you see in the
+       :ref:`Embed Chart <embedding-procedure>` modal window. 
+
+   * - ``2``
+     - Item not found. Check the ``id`` field in the iframe
+       HTML and make sure it matches what you see in the
+       :ref:`Embed Chart <embedding-procedure>` modal window.
+
+   * - ``3``
+     - Embedding not enabled. Check the settings in your chart's
+       :ref:`Embed Chart <embedding-procedure>` modal window.
+
+   * - ``4``
+     - Embedding not allowed. Check the embedding settings in your
+       chart's :ref:`data source <data-source-embedding>`.
+
+   * - ``5``
+     - Invalid payload. Your application server is not creating a
+       usable :ref:`signature <verified-signature>`.