Embedding for your organization

There are two ways to embed an Icon Map, and they suit different audiences.

Embedding maps covers the first: a published map, frozen and served to viewers who have no Fabric access at all. This page covers the second: a live map inside your own internal application, where every viewer signs in as themselves.

If you know Power BI embedding, these are the same two models - "embed for your customers" and "embed for your organization".

What it is

The map is embedded in your application, and each viewer's own Microsoft Entra identity is used to read the data. That means:

  • Viewers see only the data their own Fabric permissions allow, and row-level security applies automatically - the same RLS your Fabric and Power BI models already enforce. There is nothing to configure in Icon Map.
  • The data is live, read at the moment they open the map, not a snapshot.
  • There is no reader service principal and no published copy. Icon Map can never reach anything the viewer could not already open themselves.

The map is view-only: viewers can explore, filter, use bookmarks and fill in write-back forms, but there is no authoring and no way into the editor.

When to use which mode

Embedding maps Embedding for your organization
Viewers sign in? No Yes, with their own work account
Who reads the data A reader identity The viewer
Row-level security Not per viewer Native Fabric / Power BI RLS, per viewer
Data Snapshot, or pinned live queries Live, as the viewer
Audience Anyone - customers, the public People in your organization with access to the data
Typical use A public site, a customer portal An operations portal, an intranet, a line-of-business app

There is no per-user licence to think about: Fabric is billed at the capacity, so the audience is simply the people in your directory who are allowed to see the underlying data.

This mode cannot be used for public sharing. Every viewer signs in, so there is no anonymous link.

What you need

  • An Icon Map created with the Icon Map workload in a Fabric workspace, on a Fabric (F or trial) capacity.
  • Viewers with Fabric permission to the map item and to the data behind it - granted the normal way, by sharing the item or the workspace.
  • An Entra application that can issue the tokens the map reads with. Which application depends on how you handle sign-in:
    • Your application supplies the token (the usual choice) - your own Entra app is used, and Icon Map's viewer application is not involved at all. Your app needs these delegated permissions consented in your tenant: Azure Storage user_impersonation, Fabric/Power BI Workspace.Read.All, Item.Read.All and Dataset.Read.All, and Azure Data Explorer user_impersonation if the map reads an Eventhouse.
    • The map signs the viewer in - one-time admin consent for the Icon Map Embed Viewer application in your tenant.

Adding it to your application

Embed the map with the Icon Map JavaScript SDK. Point it at the map item and tell it how to get a token:

<div id="map" style="height: 600px"></div>

<script type="module">
  import { embedForOrganization } from "@iconmap/embed";

  embedForOrganization(document.getElementById("map"), {
    mapItem: {
      workspaceId: "00000000-0000-0000-0000-000000000000",
      itemId: "00000000-0000-0000-0000-000000000000",
    },
    // Your application already signed this user in - hand over a token for
    // the scopes the map asks for.
    getToken: (scopes) =>
      msalInstance
        .acquireTokenSilent({ scopes, account })
        .then((result) => result.accessToken),
    onError: (error) => console.error(error),
  });
</script>

You can find the workspace and item IDs in the Fabric URL of the map.

Two ways to handle sign-in

Your application supplies the token (the example above, and the usual choice). Your users sign in once, to your application, and the map reuses that session. Nothing extra appears in front of them.

The map asks for a token for the resource it is about to read - your OneLake storage, the Fabric API, an Eventhouse cluster - so return a token for the scopes you are given rather than one fixed token.

Because the tokens come from your Entra application, Icon Map's own viewer application is never used in this arrangement and needs no consent.

The map signs the viewer in. Leave out getToken and the map handles sign-in itself, showing a sign-in button the first time. Simplest to drop in, but your users will sign in twice - once to your application and once to the map.

Controlling the session

const handle = embedForOrganization(element, options);

handle.signOut();  // drop the viewer's session and cached tokens
handle.reload();   // re-read the map as the viewer
handle.destroy();  // remove the map from the page

Security

  • Least privilege by construction. There is no vendor identity in the data path. A viewer can only ever see what they are already permitted to see, and a viewer who loses access to the data stops seeing it - immediately, with no re-publish.
  • Row-level security is Fabric's, not ours. Nothing about your RLS needs restating in Icon Map, so there is nothing to get out of step.
  • Nothing is copied. No frozen snapshot of your data exists anywhere.
  • The one residual risk is the ordinary one for this model: an access token that is stolen works until it expires. Tokens are short-lived, exactly as in Power BI's equivalent mode.

More detail in the security whitepaper.

Things to know

  • Guest (B2B) viewers work to whatever extent Fabric grants them access to the data. Cross-tenant guest scenarios are not something Icon Map can widen.
  • Maps created with a development build of the workload cannot be embedded this way. Use maps created with the published Icon Map workload.
  • The map's workspace capacity must be running - a paused capacity means no data for anyone.

Next steps