diff --git a/docs/add-functionality/add-functionality.md b/docs/add-functionality/add-functionality.md index 5be6ead7..55a4c74e 100644 --- a/docs/add-functionality/add-functionality.md +++ b/docs/add-functionality/add-functionality.md @@ -45,8 +45,8 @@ Once you have embedded a dashboard, you can use helper methods in the Embedding If you plan to use Embedding SDK on a web page on a different domain from your Strategy environment, please also meet the following requirements. More information in -1. [Enable Cross-Origin Resource Sharing (CORS)](../config.md) -1. [Allow SameSite cookies](../config.md#allow-samesite-cookies) +1. [Enable Cross-Origin Resource Sharing (CORS)](../configure-library-server/enable-cors.md) +1. [Allow SameSite cookies](../configure-library-server/enable-cors.md#allow-samesite-cookies) If you plan to use Embedding SDK on the same domain as your Strategy, the above changes are not required. diff --git a/docs/configure-library-server/client-telemetry.md b/docs/configure-library-server/client-telemetry.md new file mode 100644 index 00000000..15657a02 --- /dev/null +++ b/docs/configure-library-server/client-telemetry.md @@ -0,0 +1,62 @@ +--- +title: Track embedded usage with client telemetry +description: Enable client telemetry on the Library server so that usage of your embedded dashboards and widgets is recorded in Platform Analytics, separate from standard Library usage. +--- + + + +Client telemetry records what end users do inside embedded pages — dashboards, documents, reports, and visualizations — and sends the records to Platform Analytics. This allows you to measure adoption and engagement of your embedded analytics separately from standard Library usage. Both embedding surfaces are supported: the iframe-based Embedding SDK (`microstrategy.embeddingContexts`) and the Native Embedding SDK (`microstrategy.embeddingComponent`). + +Telemetry is disabled for embedded sessions until it is enabled on the Library server. No property or code change is required in your embedding application: the SDKs read the server configuration automatically. + +## How it works + +When an end user interacts with an embedded page, the Embedding SDK builds a telemetry record and hands it to the Platform Analytics telemetry pipeline. Each record identifies: + +- The embedding surface, through the `embed_mode_id` dimension: `1` for the iframe-based Embedding SDK and `2` for the Native Embedding SDK. Standard Library sessions are not tagged as embedded, so embedded usage can be filtered and compared in Platform Analytics. +- The embedding context, through `embed_context_uri`: the URL of your embedding page, without the query string. For iframe embedding, the Embedding SDK passes the host page's URL to the embedded page automatically. +- The target of the interaction: the project, the dashboard, and, for interactions on a specific visualization, the visualization name and id. + +The device and environment (browser, operating system, Library version) are recorded once per session. + +Record delivery is resilient: telemetry failures never block or break the embedding, and a record that fails to send immediately is buffered locally and retried. + +## Prerequisites + +1. Platform Analytics is deployed in your environment, and client telemetry is enabled for the project that contains the embedded content. Records are only sent for projects with client telemetry enabled in the Platform Analytics telemetry settings. +1. Enable telemetry for embedded sessions on the Library server. Navigate to `MicroStrategyLibrary/WEB-INF/classes/config/configOverride.properties` and add the following line, or replace it if already present: + + `features.telemetry.embedEnabled=true` + +1. Restart your Library web application hosted on the application server. + +Optionally, you can control how records are delivered with `features.telemetry.immediateSend` in the same properties file. When it is `true` (the default), each record is sent to Platform Analytics as soon as it completes; when it is `false`, records are buffered in the browser's IndexedDB and flushed when the user returns. + +## What is recorded + +### In iframe-embedded pages + +The following user interactions are recorded in pages embedded with the Embedding SDK: + +- Dashboard manipulations, such as filtering, sorting, drilling, and page switching, including the name and id of the visualization the user acted on. +- Link clicks: URL links, links to reports or documents, contextual links to the same or another dashboard, and links to a dashboard in another project. +- Toolbar and sharing actions: exporting to PDF, CSV, Excel, Google Sheets, or plain text, subscribing, applying a bookmark, answering prompts, copying a share link, posting a comment, viewing the data behind a visualization, and resetting the dashboard. + +### In natively embedded dashboards and visualizations + +For dashboards and visualizations embedded with the Native Embedding SDK: + +- Manipulations: sorting (including clearing a sort), drilling, keep-only and exclude, selectors, panel selectors, and showing totals, with the visualization name and id. When several dashboards are embedded on one page, each dashboard instance carries its own stable action id, so their records can be told apart. +- Link clicks, with the same link types as iframe embedding. + +Some interactions are intentionally not recorded in native embedding: page load and render events, and filtering applied through the SDK's `applyFilter` or `applyManipulations` APIs by the embedding application itself. Only direct end-user interactions are counted, so programmatic changes from the host application are not double-counted as usage. + +## View the data in Platform Analytics + +The records are written to the Platform Analytics client telemetry data. In the Client Telemetry reports, you can: + +- Filter usage by the `embed_mode_id` dimension to separate iframe-embedded usage, natively embedded usage, and standard Library usage. +- Break usage down by the embedding page (`embed_context_uri`), by dashboard, or by visualization. +- Review the interaction types, such as filter, sort, drill, export, and link clicks, with the recorded request duration of each manipulation. + +Since the host page URL is recorded without its query string, personal data that may be carried in query parameters is not collected. diff --git a/docs/configure-library-server/configure-library-server.md b/docs/configure-library-server/configure-library-server.md new file mode 100644 index 00000000..790676e6 --- /dev/null +++ b/docs/configure-library-server/configure-library-server.md @@ -0,0 +1,18 @@ +--- +title: Configure Library Server for embedding +description: The Library server supports additional configuration for embedding, including enabling Cross-Origin Resource Sharing (CORS), hiding irrelevant allowed origins in the Content-Security-Policy response header, and sending client telemetry for embedded sessions to Platform Analytics. +--- + +To embed Strategy content into your web application, the Library server can be configured to support cross-domain embedding, protect the domains configured in your security settings, and report usage of embedded content to Platform Analytics. + +- [Enable Cross-Origin Resource Sharing (CORS)](./enable-cors.md) + + If you use the Embedding SDK on a different domain from your Strategy environment, enable CORS on the Library server and allow SameSite cookies, so that the embedded pages can communicate with the Library server across domains. + +- [Hide irrelevant allowed origins in the CSP response header](./hide-irrelevant-allowed-origins.md) + + When multiple allowed origins are configured on the Library server, enable the `features.hideIrrelevantAllowOrigins` feature flag so that the `Content-Security-Policy` response header only exposes the allowed origins relevant to the current requester, and use wildcard allowed origins to cover subdomains. + +- [Track embedded usage with client telemetry](./client-telemetry.md) + + Enable the `features.telemetry.embedEnabled` feature flag so that usage of your embedded dashboards and widgets is recorded in Platform Analytics, separate from standard Library usage. diff --git a/docs/configure-library-server/enable-cors.md b/docs/configure-library-server/enable-cors.md new file mode 100644 index 00000000..2a2e7b72 --- /dev/null +++ b/docs/configure-library-server/enable-cors.md @@ -0,0 +1,99 @@ +--- +title: Enable Cross-Origin Resource Sharing (CORS) +description: If you plan to use Embedding SDK on a different domain from your Strategy environment, please enable Cross-Origin Resource Sharing (CORS) and allow SameSite cookies. +--- + +If you plan to use Embedding SDK on a different domain from your Strategy environment, please also meet the following requirements. + +## Enable Cross-Origin Resource Sharing (CORS) + +Cross-Origin Resource Sharing (CORS) provides a way for a web application running in one origin (domain, protocol, and port) to access selected resources from a server in a different origin. A cross-origin HTTP request uses additional HTTP headers to tell the browser to let the web application share resources. For security reasons, browsers restrict cross-origin HTTP requests initiated from within scripts. This means that when a web application requests HTTP resources from a different origin, the response from the other origin must include the right CORS headers. + +:::note + +Chrome Web Browser version 80 and above introduces new changes which may impact embedding. For more information, see [KB484005: Chrome v80 Cookie Behavior and the Impact on Strategy Deployments](https://community.strategy.com/article/Chrome-v80-Cookie-Behavior-and-the-impact-on-MicroStrategy-Deployments). + +::: + +To enable CORS for the REST Server: + +1. Open the Library Admin page. Your URL should be similar to the following: + + `https://:/MicroStrategyLibrary/admin` + +1. Navigate to **Library Server -> Security Settings**. +1. Choose the appropriate setting for **Allow Library embedding in other sites** to reconfigure CORS. + + ![Library Admin CORS Setting](../images/LibraryAdmin_CORSsetting.png) + +Using the Library Admin page is the easiest way to enable CORS for the REST Server, but you can also configure CORS manually. + +1. Navigate to `MicroStrategyLibrary/WEB-INF/classes/config/configOverride.properties`. +1. Edit the `configOverride.properties` file in a text editor. +1. Add the following lines, or replace them if already present: + + `auth.cors.origins=http://example.com:port` + + `security.allowedOrigins=http://example.com:port` + +1. Restart your Library web application hosted on the application server. + +Alternatively, you can also configure this in Workstation by [editing the properties of the environment](https://www2.microstrategy.com/producthelp/Current/Workstation/WebHelp/Lang_1033/Content/library_admin_settings.htm#View). + +## Allow SameSite cookies + +Google Chrome (version 80+) and Microsoft Edge (version 86+) introduced new changes that may impact embedding. + +For Embedding SDK to function as expected in a 3rd-party context, it is required to explicitly label session cookies with `SameSite=None; Secure`. + +### For MicroStrategy 2021 Update 6 or after + +Starting in MicroStrategy 2021 Update 6, you can manage SameSite Cookies for Library in Workstation, by following the steps in [this document](https://www2.microstrategy.com/producthelp/Current/Workstation/WebHelp/Lang_1033/Content/config_samesite_cookies.htm). + +![SameSite Cookie](../images/SameSiteCookie.png) + +### For MicroStrategy 2021 Update 5 or before + +If you are using MicroStrategy 2021 Update 5 or before, make the following changes on your server instance. + +1. If `context.xml` doesn't already exist in the following folder location, create it: `[Tomcat Folder]\webapps\MicroStrategyLibrary\META-INF\context.xml`. Add the following to `context.xml`: + + ```xml + + + + ``` + +1. In `[Tomcat Folder]\webapps\MicroStrategyLibrary\WEB-INF\web.xml`, change `sameSite` param-value blow to `NONE` to permit embedding. + + ```xml + + + cookieProcessorFilter + com.microstrategy.web.filter.CookieProcessorFilter + + sameSite + NONE + + + + ``` + +1. Ensure your Tomcat is configured to support HTTPS. +1. Restart Tomcat. + +For more information, see [Chrome v80 Cookie Behavior and the Impact on Strategy Deployments](https://community.microstrategy.com/s/article/Chrome-v80-Cookie-Behavior-and-the-impact-on-Strategy-Deployments?language=en_US). + +## The Partitioned Cookie Change + +Before MicroStrategy ONE June 2024, when the Library server and the client website are in different domains, the Embedding SDK requires third-party cookies to be allowed to work correctly. In the past, Chrome's default setting was only "Block third-party cookies in Incognito mode", so the customer can use Embedding SDK without changing the Chrome settings. + +![The default Chrome preference](../images/chrome-preference.png) + +However, third-party cookies are on their way out. Google is expected to stop the use of third-party cookies by [2025 Q2](https://developers.google.com/privacy-sandbox/3pcd). At that time, Chrome will block third-party cookies by default, and the customer can't use Embedding SDK unless he changes the Chrome preference to enable the 3rd party cookies manually. + +To avoid the changes of third-party cookies default setting breaking the Embedding SDK workflow, we adopt [CHIPS](https://developer.chrome.com/docs/privacy-sandbox/chips/)(Cookies Having Independent Partitioned State) solution to put the Library server's cookie into partitioned storage. The user needs to enable the partitioned cookie in the Library settings to use this solution: + +![The partitioned cookie setting](../images/partitioned-cookie.png) + +After this change, the customer can use most of the Embedding SDK functionalities even if 3rd party cookies are blocked in the Chrome preference. But for the SAML/OIDC login, the old workflow changes, and the user need to do more to make it work. The details can be seen in [SAML or OIDC authentication after MicroStrategy ONE June 2024](../support-for-different-authentication-environments/authentication-saml.md#for-microstrategy-one-june-2024-or-after). diff --git a/docs/configure-library-server/hide-irrelevant-allowed-origins.md b/docs/configure-library-server/hide-irrelevant-allowed-origins.md new file mode 100644 index 00000000..125ba045 --- /dev/null +++ b/docs/configure-library-server/hide-irrelevant-allowed-origins.md @@ -0,0 +1,90 @@ +--- +title: Hide irrelevant allowed origins in the CSP response header +description: Enable the features.hideIrrelevantAllowOrigins feature flag on the Library server so that the Content-Security-Policy response header only exposes the allowed origins relevant to the current requester, and use wildcard allowed origins to cover subdomains. +--- + + + +When the Library server has multiple allowed origins configured, the `Content-Security-Policy: frame-ancestors` response header of an embedded page lists all of them on every request. If one Library server serves several web applications or tenants, each application can discover the other applications' domains from the response header, which raises a privacy concern. The Library server can hide these irrelevant allowed origins so that each requester only sees the allowed origins relevant to itself. + +## Why the allowed origins are exposed + +To embed Strategy content into web applications hosted on different domains, you add those domains to the server's allowed origins. See [Enable Cross-Origin Resource Sharing (CORS)](./enable-cors.md). + +For a request to an embedded page, the server returns a response header similar to the following: + +```text +content-security-policy: +frame-ancestors 'self' local://plugins https://app1.example.com https://app2.example.com +``` + +Both `https://app1.example.com` and `https://app2.example.com` are listed even if the request comes from a page hosted on `https://app1.example.com` only. This discloses the domain of the second application to the first application's users. + +## How the filtering works + +The behavior is controlled by the server-side feature flag `features.hideIrrelevantAllowOrigins`, which is disabled (`false`) by default. When it is enabled: + +- The server keeps `'self'`, `local://plugins`, and the configured allowed origins that cover the current requester's embedding origin. A configured origin covers the requester when it matches the embedding origin exactly, or when it is a wildcard origin such as `https://*.example.com` and the embedding origin is a subdomain of it. All other configured allowed origins are removed from the response header. +- The requester's embedding origin is determined from the request's `Referer` header. The Embedding SDK also appends the embedding page's origin to the embedded iframe URL automatically, so the filtering still works when the iframe is redirected through the Library login page in non-custom authentication environments. No change to your embedding code is required. +- If the `Referer` header is absent, no filtering is applied and all configured allowed origins are listed, preserving the original behavior. +- For background API calls made with `XMLHttpRequest`, the server does not return the `frame-ancestors` directive at all, regardless of the flag. The directive has no meaning for a response consumed by script, and suppressing it avoids leaking the allowed origins list on API responses. + +With the flag enabled, a request from a page hosted on `https://app1.example.com` receives: + +```text +content-security-policy: +frame-ancestors 'self' local://plugins https://app1.example.com +``` + +## Enable the origin filtering on the Library server + +1. Navigate to `MicroStrategyLibrary/WEB-INF/classes/config/configOverride.properties` on the Library server. +1. Add the following line, or replace it if already present: + + `features.hideIrrelevantAllowOrigins=true` + +1. Restart your Library web application hosted on the application server. + +The flag applies to the whole server and to all types of embedded pages, including the Library home page, dashboard consumption pages, document consumption pages, report pages, and agent consumption pages. The Embedding SDK needs no new property or code change. + +## Use wildcard allowed origins + +Filtering by exact origin match requires one allowed origin entry per domain. When your applications are spread across subdomains, or the embedded page is nested inside intermediate iframes, you can configure a wildcard allowed origin instead, such as `https://*.example.com`. + +1. Configure the allowed origins in the same way as regular allowed origins. For example, add the following line to `MicroStrategyLibrary/WEB-INF/classes/config/configOverride.properties`: + + `security.allowedOrigins=https://*.example.com` + +1. Restart your Library web application hosted on the application server. + +The wildcard allowed origin follows these rules: + +- The protocol is required and the wildcard is only allowed as the leftmost label of the host, for example, `https://*.example.com`. +- It covers any subdomain at any depth, for example, `a.example.com` and `tenant.a.example.com`, but it does not cover the bare domain `example.com` itself. If the bare domain is also an embedding host, add it as a separate allowed origin entry. +- The protocol must match exactly. For example, `https://*.example.com` does not cover a page hosted on `http://a.example.com`. When a port is specified, the port must also match. + +For example, with `security.allowedOrigins=https://*.zebra.com` configured and the flag enabled, a nested embedding structure like the following still works: + +```text +-- root page with domain 'a.zebra.com' + -- intermediate iframe with domain 'b.zebra.com' + -- embedded Library page with domain 'lib.example.cloud.strategy.com' +``` + +The response's `frame-ancestors` value only contains `https://*.zebra.com`, which covers every ancestor page in the chain. + +:::warning Confirm your embedding structure before enabling the flag + +The filtering can break nested embedding when the pages in the iframe chain are hosted on different root domains. For example, a root page on `a.example.com` embeds an intermediate iframe on `b.other.com`, which embeds the Library page. The intermediate iframe's domain is the direct parent of the Library page, so the filtering keeps only the entry covering `b.other.com` and removes `a.example.com`. Since `frame-ancestors` requires every ancestor page in the chain to be allowed, the embedding stops working. + +Only enable `features.hideIrrelevantAllowOrigins` after you confirm that, in all of your embedding chains, the root page and any intermediate iframe are covered by the same wildcard allowed origin, or by the requester's exact allowed origin. + +::: + +When the flag is enabled, wildcard allowed origins are also honored when the server validates the host portal used in shared links, so a host portal on a subdomain of a wildcard entry can still be used. + +## Verify the filtering + +1. Open your embedding page in the browser and open the developer tools. +1. In the network tab, inspect the response of a request to the embedded page on the Library server. +1. Confirm that the `content-security-policy` header only contains `'self'`, `local://plugins`, and the allowed origin entries that cover the current embedding page, and that the embedded page still renders as expected. diff --git a/docs/index.md b/docs/index.md index fba7c578..6d472b95 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,7 +18,7 @@ There are three basic steps for embedding a dashboard. :::tip - If the application server is different from the server running the StrategyLibrary application, you may need to [perform additional configuration to support Cross-Origin Resource Sharing (CORS)](./config.md). + If the application server is different from the server running the StrategyLibrary application, you may need to [perform additional configuration to support Cross-Origin Resource Sharing (CORS)](./configure-library-server/enable-cors.md). ::: diff --git a/docs/support-for-different-authentication-environments/authentication-saml.md b/docs/support-for-different-authentication-environments/authentication-saml.md index 572a3f72..1752b3b2 100644 --- a/docs/support-for-different-authentication-environments/authentication-saml.md +++ b/docs/support-for-different-authentication-environments/authentication-saml.md @@ -33,7 +33,7 @@ You may encounter some difficulties in this workflow: ## For MicroStrategy ONE June 2024 or after -In MicroStrategy ONE June 2024, we add the [partitioned cookie change](../config#the-partitioned-cookie-change) to enable the customer to use the Embedding SDK even if third-party cookies are blocked. But if third-party cookies are blocked, the old SAML or OIDC login process can't work. +In MicroStrategy ONE June 2024, we add the [partitioned cookie change](../configure-library-server/enable-cors#the-partitioned-cookie-change) to enable the customer to use the Embedding SDK even if third-party cookies are blocked. But if third-party cookies are blocked, the old SAML or OIDC login process can't work. You can unblock the third-party cookies manually to support the old workflow, but we recommend you use the new [embedding auth APIs](../support-for-different-authentication-environments/new-authentication-apis.md), which can work in the third-party cookies blocked case, and simplify the SAML or OIDC login logic. You can see the examples in the [playground](https://microstrategy.github.io/playground/?example=g17). A simple code piece would be like this: diff --git a/docs/support-for-different-authentication-environments/guest-authentication-mode-only.md b/docs/support-for-different-authentication-environments/guest-authentication-mode-only.md index 23ad6104..e14a8a40 100644 --- a/docs/support-for-different-authentication-environments/guest-authentication-mode-only.md +++ b/docs/support-for-different-authentication-environments/guest-authentication-mode-only.md @@ -60,7 +60,7 @@ Because this simple embedding example uses a dashboard on the demo server, you a **To customize the example to use your Library Server**: -1. Decide where you want to have the HTML page. If the domain is different from your Library Server's domain, you may need to [perform additional configuration to support Cross-Origin Resource Sharing (CORS)](../config.md). +1. Decide where you want to have the HTML page. If the domain is different from your Library Server's domain, you may need to [perform additional configuration to support Cross-Origin Resource Sharing (CORS)](../configure-library-server/enable-cors.md). 1. In an IDE, text editor or [Embedding SDK Playground](https://microstrategy.github.io/playground/), open the HTML file and configure it to reflect the values in your environment: diff --git a/docs/support-for-different-authentication-environments/support-for-different-authentication-environments.md b/docs/support-for-different-authentication-environments/support-for-different-authentication-environments.md index 4439a5d2..2df50c43 100644 --- a/docs/support-for-different-authentication-environments/support-for-different-authentication-environments.md +++ b/docs/support-for-different-authentication-environments/support-for-different-authentication-environments.md @@ -29,8 +29,8 @@ When you embed a dashboard in an application, you want it to display as easily a If you plan to use Embedding SDK on a web page on a different domain from your Strategy environment, please also meet the following requirements. More information in -1. [Enable Cross-Origin Resource Sharing (CORS)](../config.md) -1. [Allow SameSite cookies](../config.md#allow-samesite-cookies) +1. [Enable Cross-Origin Resource Sharing (CORS)](../configure-library-server/enable-cors.md) +1. [Allow SameSite cookies](../configure-library-server/enable-cors.md#allow-samesite-cookies) If you plan to use Embedding SDK on the same domain as your Strategy, the above changes are not required. diff --git a/docs/whats-new-in-the-embedding-sdk.md b/docs/whats-new-in-the-embedding-sdk.md index 88de6b87..0d0d3eb7 100644 --- a/docs/whats-new-in-the-embedding-sdk.md +++ b/docs/whats-new-in-the-embedding-sdk.md @@ -5,6 +5,13 @@ description: In each release, changes are made to make the MicroStrategy SDK mor In each release, changes are made to make the MicroStrategy SDK more powerful and easier to use. +## Strategy November 2026 + +- [Track embedded usage with client telemetry](./configure-library-server/client-telemetry.md) + - Enable the `features.telemetry.embedEnabled` feature flag on the Library server so that usage of your embedded dashboards and widgets is recorded in Platform Analytics, separate from standard Library usage. +- [Hide irrelevant allowed origins in the CSP response header](./configure-library-server/hide-irrelevant-allowed-origins.md) + - Enable the `features.hideIrrelevantAllowOrigins` feature flag on the Library server and use wildcard allowed origins, so that the `Content-Security-Policy` response header only exposes the allowed origins relevant to the current requester. + ## Strategy September 2026 - [Support `currentPage.targetFolder` for embedded Library page](./embed-library-main-page/embed-library-properties.md#currentpage) diff --git a/sidebars.js b/sidebars.js index 9ea73394..efcbcb8f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -20,7 +20,19 @@ const sidebars = { tutorialSidebar: [ "index", "whats-new-in-the-embedding-sdk", - "config", + { + type: "category", + link: { + type: "doc", + id: "configure-library-server/configure-library-server", + }, + label: "Configure Library Server for embedding", + items: [ + "configure-library-server/enable-cors", + "configure-library-server/hide-irrelevant-allowed-origins", + "configure-library-server/client-telemetry", + ], + }, "playground", { type: "category",