Embedding private objects
Note
This feature is only available with the Business service plan.
You can securely embed private charts or dashboards into a website or app using special JWT token
Embedding private objects only works in the new DataLens object model at the workbook level and is only available to the workbook administrator.
You cannot embed private objects based on the following connections:
-
Note
You can share a dashboard or chart based on Yandex Metrica or AppMetrica data.
How to embed a private object
-
Create a key for embedding:
Note
You can use one key to embed multiple objects.
-
Go to the DataLens home page
. -
In the left-hand panel, select
Collections and workbooks. -
Open the workbook with the object you want to embed.
-
At the top of the screen, click
and select Keys for embedding. -
In the window that opens:
-
Click
Create key. -
Enter the key name and click Create.
-
At the bottom, click Download key file or copy the key value.
Warning
After you close the window, all data from it will be lost.
The new key for embedding will appear in the list.
-
-
-
Configure the embedding for a private object:
Note
You can configure multiple embeddings for each object.
-
In the row with the object, click
and select Embedding settings. -
In the window that opens, click
New embedding. -
In the settings window, specify:
For a chartFor a dashboard-
Name: Enter a name for the embedding.
-
Key: Select a previously created key for embedding.
-
Select Default parameters:
- Enable all (default): All the unsigned parameters are enabled, unless explicitly disabled.
- Disable all: All the unsigned parameters are disabled, unless explicitly enabled.
These restrictions do not apply to signed parameters from the token.
-
(Optional) Disabled parameters: Specify the names of unsigned parameters you want to disable when embedding a chart. Available in Enable all mode.
-
(Optional) Enabled parameters: Specify the names of unsigned parameters that can be provided in the embedding link. Any parameters not specified in the list will be ignored when attempting to provide them in the embedding link. Available in Disable all mode.
- Name: Enter a name for the embedding.
- Key: Select a previously created key for embedding.
- (Optional) Disabled parameters: Specify the names of unsigned parameters you want to disable when embedding a dashboard. These restrictions do not apply to signed parameters from the token. By default, any parameters specified in the dashboard settings can be provided in the embedding link.
-
-
Click Create. In the ID column, copy the ID of the object to embed, and then click Close.
-
-
Create a token:
-
Prepare a payload for the token, i.e., information about the object to embed. The payload contains the following fields:
-
embedId
: ID of the object to embed. -
iat
: JWT issue time in Unix Timestamp format. -
exp
: Token expiration time in Unix Timestamp format.Warning
Tokens with more than 10 hours between
exp
andiat
are invalid. -
dlEmbedService
: Service ID string constant,YC_DATALENS_EMBEDDING_SERVICE_MARK
. -
(Optional)
params
: Signed chart parameters provided as part of the token. They cannot be changed without regenerating the token.Example:
{ "embedId": "ieez7********", "iat": 1516239022, "exp": 1516240822, "dlEmbedService": "YC_DATALENS_EMBEDDING_SERVICE_MARK", "params": { "param1": "value1", "param2": "value2" } }
-
-
To create a JWT token, sign the prepared payload with the private key you got earlier when creating the key for embedding.
Note
Use the
PS256
algorithm when creating the JWT.To create a JWT token, use these code samples:
PythonNode.jsGoInstall
cryptography
for working withPS256
:pip3 install cryptography
Run the following code:
import time import jwt import json private_key = b"""<private_key>""" now = int(time.time()) payload = { 'embedId': "<embed_object_ID>", 'dlEmbedService': "YC_DATALENS_EMBEDDING_SERVICE_MARK", 'iat': now, 'exp': now + 360, "params": { }} # JWT generation. encoded_token = jwt.encode( payload, private_key, algorithm='PS256', ) print(encoded_token)
Install the jsonwebtoken
package using npm :npm install jsonwebtoken
Run the following code:
const privateKey = `<private_key>`; const now = Math.floor(Date.now() / 1000); const payload = { embedId: '<embed_object_ID>', dlEmbedService: 'YC_DATALENS_EMBEDDING_SERVICE_MARK', iat: now, exp: now + 360, params: {}, }; const jwt = require('jsonwebtoken'); const encodedToken = jwt.sign(payload, privateKey, { algorithm: 'PS256', }); console.log(encodedToken);
Install the jwt-go
package:go install github.com/golang-jwt/jwt/v5@latest
Run the following code:
package main import ( "fmt" "time" "github.com/golang-jwt/jwt/v5" ) func main() { privateKey, err := jwt.ParseRSAPrivateKeyFromPEM([]byte(`<private_key>`)) now := time.Now().Unix() payload := jwt.MapClaims{ "embedId": "<embed_object_ID>", "dlEmbedService": "YC_DATALENS_EMBEDDING_SERVICE_MARK", "iat": now, "exp": now + 360, "params": map[string]interface{}{}, } token := jwt.NewWithClaims(jwt.SigningMethodPS256, payload) signedToken, err := token.SignedString(privateKey) if err != nil { fmt.Println("Error generating token:", err) return } fmt.Println(signedToken) }
-
Generate an embedding link:
For a chartFor a dashboardhttps://datalens.yandex.cloud/embeds/chart#dl_embed_token=<token>
Where
<token>
is the JWT token.https://datalens.yandex.cloud/embeds/dash#dl_embed_token=<token>
Where
<token>
is the JWT token.
-
-
Add an embedding link to your website or app, e.g.:
For a chartFor a dashboard<iframe src="https://datalens.yandex.cloud/embeds/chart#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>
Where:
src
: Embedding URL.<token>
: JWT token.width
: Chart width.height
: Chart height.frameborder
: Chart border (yes or no).
<iframe src="https://datalens.yandex.cloud/embeds/dash#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>
Where:
src
: Embedding URL.<token>
: JWT token.width
: Dashboard width.height
: Dashboard height.frameborder
: Dashboard border (yes or no).
Unsigned parameters
By default, any parameters, except those explicitly disabled, can be provided in the embedding link. They should be specified in the URL before the token hash. This allows you to change some widget/dashboard parameters on the client side without recreating the token.
For example, where a chart or dashboard employs the from
and/or to
parameters to filter values by time, you can provide these parameters in the embedding link before the token hash:
<iframe src="https://datalens.yandex.cloud/embeds/chart?from=2022-01-01&to=2023-02-05#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>
Where:
src
: Embedding URL.<token>
: JWT token.from=2022-01-01&to=2023-02-05
: Unsigned parameters.
<iframe src="https://datalens.yandex.cloud/embeds/dash?from=2022-01-01&to=2023-02-05#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>
Where:
src
: Embedding URL.<token>
: JWT token.from=2022-01-01&to=2023-02-05
: Unsigned parameters.
In the embedding link, any unsigned parameters are ignored if:
- The parameter is listed among the parameters disabled in Enable all mode.
- The parameter is not listed among the parameters enabled in Disable all mode.
The parameter names are in the list of disabled parameters.
Recommendations
When embedding private objects, please follow these guidelines:
-
Default values should be provided in the link parameters.
-
Note that any parameter in the link will override any signed parameter with the same name.
-
To block changes to a parameter value:
For a chartFor a dashboard-
Add a signed parameter with a required value into the token.
-
In chart embedding settings:
- In Enable all mode, add the parameter to the disabled list.
- In Disable all mode, do not add the parameter to the enabled list.
- Add a signed parameter with a required value into the token.
- In the dashboard embedding settings, add the parameter to the disabled list.
-
Things to consider when embedding dashboards
When embedding dashboards, consider the following:
- Any embedded dashboard can only be opened in view mode. The navigation bar and the
menu for charts are hidden. - When you open a dashboard, its settings apply.
- For any embedded dashboard, only the parameters specified in the dashboard settings are enabled.
- You cannot provide the state of filtered charts in the
state
parameter. - The embedding link may not contain a dashboard header.
- In the embedding link, use
tab
to specify the tab to open the dashboard on.