Skip to content

Commit 7a1e52f

Browse files
steverensteveren
authored
DOCSP-5341: [Charts] Update embedding docs based on feedback from S&T (#166)
* DOCSP-5341: [Charts] Update embedding docs based on feedback from S&T
1 parent b47cbee commit 7a1e52f

File tree

8 files changed

+194
-99
lines changed

8 files changed

+194
-99
lines changed

‎source/admin-settings.txt‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,25 +14,24 @@ Admin Settings
1414
:depth: 1
1515
:class: singlecol
1616

17-
To access the Admin Settings page, you must be a `Project Owner
17+
To access the Admin Settings page, you must be an Atlas `Project Owner
1818
<https://docs.atlas.mongodb.com/reference/user-roles/#project-roles>`__.
1919
If you have the Project Owner role, the :guilabel:`Admin Settings`
2020
link appears in the top right corner of the Charts UI.
2121

2222
Embedding Key Generation
2323
------------------------
2424

25-
Embedding keys are necessary for :ref:`verified signature
26-
<verified-signature>` generation, and are used in conjunction
27-
with :doc:`embedded charts <embedding-charts>`. To generate a new
28-
embedding key, click the :guilabel:`Generate New Key` button on the
29-
right side of the page.
25+
Embedding keys are necessary for verified signature generation, and are
26+
used in conjunction with :doc:`embedded charts <embedding-charts>`. To
27+
generate a new embedding key, click the :guilabel:`Generate New Key`
28+
button on the right side of the page.
3029

3130
.. warning::
3231

3332
If you generate a new key, any previous keys become invalid. Ensure
34-
that all the embedded charts which use the old key are updated to
35-
use the new key.
33+
that all the existing embedded charts that use the old key are
34+
updated to use the new key.
3635

3736
.. figure:: /images/charts/generate-new-key.png
3837
:figwidth: 650px

‎source/build-charts.txt‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,4 +33,3 @@ To build a new chart:
3333
/sort-limit-data
3434
/customize-charts
3535
/sample-mode
36-
/embedding-charts

‎source/data-sources.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -230,15 +230,15 @@ embedding for a data source:
230230

231231
a. :guilabel:`Verified Signature only`. This option requires
232232
embedded charts to include a :ref:`secret embedding key
233-
<verified-signature>` with each request sent to the data source.
233+
<embedding-charts>` with each request sent to the data source.
234234
Without a verified signature, the chart will not render. This
235235
option allows the chart owner to ensure that the chart is used
236236
only in its intended context.
237237

238238
Generating a verified signature for authorized users to include
239239
with their embedded charts requires some server-side code.
240240
Examples in several languages and platforms are available with
241-
the :ref:`verified signature documentation <verified-signature>`.
241+
the :ref:`verified signature documentation <embedding-charts>`.
242242

243243
#. :guilabel:`Unauthenticated or Verified Signature`. This option
244244
allows the chart to be viewed either with or without a verified

‎source/embedding-charts.txt‎

Lines changed: 28 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -9,113 +9,53 @@ Embedding Charts in Your Web Application
99
.. contents:: On this page
1010
:local:
1111
:backlinks: none
12-
:depth: 1
12+
:depth: 2
1313
:class: singlecol
1414

1515
Overview
1616
--------
1717

18-
As a dashboard :ref:`Author <dashboard-permissions>`, you can embed
19-
charts into your own web sites, allowing people who are not Charts
20-
users to see your visualizations. You can either require a verified
18+
As a dashboard :ref:`Author <dashboard-permissions>`, you can enable
19+
embedding on your charts, allowing your visualizations to be embedded
20+
in external web sites. You can either require a verified
2121
signature to accompany each data request, or allow anyone with the
2222
chart's identifying information to embed it in a web page.
2323

2424
If you want strict control over who can embed your charts, use the
25-
:ref:`Verified Signature <require-authentication>` option. If your data
25+
:guilabel:`Verified Signature Required` option. If your data
2626
is non-sensitive and you prefer a simpler embedding solution, use the
27-
:ref:`Unauthenticated Access <allow-unauthenticated>` option.
27+
:guilabel:`Unauthenticated Access` option.
28+
29+
.. note::
30+
31+
You can enable chart embedding with the verified signature
32+
required option even if you don't currently have an :ref:`embedding
33+
key <admin-settings>`, but you'll need a key to generate a
34+
verified signature. If you are a `Project Owner
35+
<https://docs.atlas.mongodb.com/reference/user-roles/#project-roles>`__
36+
for your Atlas project, you can generate an embedding key on the
37+
:ref:`Admin Settings <admin-settings>` page. Otherwise, you must
38+
contact the Atlas Project Owner and ask for an embedding key.
2839

2940
.. _embedding-procedure:
3041

3142
Procedure
3243
---------
3344

34-
From your dashboard tab, select the dashboard containing the chart you
35-
wish to make embeddable. From the dashboard, click the ellipsis
36-
(:guilabel:`...`) button at the top-right of the chart to access its
37-
embedding information. Select :guilabel:`Embed Chart` from the dropdown
38-
menu.
39-
40-
If you have not already enabled embedding for the data source this
41-
uses, and if you are the data source owner, you have the opportunity to
42-
do so now. Click the :guilabel:`Enable embedding options` link.
43-
44-
.. figure:: /images/charts/embed-chart-options.png
45-
:figwidth: 507px
46-
:alt: Embed a chart
47-
48-
Once the data source has embedding enabled, you can choose to allow
49-
unauthenticated access or restrict access to those with a
50-
:ref:`verified signature <require-authentication>`.
51-
52-
.. figure:: /images/charts/embed-chart.png
53-
:figwidth: 507px
54-
:alt: Embed a chart
55-
56-
.. _allow-unauthenticated:
57-
58-
Allow Unauthenticated Access
59-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60-
61-
To allow anyone with the chart link to embed the chart in a web page,
62-
select the :guilabel:`Unauthenticated` tab and toggle the switch marked
63-
:guilabel:`Enable unauthenticated access` to :guilabel:`On`. The HTML
64-
code necessary to embed the chart appears in the modal window. This
65-
HTML snippet is ready to copy and paste into an external web page.
45+
.. tabs::
6646

67-
.. figure:: /images/charts/embed-chart2.png
68-
:figwidth: 508px
69-
:alt: Embed unauthenticated chart
70-
71-
.. _require-authentication:
72-
73-
Require Authentication for Access
74-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75-
76-
For increased security, you can require a verified signature to
77-
accompany each data request for an embedded chart. Select the
78-
:guilabel:`Verified Signature` tab and toggle the :guilabel:`Enable
79-
signed authentication acces` switch to :guilabel:`On`.
80-
81-
.. figure:: /images/charts/embed-chart3.png
82-
:figwidth: 508px
83-
:alt: Embed authenticated chart
84-
85-
In addition to the HTML iframe, the verified signature option requires
86-
some server-side code in order to work. The HTML snippet above shows
87-
what the iframe needs to look like, but it is not usable as-is.
88-
Your web application must use a secret embedding key to sign the URL
89-
and include a timestamp.
90-
91-
.. _verified-signature:
92-
93-
Verified Signature Generation
94-
-----------------------------
95-
96-
To grant data access for embedded charts which require authentication,
97-
you must obtain an embedding key from the
98-
:ref:`Admin Settings <admin-settings>` page.
99-
100-
.. note::
47+
tabs:
48+
- id: unauthenticated
49+
name: Unauthenticated Access
50+
content: |
10151

102-
You must be a :ref:`Project Owner <dashboard-permissions>` to access
103-
the :guilabel:`Admin Settings` page. For users with the
104-
:ref:`Project Owner <dashboard-permissions>` role, the
105-
:guilabel:`Admin Settings` link appears in the top right corner of
106-
the charts UI. As a non-admin user, you can still use embedded
107-
charts, but you will need to ask a Project Owner for a key.
52+
.. include:: /includes/steps/embed-chart-unauthenticated.rst
10853

109-
Once you have a key, you can create the server-side code required to
110-
generate the verified signature which must accompany a data request
111-
from an embedded chart. Code examples of how to generate a verified
112-
signature are available for the following languages and platforms:
54+
- id: verified-signature
55+
name: Verified Signature Required
56+
content: |
11357

114-
- `Node.js <https://github.com/mongodb/charts-embedding-examples/tree/master/node>`__
115-
- `C# <https://github.com/mongodb/charts-embedding-examples/tree/master/c-sharp>`__
116-
- `Java <https://github.com/mongodb/charts-embedding-examples/tree/master/java>`__
117-
- `Python <https://github.com/mongodb/charts-embedding-examples/tree/master/python>`__
118-
- `MongoDB Stitch <https://github.com/mongodb/charts-embedding-examples/tree/master/stitch>`__
58+
.. include:: /includes/steps/embed-chart-verified.rst
11959

12060
Embedded Charts Error Codes
12161
---------------------------
@@ -152,4 +92,4 @@ If an embedded chart fails to render, an error code is displayed:
15292

15393
* - ``5``
15494
- Invalid payload. Your application server is not creating a
155-
usable :ref:`signature <verified-signature>`.
95+
usable :ref:`signature <admin-settings>`.

‎source/images/charts/embed-chart4.png‎

28.5 KB
Loading

‎source/includes/steps-embed-chart-unauthenticated.yaml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Select a dashboard.
3+
ref: select-dashboard
4+
level: 4
5+
content: |
6+
7+
From your dashboard tab, select the dashboard containing the chart
8+
you wish to make embeddable.
9+
---
10+
title: Select a chart.
11+
ref: select-chart
12+
level: 4
13+
content: |
14+
15+
From the dashboard, click the ellipsis (:guilabel:`...`) button at
16+
the top-right of the chart to access its embedding information.
17+
Select :guilabel:`Embed Chart` from the dropdown menu.
18+
---
19+
title: Enable embedding on the data source
20+
ref: enable-data-source
21+
level: 4
22+
content: |
23+
24+
If you have already enabled embedding on the data source this chart
25+
uses, you can skip this step. If you haven't yet enabled embedding
26+
on the data source, you can do so now. Click the :guilabel:`Enable
27+
embedding options` link.
28+
---
29+
title: Select the :guilabel:`Unauthenticated` tab in the dialog window.
30+
ref: select-unauthenticated
31+
level: 4
32+
content: |
33+
34+
.. figure:: /images/charts/embed-chart.png
35+
:figwidth: 508px
36+
:alt: Embed unauthenticated chart
37+
---
38+
title: Toggle the switch marked :guilabel:`Enable unauthenticated
39+
access` to :guilabel:`On`.
40+
ref: toggle-unauthenticated-on
41+
level: 4
42+
content: |
43+
44+
The HTML code necessary to embed the chart appears in the modal
45+
window. This HTML snippet is ready to copy and paste into an
46+
external web page.
47+
48+
.. figure:: /images/charts/embed-chart2.png
49+
:figwidth: 508px
50+
:alt: Embed unauthenticated chart
51+
52+
...

‎source/includes/steps-embed-chart-verified.yaml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Select a dashboard.
3+
ref: select-dashboard-verified
4+
level: 4
5+
content: |
6+
7+
From your dashboard tab, select the dashboard containing the chart
8+
you wish to make embeddable.
9+
---
10+
title: Select a chart.
11+
ref: select-chart-verified
12+
level: 4
13+
content: |
14+
15+
From the dashboard, click the ellipsis (:guilabel:`...`) button at
16+
the top-right of the chart to access its embedding information.
17+
Select :guilabel:`Embed Chart` from the dropdown menu.
18+
---
19+
title: Enable embedding on the data source
20+
ref: enable-data-source-verified
21+
level: 4
22+
content: |
23+
24+
If you have already enabled embedding on the data source this chart
25+
uses, you can skip this step. If you haven't yet enabled embedding
26+
on the data source, you can do so now. Click the :guilabel:`Enable
27+
embedding options` link.
28+
---
29+
title: Select the :guilabel:`Verified Signature` tab in the dialog
30+
window.
31+
ref: select-verified
32+
level: 4
33+
content: |
34+
35+
.. figure:: /images/charts/embed-chart4.png
36+
:figwidth: 508px
37+
:alt: Embed unauthenticated chart
38+
---
39+
title: Toggle the switch marked :guilabel:`Enable signed authentication
40+
access` to :guilabel:`On`.
41+
ref: toggle-verified-on
42+
level: 4
43+
content: |
44+
45+
The HTML code which appears in the modal window shows the parameters
46+
which are required to embed a chart with authentication enabled, but
47+
it is not usable as-is. Continue with the subsequent steps to
48+
enable authenticated access.
49+
---
50+
title: Go to :guilabel:`Admin Settings` to acquire an embedding key.
51+
ref: go-to-admin-settings
52+
level: 4
53+
content: |
54+
55+
Click the :guilabel:`Admin Settings` link below the HTML code
56+
snippet in the modal window.
57+
58+
.. note::
59+
60+
You must be a :ref:`Project Owner <dashboard-permissions>` to
61+
access the :guilabel:`Admin Settings` page. For users with the
62+
Project Owner role, the :guilabel:`Admin Settings` link appears
63+
in the top right corner of the charts UI. As a non-admin user,
64+
you can still use embedded charts, but you will need to ask a
65+
Project Owner for a key.
66+
---
67+
title: Generate an embedding key.
68+
ref: generate-key
69+
level: 4
70+
content: |
71+
72+
Click the :guilabel:`Generate New Key` button to create a new
73+
embedding key. Store the key in a safe place.
74+
75+
.. warning::
76+
77+
If you generate a new key, any previous keys become invalid. Ensure
78+
that all the existing embedded charts that use the old key are
79+
updated to use the new key.
80+
---
81+
title: Create the server-side code necessary for a verified
82+
signature.
83+
ref: server-side-code
84+
level: 4
85+
content: |
86+
87+
Generating a verified signature to accompany data requests from
88+
embedded charts with authentication enabled requires server-side
89+
code. The verified signature creates a payload by generating a
90+
`HMAC <https://en.wikipedia.org/wiki/HMAC>`__ from your embedding
91+
key, a timestamp, and identifying data from your chart. The verified
92+
signature is valid for a limited time period specified in your
93+
server-side code.
94+
95+
Code examples demonstrating how to generate a verified
96+
signature are available for the following languages and platforms:
97+
98+
- `Node.js <https://github.com/mongodb/charts-embedding-examples/tree/master/node>`__
99+
- `C# <https://github.com/mongodb/charts-embedding-examples/tree/master/c-sharp>`__
100+
- `Java <https://github.com/mongodb/charts-embedding-examples/tree/master/java>`__
101+
- `Python <https://github.com/mongodb/charts-embedding-examples/tree/master/python>`__
102+
- `MongoDB Stitch <https://github.com/mongodb/charts-embedding-examples/tree/master/stitch>`__
103+
104+
...

‎source/index.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@ uses this region to calculate the fees.
147147
/data-sources
148148
/build-charts
149149
/chart-types
150+
Chart Embedding </embedding-charts>
150151
/admin-settings
151152
/release-notes
152153
/third-party-licenses

0 commit comments

Comments
 (0)