@bitruvius/esri-auth

Sign in once, and every secured ArcGIS layer in your scene streams.

Opt-in ArcGIS authentication for the Bitruvius SDK. Public first: open ArcGIS Online and Enterprise layers stream with no prompt, and auth engages only when a secured scene layer, I3S service or elevation ImageServer actually challenges.

It implements the SDK's RequestAuthorizer seam, so one configured session flows into every layer (Tiles3DSplatLayer, I3sPointCloudLayer, Tiles3DMeshLayer, addEsriTerrain / createEsriTerrain). Public/non-ESRI apps that never import this package ship zero bytes of it (and none of its peer dependency).

Install

npm i @bitruvius/esri-auth @esri/arcgis-rest-request

@esri/arcgis-rest-request (Apache-2.0) is a peer dependency. It powers the OAuth flow and the portal to federated-server token exchange. The apiKey, token, and iwa/cookies modes don't use it at runtime.

AGOL / Enterprise named-user (OAuth 2.0 PKCE)

import { configureEsriAuth } from '@bitruvius/esri-auth';

configureEsriAuth({
  mode: 'oauth',
  portalUrl: 'https://www.arcgis.com',     // or https://gis.example.com/portal
  clientId: 'YOUR_OAUTH_APP_ID',
  redirectUri: location.origin,            // a registered redirect URI
});

// Then add layers as usual. Public ones stream silently; a secured one
// auto-challenges ONCE and the whole scene shares the session.
map.addLayer(new I3sPointCloudLayer({ id: 'lidar', url: '…/SceneServer/layers/0' }));

Put a tiny page at your redirectUri that finishes the flow:

// /oauth-callback.html
import { completeEsriOAuth } from '@bitruvius/esri-auth';
completeEsriOAuth({ clientId: 'YOUR_OAUTH_APP_ID' });

Pre-authenticate before adding secured layers with await signInEsri().

Other modes

// API key (location services + scoped items; NOT secured hosted scene layers)
configureEsriAuth({ mode: 'apiKey', apiKey: 'AAPK…' });

// A token you already have (string, or an async getter the SDK calls on 498)
configureEsriAuth({ mode: 'token', token: async () => myToken() });

// Web-tier SSO (IWA/Kerberos, SAML, OIDC, PKI): no token, send cookies.
// The server must include this origin in authorizedCrossOriginDomains.
configureEsriAuth({ mode: 'iwa' });

// Adopt an existing @esri/arcgis-rest-request identity manager
configureEsriAuth({ mode: 'byo', manager });

Per-layer override

Prefer the global configureEsriAuth() (shared sign-in). For an exception, build a stand-alone authorizer and pass it to one layer's auth:

import { makeEsriAuthorizer } from '@bitruvius/esri-auth';
const auth = makeEsriAuthorizer({ mode: 'token', token: t });
map.addLayer(new I3sPointCloudLayer({ id: 'x', url, auth }));

How it works

• Public-first: the first request to a host goes out unauthenticated. A clean response marks the host public forever after (zero cost). A challenge, whether HTTP 401/403, ArcGIS 499 (token required) or 498 (invalid token), or the f=json 200-with-{error:{code}} envelope, triggers acquisition and one retry.
• Federated scoping: tokens are host-scoped. ArcGISIdentityManager.getToken(url) discovers a service host's /rest/info and exchanges the portal token for the correct federated-server token; concurrent tile bursts share one acquisition.
• Attach (auto, default): a header (X-Esri-Authorization: Bearer) for JSON/metadata; a ?token= query param for binary tile/scene-node/CDN endpoints (avoids a CORS preflight the tile CDN often won't answer). Force with attach: 'header' | 'query'.
• Refresh: tokens refresh before/at expiry across long streaming sessions; a mid-stream 498 transparently refreshes and retries.

Tokens are never logged. The token never enters a JSON request URL under auto.

Your credentials, your data

This package signs you in. It grants no right to any ArcGIS content. Your organization's agreement with Esri governs what you may do with anything a token unlocks, including whether the data may be shown in a public application at all, and attribution requirements attached to a service are conditions of that agreement rather than courtesies.

Tokens are never logged, and under the default auto attach mode a token never enters a JSON request URL.

Trademarks

Esri, ArcGIS and I3S are trademarks of Environmental Systems Research Institute, Inc. All other marks are the property of their respective owners.

These names are used solely to describe the services this software interoperates with. Bitruvius is not affiliated with, sponsored by, or endorsed by any of them, and no such relationship is implied. Use of any ArcGIS service remains subject to Esri's own terms and licensing.

License

Proprietary. The full terms ship as LICENSE inside this package, and are readable before installing at cdn.bitruvius.com/legal/sdk-license-v1.txt.

© Bitruvius, Inc.