ArcGIS sign-in and the proxy

Icon Map Slicer needs no API keys for its own basemaps. The only credentials it uses are for ArcGIS. This page covers where those credentials go, how they are stored, and what the Icon Map proxy does when a server does not allow Power BI to read it.

The ArcGIS Authentication card

The ArcGIS Authentication card sets how the map connects to ArcGIS Online or ArcGIS Enterprise. It is not always in the Format pane: it appears once the map uses ArcGIS, which means any of these:

• Background Layer > Map Source is ArcGIS.
• A basemap list made in the Basemaps dialog holds an ArcGIS basemap or web map.
• An ArcGIS reference layer is on (Reference Layers > ArcGIS Layer - Setup).
• The ArcGIS data layer is on (Data Layers > ArcGIS Layer).
• Hill Shading or 3D Terrain reads an ArcGIS elevation service.
• Authentication Type is already set to Sign in with ArcGIS.

The full guide, with steps for each method, is Connect to ArcGIS. In summary:

With Sign in with ArcGIS, the ArcGIS sign-in page opens in a browser tab. A relay at api.iconmap.ai passes the sign-in result back to the visual, and the visual then exchanges it for a token directly with your portal. The token is not sent to Icon Map.

Send Credential As sets how the credential travels to ArcGIS: URL Parameter (Default) or Authorization Header (Bearer). Leave it on URL Parameter unless your server rejects it. ArcGIS Enterprise 11.5 and later may reject newer API keys on the URL with "Invalid Token". Those servers need the Authorization Header option and must allow the Authorization header in their CORS settings.

With no credential, ArcGIS content is read as public content.

Test Connection checks the portal, the credential and every ArcGIS layer in the map, and explains anything that fails.

How credentials are stored

• An ArcGIS API key is saved in the report as an ordinary setting. Anyone who can edit the report can read it, and the visual sends it to ArcGIS with each request. Restrict the key in ArcGIS to the services the map uses.
• The ArcGIS Client Secret is saved in protected form and shown as dots after you enter it.
• Sessions from a personal ArcGIS sign-in are kept in the visual's local storage on the reader's device, not in the report. This uses the optional local storage privilege, so your Power BI tenant must allow local storage for custom visuals. Without it, people sign in again more often.
• The Icon Map license key, where one is used, is saved in the report in Icon Map Slicer > License Key (for non-user based licensing). See License keys and activation.

The proxy

Why a proxy exists

Power BI runs every custom visual in a sandboxed frame. A web server must explicitly allow requests from that frame, through CORS headers, before the visual can read its response. Most public map services do. Some servers do not, typically ArcGIS Enterprise servers and some tile, GeoJSON and WFS servers. A layer from such a server stays blank, even though the same link opens in a browser.

The fix that keeps everything in your control is to allow CORS on your server. When you cannot, the Icon Map proxy can fetch the resource on the visual's behalf and return it with the headers Power BI needs.

The proxy is a relay service run by Icon Map at proxy.icon-map.com. It is off by default. It requires an Icon Map license key, and proxied requests may consume additional usage credits.

When the proxy is used

The setting is named Use proxy when required, and it works the way the name says:

• Every server is tried directly first.
• Only a server that is found not to allow Power BI is fetched through the proxy. That applies to the request that found the block and to later requests to that server in the same session. Map tiles and images follow the same rule.
• Servers that allow Power BI are never proxied, even with the switch on.

You can switch the proxy on in these places:

When ArcGIS servers have been found blocked, the explanation under the ArcGIS switch names them: "These ArcGIS servers blocked requests from Power BI: ...".

The proxy choice for a file or raster layer is made in the Layer Manager: the tick box while you add the layer, and Use proxy when required in its editor afterwards. The Format pane groups of those layers have no proxy switch.

WMS reference layers have no proxy option, and the Layer Manager does not offer one when it adds a WMS layer. Neither do basemaps from a tile server, WMS or style link, unless the same server is also used by a layer that has the proxy on.

What is sent to the proxy

Nothing is sent to the proxy unless a proxy option is on and a server has been found to block Power BI.

To open a session, the visual sends:

• the Icon Map license key from the Icon Map Slicer card
• the environment the report is running in (for example Power BI Desktop, the Power BI service or Power BI Embedded)
• the product name, IconMapSlicer
• the optional Reference from the Icon Map Slicer card
• the visual's instance ID and a session ID

The proxy answers with a short-lived session token, which the visual reuses until shortly before it expires.

For each proxied request, the visual sends:

• the full address of the resource, including its query string. A token or key that is part of the address travels with it
• the session token
• any extra request headers the server needs, for example an authorization header

The proxy makes the request to your server and passes the response back, including binary content such as tiles.

What this means:

• The proxy service sees the address of each proxied request, any credential attached to it, and the response.
• The rows of your Power BI data are not sent by this mechanism. Only layer and tile requests are. If you build a layer's link or filter from your data with conditional formatting, the values in that link are part of the address.
• Your server must be reachable from the internet for the proxy to fetch from it. The proxy cannot reach a server that is only available inside your network.

Turn the proxy off everywhere

Turn on Icon Map Slicer > Customization > Airgapped Environment. The proxy is then ruled out for the whole map. Use proxy when required is shown off and disabled, with the note "Not available: Airgapped Environment is on, so the map makes no calls to Icon Map services, including the proxy." The Layer Manager hides its proxy check box and switch.

An Icon Map license can also rule the proxy out. The switch then reads "Not available: this license does not include the Icon Map proxy."

See Power BI Report Server (on-premises).

Tips and limits

• Prefer fixing CORS on your own server. It avoids the proxy, the license key requirement and the extra hop.
• A link that opens in a browser but not in the map is the usual sign of a CORS block. See Troubleshooting.
• The proxy does not make a private server public. It forwards the credentials your map already uses.
• If your network restricts outbound traffic, allow the ArcGIS and Icon Map addresses listed in Supported environments and limits.

Related

• Connect to ArcGIS
• Other basemap providers
• Files and feeds
• Security and certification