Embed the Azure Data Explorer web UI in an iframe

The Azure Data Explorer web UI can be embedded in an iframe and hosted in third-party websites. This article describes how to embed the Azure Data Explorer web UI in an iframe.

All functionality is tested for accessibility and supports dark and light on-screen themes.

How to embed the web UI in an iframe

Add the following code to your website:

<iframe
  src="https://dataexplorer.azure.cn/?f-IFrameAuth=true&f-UseMeControl=false&workspace=<guid>"
></iframe>

The f-IFrameAuth query parameter tells the web UI not to redirect to get an authentication token and the f-UseMeControl=false parameter tells the web UI not to show the user account information pop-up window. These actions are necessary since the hosting website is responsible for authentication.

The workspace=<guid> query parameter creates a separate workspace for the embedded iframe. Workspace is a logic unit that contains tabs, queries, settings and connections. By setting it to a unique value, it prevents data sharing between the embedded and the non-embedded version of https://dataexplorer.azure.cn.

Handle authentication

When embedding the web UI, the hosting page is responsible for authentication. The following diagrams describe the authentication flow.

Use the following steps to handle authentication:

1. In your application, listen for the getToken message.

   window.addEventListener('message', (event) => {
      if (event.data.signature === "queryExplorer" && event.data.type === "getToken") {
        // CODE-1: Replace this placeholder with code to get the access token from Microsoft Entra ID and
        //         then post a "postToken" message with an access token and an event.data.scope
      }
   })    
   

2. Define a function to map the event.data.scope to Microsoft Entra scope. Use the following table to decide how to map event.data.scope to Microsoft Entra scopes:

   Resource	event.data.scope	Microsoft Entra scope
   Cluster	query	https://{your_cluster}.{your_region}.kusto.chinacloudapi.cn/.default
   Graph	People.Read	People.Read, User.ReadBasic.All, Group.Read.All
   Dashboards	https://rtd-metadata.chinacloudsites.cn/user_impersonation	https://rtd-metadata.chinacloudsites.cn/user_impersonation

   For example, the following function maps scopes based on the information in the table.

       function mapScope(scope) {
           switch(scope) {
               case "query": return ["https://your_cluster.your_region.kusto.chinacloudapi.cn/.default"];
               case "People.Read": return ["People.Read", "User.ReadBasic.All", "Group.Read.All"];
               default: return [scope]
           }
       }
   

3. Get a JWT access token from the Microsoft Entra authentication endpoint for the scope. This code replaces placeholder CODE-1.

   For example, you can use @azure/MSAL-react to get the access token. The example uses the mapScope function you defined earlier.

   import { useMsal } from "@azure/msal-react";
   const { instance, accounts } = useMsal();
   
   instance.acquireTokenSilent({
     scopes: mapScope(event.data.scope),
     account: accounts[0],
   })
   .then((response) =>
       var accessToken = response.accessToken
       // - CODE-2: Replace this placeholder with code to post a "postToken" message with an access token and an event.data.scope
   )
   

   Important

   You can only use User Principal Name (UPN) for authentication, service principals are not supported.

4. Post a postToken message with the access token. This code replaces placeholder CODE-2:

        iframeWindow.postMessage({
            "type": "postToken",
            "message": // the access token your obtained earlier
            "scope": // event.data.scope as passed to the "getToken" message
        }, '*');
      }
   

   Important

   The hosting window must refresh the token before expiration by sending a new postToken message with updated tokens. Otherwise, once the tokens expire, service calls will fail.

Embed dashboards

To embed a dashboard, a trust relationship must be established between the host's Microsoft Entra app and the Azure Data Explorer dashboard service (RTD Metadata Service).

1. Follow the steps in Web Client (JavaScript) authentication and authorization.

2. Open the Azure portal and make sure that you're signed into the correct tenant. In the top-right corner, verify the identity used to sign into the portal.

3. In the resources pane, select Microsoft Entra ID > App registrations.

4. Locate the app that uses the on-behalf-of flow and open it.

5. Select Manifest.

6. Select requiredResourceAccess.

7. In the manifest, add the following entry:

     {
       "resourceAppId": "35e917a9-4d95-4062-9d97-5781291353b9",
       "resourceAccess": [
           {
               "id": "388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c",
               "type": "Scope"
           }
       ]
     }
   

   • 35e917a9-4d95-4062-9d97-5781291353b9 is the application ID of Azure Data Explorer dashboard service.
   • 388e2b3a-fdb8-4f0b-ae3e-0692ca9efc1c is the user_impersonation permission.

8. In the Manifest, save your changes.

9. Select API permissions and validate you have a new entry: RTD Metadata Service.

10. Under Microsoft Graph, add permissions for People.Read, User.ReadBasic.All, and Group.Read.All.

11. In Azure PowerShell, add the following new service principal for the app:

    New-MgServicePrincipal -AppId 35e917a9-4d95-4062-9d97-5781291353b9
    

    If you encounter the Request_MultipleObjectsWithSameKeyValue error, it means that the app is already in the tenant indicating it was added successfully.

12. In the API permissions page, select Grant admin consent to consent for all users.

 <iframe src="https://dataexplorer.azure.cn/dashboards?[feature-flags]" />

"f-IFrameAuth": true,
"f-PersistAfterEachRun": true,
"f-Homepage": false,
"f-ShowPageHeader": false,
"f-ShowNavigation": false,
"f-DisableExploreQuery": false,

Feature flags

The hosting app may want to control certain aspects of the user experience. For example, hide the connection pane, or disable connecting to other clusters. For this scenario, the web explorer supports feature flags.

A feature flag can be used in the URL as a query parameter. To disable adding other clusters, use https://dataexplorer.azure.cn/?f-ShowConnectionButtons=false in the hosting app.

Related content

• Kusto Query Language (KQL) overview
• Write Kusto queries
• Embedding sample