(DOCSP-7954): Whitelist filter fields for unauthenticated charts (#276)

jeff-allen-mongo · jeff-allen-mongo · commit 44cbf18c5250 · 2019-12-11T11:24:10.000-05:00
* (DOCSP-7954): Whitelist filter fields for unauthenticated charts * Updates per review * Updates per review pt 2
diff --git a/source/dashboard-permissions.txt b/source/dashboard-permissions.txt
@@ -35,8 +35,14 @@ following dashboard permissions are available:
        ``Viewers`` cannot make any modifications to the dashboard.
 
    * - Author
-     - Can add, modify, or delete charts, change dashboard layout, and
-       rename the dashboard.
+     - Can perform the following actions:
+     
+       - Add, modify, and delete charts,
+       - Specify which fields can be used for
+         :ref:`Unauthenticated embedded chart filters
+         <specify-filter-fields>`,
+       - Change dashboard layout,
+       - Rename the dashboard.
 
    * - Owner
      - Has all privileges of ``Author`` and can also
diff --git a/source/embedded-chart-options.txt b/source/embedded-chart-options.txt
@@ -21,77 +21,197 @@ query parameters to their iframe URLs.
 
 .. _embed-options-filter:
 
-Specify a Filter
-----------------
+Filter Data on Embedded Charts
+------------------------------
 
 Use the ``filter`` query parameter to only display data in your
-embedded chart which matches a specified :abbr:`MQL (MongoDB Query Language)`
-filter.
+embedded chart which matches a specified
+:abbr:`MQL (MongoDB Query Language)` filter.
 
-.. important::
+You can use the ``filter`` query parameter on both Unauthenticated
+charts and charts which require a Verified Signature. The filtering
+behavior differs with each authentication setting:
 
-   For security reasons, the ``filter`` query parameter can only be used
-   on charts embedded with a
-   :ref:`Verified Signature <embedding-procedure>`. You should generate
-   your ``filter`` in your server-side code, rather than receiving
-   it from the client. Generating the filter from the server
-   prevents the client from modifying the filter and potentially
-   accessing restricted data.
+- With Unauthenticated charts, the chart
+  :ref:`Author <dashboard-roles>` specifies the fields that can be
+  included in filters set by the embedding application code or added by
+  chart viewers. To learn how to specify filterable fields, see
+  :ref:`Specify Filterable Fields <specify-filter-fields>`.
 
-Syntax
-~~~~~~
+- With charts which require a Verified Signature, all document
+  fields can be filtered upon, however you must generate
+  the filter in the server-side code and include the filter as part of
+  your signed payload.
 
-Specify an MQL document as your ``filter`` query parameter. Use the
-same syntax used in the :ref:`query bar <query-bar>` in the Chart
-Builder.
+.. _specify-filter-fields:
 
-MQL queries contain characters that must be URL-encoded before
-your server-side code calculates the verified signature.
-When |charts-short| verifies the signature, it URL-encodes the filter
-again using the JavaScript
-`encodeURIComponent
-<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent>`__
-function. You must use the same encoding algorithm to encode your
-filter.
+Specify Filterable Fields (Unauthenticated Charts Only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. important::
+A chart :ref:`Author <dashboard-roles>` specifies the fields that can be
+included in filters set by the embedding application code or added by
+chart viewers. Use these fields to restrict the data that viewers can
+access. By default, no fields are whitelisted, meaning the chart cannot
+be filtered until you explicitly whitelist at least one field.
 
-   You must encode spaces in your filter as ``%20``, rather than ``+``
-   or a raw space.
+To define filterable fields:
 
-To see how correctly encode an MQL filter using different server-side
-programming languages, see `MongoDB Charts Embedding Examples
-<https://github.com/mongodb/charts-embedding-examples>`__ on GitHub.
+1. Navigate to the :ref:`dashboard <dashboards>` that contains the chart
+   where you wish to define filterable fields.
 
-Example
-~~~~~~~
+#. For the desired chart, click the :icon-fa5:`ellipsis-h` button and
+   select :guilabel:`Embed Chart` from the dropdown.
+
+#. In the :guilabel:`User Specified Filters` section, use the
+   dropdown to select which fields chart viewers can use filter data
+   in the chart. You can also manually type values to add fields not
+   listed in the dropdown.
+
+   .. note::
+   
+      This option only appears if you already have
+      :guilabel:`Unauthenticated` embedding access enabled.
+
+#. When you have selected all desired fields, click :guilabel:`Save`
+   below the dropdown.
+
+Chart :ref:`viewers <dashboard-roles>` and applications which render
+the chart can now specify filters based on the whitelisted fields to
+display subsets of the original chart data. If a viewer attempts to
+specify a filter using a field not in the whitelist, an
+:ref:`error <embedded-errors>` is returned.
+
+.. topic:: Filters for Embedded Documents
+
+   When you whitelist a field whose value is an embedded document, you
+   must specify each individual sub-field you wish to add to the
+   whitelist.
+
+   .. example::
+
+      Consider the following document:
+
+      .. code-block:: json
+
+         {
+           "name": "Alice",
+           "favorites" : 
+           {
+             "color": "green",
+             "animal": "turtle",
+             "season": "autumn"
+           } 
+         }
+
+   If you only add the ``favorites`` field to the whitelist, it does
+   *not* grant viewers permission to filter upon any of the sub-fields
+   of ``favorites``. Instead, you may add one or more of the sub-fields
+   individually to the whitelist by specifying ``favorites.color``,
+   ``favorites.animal``, or ``favorites.season``.
+
+
+
+Filter Syntax
+~~~~~~~~~~~~~
+
+Select the appropriate tab to see an example of how to filter data in
+an Unauthenticated chart and a Verified Signature chart:
+
+.. tabs::
+
+   tabs:
+     - id: unauthenticated
+       name: Unauthenticated External Sharing
+       content: |
+
+         You can specify an MQL document as your ``filter`` query
+         parameter provided that the fields used in your filter are in
+         the
+         :ref:`whitelist of filterable fields <specify-filter-fields>`.
+
+         .. include:: /includes/fact-embedded-filter-examples-unauth.rst
+
+         .. note::
+
+            You must URL-encode special characters of the filter
+            parameter.
+
+         Example
+         ```````
+
+         The following iframe ``src`` URL renders a chart which only
+         displays documents with an ``imdb.rating`` greater than or
+         equal to ``8``:
+
+         .. code-block:: none
+            :emphasize-lines: 4
+
+            https://charts.mongodb.com/charts-atlasproject1-piocy/embed/charts?
+            id=93584ddb-1115-4a12-afd9-5129e47bbb0d&
+            tenant=3397ee6d-5079-4a20-b097-cedd475220b5&
+            filter={"imdb.rating":%20{$gte:%208}}&
+            autorefresh=30
+
+         The URL uses an encoded ``filter`` parameter of
+         ``{"imdb.rating":%20{$gte:%208}}``. Decoded,
+         this filter is:
+
+         .. code-block:: json
+
+            {"imdb.rating": {$gte: 8}}
+
+     - id: verified-signature
+       name: Verified Signature Required
+       content: |
+
+         Specify an MQL document as your ``filter`` query parameter.
+
+         .. include:: /includes/fact-embedded-filter-examples-verified.rst
+
+         When using filters in a Verified Signature, MQL queries contain
+         characters that must be URL-encoded before your server-side
+         code calculates the signature. When |charts-short| verifies the
+         signature, it URL-encodes the filter again using the JavaScript
+         `encodeURIComponent
+         <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent>`__
+         function. You must use the same encoding algorithm to encode
+         your filter.
+
+         .. important::
+
+            You must encode spaces in your filter as ``%20``, rather than ``+``
+            or a raw space.
+
+         To see how correctly encode an MQL filter using different server-side
+         programming languages, see `MongoDB Charts Embedding Examples
+         <https://github.com/mongodb/charts-embedding-examples>`__ on GitHub.
 
-The following iframe ``src`` URL renders a chart which only displays
-documents with an ``imdb.rating`` greater than or equal to ``8``:
+         Example
+         ```````
 
-.. code-block:: none
-   :emphasize-lines: 6
+         The following iframe ``src`` URL renders a chart which only
+         displays documents with an ``imdb.rating`` greater than or
+         equal to ``8``:
 
-   https://charts.mongodb.com/charts-atlasproject1-piocy/embed/charts?
-   id=93584ddb-1115-4a12-afd9-5129e47bbb0d&
-   tenant=3397ee6d-5079-4a20-b097-cedd475220b5&
-   timestamp=1564156636&
-   expires-in=300&
-   filter=%7B%22imdb.rating%22%3A%20%7B%24gte%3A%208%7D%7D&
-   autorefresh=30&
-   signature=8e0d92b33934c928f6c6974e2f0102ace77f56d851cb0d33893e84c359ab1043
+         .. code-block:: none
+            :emphasize-lines: 6
 
-The URL uses an encoded ``filter`` parameter of
-``%7B%22imdb.rating%22%3A%20%7B%24gte%3A%208%7D%7D``. Decoded, this
-filter is:
+            https://charts.mongodb.com/charts-atlasproject1-piocy/embed/charts?
+            id=93584ddb-1115-4a12-afd9-5129e47bbb0d&
+            tenant=3397ee6d-5079-4a20-b097-cedd475220b5&
+            timestamp=1564156636&
+            expires-in=300&
+            filter=%7B%22imdb.rating%22%3A%20%7B%24gte%3A%208%7D%7D&
+            autorefresh=30&
+            signature=8e0d92b33934c928f6c6974e2f0102ace77f56d851cb0d33893e84c359ab1043
 
-.. code-block:: json
+         The URL uses an encoded ``filter`` parameter of
+         ``%7B%22imdb.rating%22%3A%20%7B%24gte%3A%208%7D%7D``. Decoded,
+         this filter is:
 
-   {"imdb.rating": {$gte: 8}}
+         .. code-block:: json
 
-The server-side code creates a payload with the necessary information
-to render the chart, including the filter. The payload ensures that
-the verified signature is valid before rendering the chart.
+            {"imdb.rating": {$gte: 8}}
 
 .. _embed-options-refresh:
 
diff --git a/source/embedding-charts.txt b/source/embedding-charts.txt
@@ -29,8 +29,8 @@ is non-sensitive and you prefer a simpler external sharing solution, use the
    You can enable external sharing for your chart with the verified
    signature required option even if you don't currently have an
    :ref:`external sharing key <admin-settings>`, but you'll need a key
-   to generate a verified signature. If you
-   :atlas:`own </reference/user-roles#project-roles>` for your
+   to generate a verified signature. If you are a 
+   :atlas:`Project Owner </reference/user-roles#project-roles>` of your
    |service| project, you can generate an external sharing key on the
    :ref:`Admin Settings <admin-settings>` page. Otherwise, you must
    contact the |service| Project Owner and ask for an external sharing
@@ -100,9 +100,15 @@ If an shared chart fails to render, an error code is displayed:
        value must be an integer greater than 0.
 
    * - ``7``
-     - :ref:`Filter <embed-options-filter>` not allowed. A ``filter``
-       parameter was specified for a chart using anonymous embedding.
-       Filters can only be used with verified signatures.
+     - :ref:`Filter <embed-options-filter>` not allowed. When filtering
+       an Unauthenticated embedded chart, the fields used in the filter
+       must be present in the
+       :ref:`filter whitelist <specify-filter-fields>`. Additionally,
+       filters on both Unauthenticated and Verified Signature embedded
+       charts cannot use non-logical operators before a field name
+       (e.g., :manual:`$expr </reference/operator/query/expr/>`,
+       :manual:`$where </reference/operator/query/where/>`, or
+       :manual:`$text </reference/operator/query/text/>`).
 
    * - ``8``
      - :ref:`Filter <embed-options-filter>` not valid. A ``filter``
diff --git a/source/images/charts/embed-chart2.png b/source/images/charts/embed-chart2.png
diff --git a/source/includes/fact-embedded-filter-examples-unauth.rst b/source/includes/fact-embedded-filter-examples-unauth.rst
@@ -0,0 +1,22 @@
+Your filter must match the format used in a
+:manual:`$match </reference/operator/aggregation/match/>` query and
+be either a:
+
+- Top level query
+
+  .. example::
+
+     .. code-block:: json
+
+        { "quantity": { $gte: 20 } }
+
+- Or within boolean expressions (
+  :manual:`$and </reference/operator/query/and/>`,
+  :manual:`$nor </reference/operator/query/nor/>`,
+  :manual:`$or </reference/operator/query/or/>`)
+
+  .. example::
+
+     .. code-block:: json
+
+        { $or: [ { quantity: { $lt: 20 } }, { price: 10 } ] }
diff --git a/source/includes/fact-embedded-filter-examples-verified.rst b/source/includes/fact-embedded-filter-examples-verified.rst
@@ -0,0 +1,15 @@
+Your filter must match the format used in a
+:manual:`$match </reference/operator/aggregation/match/>` query as
+shown in the following examples:
+
+.. example::
+
+   .. code-block:: json
+
+      { "quantity": { $gte: 20 } }
+
+.. example::
+
+   .. code-block:: json
+
+      { $or: [ { quantity: { $lt: 20 } }, { price: 10 } ] }
