OCR/openspec/changes/migrate-to-external-api-authentication/proposal.md

Change: Migrate to External API Authentication

Why

The current local database authentication system has several limitations:

• User credentials are managed locally, requiring manual user creation and password management
• No centralized authentication with enterprise identity systems
• Cannot leverage existing enterprise authentication infrastructure (e.g., Microsoft Azure AD)
• No single sign-on (SSO) capability
• Increased maintenance overhead for user management

By migrating to the external API authentication service at https://pj-auth-api.vercel.app, the system will:

• Integrate with enterprise Microsoft Azure AD authentication
• Enable single sign-on (SSO) for users
• Eliminate local password management
• Leverage existing enterprise user management and security policies
• Reduce maintenance overhead
• Provide consistent authentication across multiple applications

What Changes

Authentication Flow

• Current: Local database authentication using username/password stored in MySQL
• New: External API authentication via POST to https://pj-auth-api.vercel.app/api/auth/login
• Token Management: Use JWT tokens from external API instead of locally generated tokens
• User Display: Use name field from API response for user display instead of local username

API Integration

Endpoint: POST https://pj-auth-api.vercel.app/api/auth/login

Request Format:

{
  "username": "user@domain.com",
  "password": "user_password"
}

Success Response (200):

{
  "success": true,
  "message": "認證成功",
  "data": {
    "access_token": "eyJ0eXAiOiJKV1Q...",
    "id_token": "eyJ0eXAiOiJKV1Q...",
    "expires_in": 4999,
    "token_type": "Bearer",
    "userInfo": {
      "id": "42cf0b98-f598-47dd-ae2a-f33803f87d41",
      "name": "ymirliu 劉念萱",
      "email": "ymirliu@panjit.com.tw",
      "jobTitle": null,
      "officeLocation": "高雄",
      "businessPhones": ["1580"]
    },
    "issuedAt": "2025-11-14T07:09:15.203Z",
    "expiresAt": "2025-11-14T08:32:34.203Z"
  },
  "timestamp": "2025-11-14T07:09:15.203Z"
}

Failure Response (401):

{
  "success": false,
  "error": "用戶名或密碼錯誤",
  "code": "INVALID_CREDENTIALS",
  "timestamp": "2025-11-14T07:10:02.585Z"
}

Database Schema Changes

• users table modifications:
  • Remove/deprecate hashed_password column (keep for rollback)
  • Add external_user_id (VARCHAR 255) - Store Azure AD user ID
  • Add display_name (VARCHAR 255) - Store user display name from API
  • Add azure_email (VARCHAR 255) - Store Azure AD email
  • Add last_token_refresh (DATETIME) - Track token refresh timing
  • Keep username for backward compatibility (can be email)

Session Management

• Store external API tokens in session/cache instead of local JWT
• Implement token refresh mechanism based on expires_in field
• Use expiresAt timestamp for token expiration validation

Impact

Affected Capabilities

• authentication: Complete replacement of authentication mechanism
• user-management: Simplified to read-only user information from external API
• session-management: Modified to handle external tokens

Affected Code

• Backend Authentication:

  • backend/app/api/v1/endpoints/auth.py: Replace login logic with external API call
  • backend/app/core/security.py: Modify token validation to use external tokens
  • backend/app/core/auth.py: Update authentication dependencies
  • backend/app/services/auth_service.py: New service for external API integration

• Database Models:

  • backend/app/models/user.py: Update User model with new fields
  • backend/alembic/versions/: New migration for schema changes

• Frontend:

  • frontend/src/services/authService.ts: Update to handle new token format
  • frontend/src/stores/authStore.ts: Modify to store/display user info from API
  • frontend/src/components/Header.tsx: Display name field instead of username

Dependencies

• Add httpx or aiohttp for async HTTP requests to external API (already present)
• No new package dependencies required

Configuration

• New environment variables:
  • EXTERNAL_AUTH_API_URL = "https://pj-auth-api.vercel.app"
  • EXTERNAL_AUTH_ENDPOINT = "/api/auth/login"
  • EXTERNAL_AUTH_TIMEOUT = 30 (seconds)
  • USE_EXTERNAL_AUTH = true (feature flag for gradual rollout)
  • TOKEN_REFRESH_BUFFER = 300 (refresh tokens 5 minutes before expiry)

Security Considerations

• HTTPS required for all authentication requests
• Token storage must be secure (HTTPOnly cookies or secure session storage)
• Implement rate limiting for authentication attempts
• Log all authentication events for audit trail
• Validate SSL certificates for external API calls
• Handle network failures gracefully with appropriate error messages

Rollback Strategy

• Keep existing authentication code with feature flag
• Maintain password column in database (don't drop immediately)
• Implement dual authentication mode during transition:
  • If USE_EXTERNAL_AUTH=true: Use external API
  • If USE_EXTERNAL_AUTH=false: Use local authentication
• Provide migration script to sync existing users with external system

Migration Plan

1. Phase 1: Implement external API authentication alongside existing system
2. Phase 2: Test with subset of users (based on domain or user flag)
3. Phase 3: Gradual rollout to all users
4. Phase 4: Deprecate local authentication (keep code for emergency)
5. Phase 5: Remove local authentication code (after stable period)

Risks and Mitigations

Risks

1. External API Unavailability: Authentication service downtime blocks all logins

   • Mitigation: Implement fallback to local auth, cache tokens, implement retry logic

2. Token Expiration Handling: Users may be logged out unexpectedly

   • Mitigation: Implement automatic token refresh before expiration

3. Network Latency: Slower authentication due to external API calls

   • Mitigation: Implement proper timeout handling, async requests, response caching

4. Data Consistency: User information mismatch between local DB and external system

   • Mitigation: Regular sync jobs, use external system as single source of truth

5. Breaking Change: Existing sessions will be invalidated

   • Mitigation: Provide migration window, clear communication to users

Success Criteria

• All users can authenticate via external API
• Authentication response time < 2 seconds (95th percentile)
• Zero data loss during migration
• Automatic token refresh works without user intervention
• Proper error messages for all failure scenarios
• Audit logs capture all authentication events
• Rollback procedure tested and documented