From 2244aea2ced2173e541976912a945951133996b2 Mon Sep 17 00:00:00 2001 From: Zook Kessler Date: Tue, 15 Sep 2026 23:56:05 +0300 Subject: [PATCH 1/5] docs: document Azure Maps rendering in embedded web UI Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../kusto/api/monaco/host-web-ux-in-iframe.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md index 53182181e5..8f25c11b59 100644 --- a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md +++ b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md @@ -178,6 +178,34 @@ To embed a dashboard, you must establish a trust relationship between the host's > "f-DisableExploreQuery": false, > ``` +### Embed Azure Maps rendering + +To render Azure Maps visuals, the hosting application provides an Azure Maps shared access signature (SAS) token through `postMessage`. This is separate from Microsoft Entra authentication; keep your existing `getToken` handler. + +1. Add `f-enableAzureMapsSecureToken=true` to the iframe URL alongside `f-IFrameAuth=true`. +2. Create an Azure Maps account and a backend endpoint that generates short-lived SAS tokens. +3. Extend your message handler to accept `getMapsToken` messages with `signature: "queryExplorer"` and a string `requestId`. Before obtaining a token, verify that `event.origin` is `https://dataexplorer.azure.com` and `event.source` is your iframe's `contentWindow`. +4. Return the SAS token in a `postMapsToken` message with the same request ID. In this example, `iframeWindow` is the iframe's `contentWindow`, and `mapsSasToken` is the token obtained from your backend: + + ```javascript + iframeWindow.postMessage({ + signature: "queryExplorer", + type: "postMapsToken", + requestId: event.data.requestId, + token: mapsSasToken + }, "https://dataexplorer.azure.com"); + ``` + +Respond within 10 seconds. On failure, send `error: "mapsTokenUnavailable"` instead of `token`. The web UI requests new tokens when needed, so keep the handler registered and renew tokens through your backend. + +> [!IMPORTANT] +> Protect your token endpoint with the host application's authentication. Keep account keys on the server and never log tokens. If you restrict Azure Maps allowed origins, include `https://dataexplorer.azure.com`, where the map requests originate. + +Use these resources to set up and test SAS authentication: + +- [Bring Data Into View Control - Azure Maps Web SDK Samples](https://samples.azuremaps.com/controls/bring-data-into-view-control) - A sample that uses SAS token authentication. +- [Azure Function code](https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/main/Services/SampleFunctions/GetAzureMapsSaSToken.cs) - An example Azure Function for generating SAS tokens. + ### Feature flags > [!IMPORTANT] From 715d93b433ea0138d63898820b88c6a4ebca7279 Mon Sep 17 00:00:00 2001 From: Zook Kessler Date: Wed, 16 Sep 2026 12:51:39 +0300 Subject: [PATCH 2/5] docs: remove Azure Maps secure token flag instruction Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md index 8f25c11b59..69288d9915 100644 --- a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md +++ b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md @@ -182,10 +182,9 @@ To embed a dashboard, you must establish a trust relationship between the host's To render Azure Maps visuals, the hosting application provides an Azure Maps shared access signature (SAS) token through `postMessage`. This is separate from Microsoft Entra authentication; keep your existing `getToken` handler. -1. Add `f-enableAzureMapsSecureToken=true` to the iframe URL alongside `f-IFrameAuth=true`. -2. Create an Azure Maps account and a backend endpoint that generates short-lived SAS tokens. -3. Extend your message handler to accept `getMapsToken` messages with `signature: "queryExplorer"` and a string `requestId`. Before obtaining a token, verify that `event.origin` is `https://dataexplorer.azure.com` and `event.source` is your iframe's `contentWindow`. -4. Return the SAS token in a `postMapsToken` message with the same request ID. In this example, `iframeWindow` is the iframe's `contentWindow`, and `mapsSasToken` is the token obtained from your backend: +1. Create an Azure Maps account and a backend endpoint that generates short-lived SAS tokens. +2. Extend your message handler to accept `getMapsToken` messages with `signature: "queryExplorer"` and a string `requestId`. Before obtaining a token, verify that `event.origin` is `https://dataexplorer.azure.com` and `event.source` is your iframe's `contentWindow`. +3. Return the SAS token in a `postMapsToken` message with the same request ID. In this example, `iframeWindow` is the iframe's `contentWindow`, and `mapsSasToken` is the token obtained from your backend: ```javascript iframeWindow.postMessage({ From 7ed804569c44a2c8a4c95b7a16ce09d2e5c0db9a Mon Sep 17 00:00:00 2001 From: zook-ms <121035382+zook-ms@users.noreply.github.com> Date: Wed, 16 Sep 2026 18:17:16 +0300 Subject: [PATCH 3/5] Revise SAS authentication resources in documentation Updated SAS authentication resources and clarified usage of Azure Function code. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md index 69288d9915..2ec6457a91 100644 --- a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md +++ b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md @@ -203,7 +203,7 @@ Respond within 10 seconds. On failure, send `error: "mapsTokenUnavailable"` inst Use these resources to set up and test SAS authentication: - [Bring Data Into View Control - Azure Maps Web SDK Samples](https://samples.azuremaps.com/controls/bring-data-into-view-control) - A sample that uses SAS token authentication. -- [Azure Function code](https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/main/Services/SampleFunctions/GetAzureMapsSaSToken.cs) - An example Azure Function for generating SAS tokens. +- [Azure Function code](https://github.com/Azure-Samples/AzureMapsCodeSamples/blob/main/Services/SampleFunctions/GetAzureMapsSaSToken.cs) - Token-generation logic only; replace its anonymous trigger and sample-site `Referer` check with the host application's authentication and origin checks before using it for an embedded web UI. ### Feature flags From 35a3f36a608c65720bf5a5f4d181c19e6ecb7104 Mon Sep 17 00:00:00 2001 From: Zook Kessler Date: Thu, 17 Sep 2026 15:08:20 +0300 Subject: [PATCH 4/5] docs: announce November 1 embedded Maps breaking change Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md index 2ec6457a91..ae8e623a19 100644 --- a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md +++ b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md @@ -12,6 +12,11 @@ monikerRange: "azure-data-explorer" > [!INCLUDE [applies](../../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../../includes/applies-to-version/azure-data-explorer.md)] +> [!IMPORTANT] +> **Breaking change: action required by November 1, 2026.** To keep Azure Maps visuals rendering in the embedded web UI, update your hosting application to supply Azure Maps SAS tokens as described in [Embed Azure Maps rendering](#embed-azure-maps-rendering). +> +> To test the new behavior before the deadline, add `f-enableAzureMapsSecureToken=true` to your iframe URL alongside `f-IFrameAuth=true`. On November 1, 2026, `f-enableAzureMapsSecureToken` will be enabled by default. Hosting applications that don't supply Azure Maps SAS tokens will no longer be able to render map visuals. + You can embed the Azure Data Explorer web UI in an iframe and host it on third-party websites. This article describes how to embed the Azure Data Explorer web UI in an iframe. :::image type="content" source="../media/host-web-ux-in-iframe/web-ux.png" alt-text="Screenshot of the Azure Data Explorer web UI."::: From 68bcf1c0c9d3bd8b7da5e04d2f5fad0f3aca689c Mon Sep 17 00:00:00 2001 From: Zook Kessler Date: Thu, 17 Sep 2026 15:15:35 +0300 Subject: [PATCH 5/5] docs: move Maps feature flag guidance to migration section Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md index ae8e623a19..805556f365 100644 --- a/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md +++ b/data-explorer/kusto/api/monaco/host-web-ux-in-iframe.md @@ -13,9 +13,7 @@ monikerRange: "azure-data-explorer" > [!INCLUDE [applies](../../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../../includes/applies-to-version/azure-data-explorer.md)] > [!IMPORTANT] -> **Breaking change: action required by November 1, 2026.** To keep Azure Maps visuals rendering in the embedded web UI, update your hosting application to supply Azure Maps SAS tokens as described in [Embed Azure Maps rendering](#embed-azure-maps-rendering). -> -> To test the new behavior before the deadline, add `f-enableAzureMapsSecureToken=true` to your iframe URL alongside `f-IFrameAuth=true`. On November 1, 2026, `f-enableAzureMapsSecureToken` will be enabled by default. Hosting applications that don't supply Azure Maps SAS tokens will no longer be able to render map visuals. +> **Breaking change: action required by November 1, 2026.** To keep Azure Maps visuals rendering in the embedded web UI, update your hosting application to supply Azure Maps SAS tokens as described in [Embed Azure Maps rendering](#embed-azure-maps-rendering). Starting on this date, hosting applications that don't supply Azure Maps SAS tokens will no longer be able to render map visuals. You can embed the Azure Data Explorer web UI in an iframe and host it on third-party websites. This article describes how to embed the Azure Data Explorer web UI in an iframe. @@ -202,6 +200,8 @@ To render Azure Maps visuals, the hosting application provides an Azure Maps sha Respond within 10 seconds. On failure, send `error: "mapsTokenUnavailable"` instead of `token`. The web UI requests new tokens when needed, so keep the handler registered and renew tokens through your backend. +To test the new behavior before the deadline, add `f-enableAzureMapsSecureToken=true` to your iframe URL alongside `f-IFrameAuth=true`. On November 1, 2026, `f-enableAzureMapsSecureToken` will be enabled by default. + > [!IMPORTANT] > Protect your token endpoint with the host application's authentication. Keep account keys on the server and never log tokens. If you restrict Azure Maps allowed origins, include `https://dataexplorer.azure.com`, where the map requests originate.