Agent Guide: arcgis-authentication

Quick-reference decisions, checklists, and tables for authentication and authorization.

API Key vs OAuth vs Identity Manager Decision Tree

1. Does the app access only public basemaps, geocoding, or routing?
   • Yes --> API Key (simplest)
2. Does the app need to access the user's private content (web maps, feature services)?
   • Yes --> OAuth 2.0 (user signs in)
3. Is this a server-side app with no user interaction?
   • Yes --> App token (client credentials OAuth flow, server-side only)
4. Is the app connecting to ArcGIS Enterprise (on-premise)?
   • Yes --> OAuth 2.0 with custom portalUrl
5. Do you need to access multiple secured services and want automatic token management?
   • Yes --> IdentityManager handles this automatically with OAuth or registered tokens

OAuth Setup Checklist

Register your app

• Go to developers.arcgis.com (or your Enterprise portal)
• Create a new OAuth application
• Note the App ID (client ID)
• Add redirect URIs for your app (e.g., http://localhost:5173, https://yourapp.com)
• For production: add referrer restrictions on the app registration

Implement in code

• Import OAuthInfo and esriId (IdentityManager)
• Create OAuthInfo: new OAuthInfo({ appId: "YOUR_APP_ID" })
• Set popup: false for redirect flow, popup: true for popup window
• Register: esriId.registerOAuthInfos([oauthInfo])
• Check existing sign-in: esriId.checkSignInStatus(portalUrl + "/sharing")
• Trigger sign-in: esriId.getCredential(portalUrl + "/sharing")
• Load portal: new Portal({ authMode: "immediate" }) then await portal.load()

For Enterprise Portal

• Set portalUrl on OAuthInfo: new OAuthInfo({ appId, portalUrl: "https://your-portal/portal" })
• Or set globally: esriConfig.portalUrl = "https://your-portal/portal"

Using the OAuth Component

• Add <arcgis-oauth app-id="YOUR_APP_ID"> to HTML
• Listen for arcgisSignIn and arcgisSignOut events
• Access credential from event.detail.credential

Security Checklist

Token handling

• Never commit API keys or tokens to source control
• Use environment variables (e.g., VITE_ARCGIS_API_KEY) for API keys
• For OAuth: tokens are managed by IdentityManager (no manual storage needed)
• Do not store tokens in localStorage for production apps

CORS and referrers

• Configure esriConfig.request.trustedServers for servers that should receive credentials
• Set up proxy (esriConfig.request.proxyUrl) for services that do not support CORS
• Configure allowed referrers on your API key at developers.arcgis.com
• For Enterprise: ensure CORS is enabled on the portal and services

OAuth security

• Use HTTPS in production (OAuth redirects require it)
• Register only the redirect URIs you actually use
• Use popup: false (redirect flow) when popup blockers are a concern
• Handle token expiration: IdentityManager auto-refreshes, but test edge cases

API Key scoping

• Generate API keys with minimum required privileges (only basemaps, only geocoding, etc.)
• Set referrer restrictions to limit where the key can be used
• Use separate keys for development and production
• Rotate keys periodically

Sign-In / Sign-Out Flow Summary

App loads
  --> checkSignInStatus()
    --> Signed in? Load Portal, display user info
    --> Not signed in? Show sign-in button
      --> User clicks sign-in
        --> getCredential() triggers OAuth redirect/popup
          --> User authenticates at ArcGIS
            --> Redirect back with token
              --> Load Portal, display user info

Sign out:
  --> esriId.destroyCredentials()
  --> window.location.reload()

Common Token Errors