Authentication

Fusion Analyst gates the entire app behind sign-in — there is no anonymous access. Authentication is pluggable: the same context interface is backed by either a mock provider (for local development) or a real ArcGIS OAuth provider.

• Context + selection: src/auth/AuthContext.tsx
• Config: src/auth/auth.config.ts
• Types: src/auth/types.ts

Choosing a provider

The provider is selected at runtime by the AUTH_MODE value, which reads the VITE_AUTH_MODE environment variable (defaults to arcgis):

VITE_AUTH_MODE	Provider	Behavior
mock	MockAuthProvider	Auto-signs in a built-in test account, no network.
arcgis	ArcGisAuthProvider	Real OAuth with multiple ArcGIS connections.

AuthProviderComponent lazy-imports the selected provider, so you swap providers purely with configuration — no code changes:

# .env.local
VITE_AUTH_MODE=mock

The useAuth() hook

Components read auth state through useAuth(), which returns an AuthContextValue. Both providers implement the same interface, so consumers never branch on the provider.

State

Member	Type	Description
status	AuthStatus	"loading" | "authenticated" | "unauthenticated" | "error".
user	AuthUser | null	The signed-in user.
isAuthenticated	boolean	Convenience flag.
isLoading	boolean	Convenience flag.
error / authError	string | null	The last auth error.
portal	__esri.Portal | null	The live ArcGIS portal (arcgis mode).
activeConfig	ArcGisConfiguration | null	The active connection.
configurations	ArcGisConfiguration[]	All saved connections.

Actions

Method	Description
login() / logout()	Sign in / out of the active connection.
signOut()	Alias used by the header menu.
signInWithConfig(config)	Sign in with a specific connection.
setActiveConfiguration(id)	Switch the active connection.
addConfiguration(data)	Add an Enterprise connection.
addAGOLConfiguration(data)	Add an ArcGIS Online connection.
updateConfiguration(id, patch)	Edit a connection.
deleteConfiguration(id)	Remove a connection.
refreshConfigurations()	Reload the saved connection list.
clearError()	Dismiss the current error.
getArcGisToken()	Promise<string | null> — fetch a fresh portal token for the active connection (resolved at call time so it reflects silent renewal). Returns null when there is no ArcGIS session (e.g. mock mode). Used to forward the token to the backend for server-side ArcGIS work such as geocoding.

The AuthUser model

interface AuthUser {
  id: string;          // unique per portal: `${username}@${hostname}`
  username: string;
  fullName: string;
  initials: string;
  email?: string;
  role?: string;
  portal?: {
    portalUrl: string;
    token?: string;
    thumbnailUrl?: string;
  };
}

Because id is unique per portal, workspaces roam per connection — signing in to a different portal yields a different set of workspaces.

Connections (ArcGIS mode)

The ArcGIS provider manages multiple saved connections, each an ArcGisConfiguration:

interface ArcGisConfiguration {
  id: string;
  type: 'agol' | 'enterprise';
  configurationName: string;
  portalUrl: string;
  clientId: string;
  createdAt?: string;
  updatedAt?: string;
}

Connections are persisted in localStorage under keys defined in auth.config.ts (prefixed fusion_analyst_). Tokens are never persisted — the ArcGIS SDK's IdentityManager handles the OAuth flow and token lifecycle; only the connection definitions and the active connection id are stored.

Managing connections in the UI

The SignInPanel lists saved connections and lets users add or manage them. The dialogs are provided by the useConnectionDialogs() hook:

const {openManage, openAddAgol, openAddEnterprise, dialogs} =
  useConnectionDialogs();

• openAddAgol() — add an ArcGIS Online connection.
• openAddEnterprise() — add an Enterprise portal connection.
• openManage() — edit or delete existing connections.
• dialogs — a node you render once to host all managed dialogs.

How sign-in maps to a user

When the ArcGIS portal loads, userFromPortal maps the portal user and active connection onto an AuthUser, deriving initials and the per-portal id.

Mock provider

MockAuthProvider auto-signs in a TEST_ACCOUNT (username: test.analyst) and stubs all connection methods as no-ops. It is ideal for working on workspaces, views, and widgets without an ArcGIS portal.