Authentication System Documentation

Overview

The application uses a two-step authentication process:

1. API Authentication - Required for accessing backend API endpoints
2. Esri Authentication - Required for accessing Esri content and services

Components

1. API Authentication (src/services/authService.js)

• Handles authentication with the backend API
• Uses environment variables for credentials:
  • VITE_API_USERNAME
  • VITE_API_PASSWORD
• Stores JWT token in memory
• Includes JWT token in Authorization header for all API requests
• Provides fetchWithAuth method for authenticated API calls

2. Initialization Service (src/services/initService.js)

• Manages automatic API authentication on application startup
• Ensures API authentication is complete before other services are used
• Provides initialization status and error handling

3. Esri Authentication (src/services/esriAuth.js)

• Handles authentication with Esri services
• Requires valid API authentication to fetch Esri token
• Manages Esri token lifecycle and registration with Esri IdentityManager

4. Authentication Context (src/contexts/AuthContext.jsx)

• Provides authentication state and methods to React components
• Manages login/logout functionality
• Handles authentication errors

5. Esri Authentication Hook (src/hooks/useEsriAuth.js)

• React hook for Esri authentication
• Ensures API authentication is complete before Esri authentication
• Manages Esri token registration and refresh

Authentication Flow

Environment Variables

Required environment variables for authentication:

VITE_API_URL=your_api_url
VITE_API_USERNAME=your_api_username
VITE_API_PASSWORD=your_api_password

Security Considerations

1. API Authentication

   • JWT token stored in memory (not in localStorage)
   • Credentials stored in environment variables
   • Automatic authentication on startup
   • Token included in Authorization header for all API requests

2. Esri Authentication

   • Depends on valid API authentication
   • Tokens managed by Esri IdentityManager
   • Automatic token refresh handling

Error Handling

1. API Authentication Errors

   • Invalid credentials
   • Network errors
   • Server errors
   • JWT token expiration

2. Esri Authentication Errors

   • API authentication required
   • Token generation failures
   • Token registration errors

Usage Examples

Making Authenticated API Calls

import authService from '../services/authService';

async function fetchData() {
  try {
    const response = await authService.fetchWithAuth('/api/endpoint');
    const data = await response.json();
    // Handle data
  } catch (error) {
    // Handle error
  }
}

Using Esri Authentication

import { useEsriAuth } from '../hooks/useEsriAuth';

function MyComponent() {
  const { isAuthenticated, isLoading } = useEsriAuth();

  if (isLoading) {
    return <LoadingSpinner />;
  }

  if (!isAuthenticated) {
    return <AuthError />;
  }

  return <EsriContent />;
}