[FEATURE][AUTH]: OAuth Enhancement Following PR 768

Goal

Complete the OAuth 2.0 implementation started in PR #768 by addressing remaining gaps: token management UI, OAuth coverage for resources/prompts, automated cleanup, and provider templates. Several items (refresh tokens, PKCE) are already implemented.

Why Now?

1. Production Readiness: Organizations need complete OAuth lifecycle management
2. User Experience: Manual token management is error-prone
3. Security Compliance: Proper token rotation and cleanup required for audits
4. Enterprise Adoption: Large organizations require comprehensive OAuth support

Status Summary

📖 User Stories

Scenario: View OAuth tokens list
  Given I am logged in as an admin
  When I navigate to "OAuth Tokens" in the Admin UI
  Then I should see a list of all OAuth authorizations
  And each entry should show: user, gateway, scopes, expiration status

Scenario: View token details
  Given an OAuth token exists for user "alice@example.com"
  When I click on the token entry
  Then I should see: creation time, last used, scopes granted, expiration
  And I should NOT see the actual token value

Scenario: Revoke user token
  Given an OAuth token exists for user "alice@example.com"
  When I click "Revoke" on the token entry
  Then the token should be deleted
  And the user should need to re-authorize on next access

Scenario: OAuth for resource access
  Given gateway "github-mcp" requires OAuth
  When I request resource "repo-list"
  Then OAuth authorization should be triggered if no valid token
  And the resource should be fetched with the OAuth token

Scenario: OAuth for prompt execution
  Given gateway "github-mcp" requires OAuth
  When I execute prompt "pr-summary"
  Then the prompt execution should use the OAuth token
  And the response should include data from authenticated API calls

Scenario: Scheduled cleanup
  Given OAuth tokens older than retention period exist
  When the cleanup job runs (every 24 hours)
  Then expired tokens should be deleted
  And a cleanup metrics event should be logged

Scenario: Configurable retention
  Given OAUTH_TOKEN_RETENTION_DAYS=30
  And tokens from 45 days ago exist
  When cleanup runs
  Then the 45-day-old tokens should be deleted
  And tokens from 20 days ago should be preserved

Scenario: Select GitHub template
  Given I am creating a new gateway with OAuth
  When I select "GitHub" from OAuth provider dropdown
  Then authorization_url should auto-fill: "https://github.com/login/oauth/authorize"
  And token_url should auto-fill: "https://github.com/login/oauth/access_token"

Scenario: Custom provider
  Given I am creating a gateway with a custom OAuth provider
  When I select "Custom" from the dropdown
  Then I should be able to enter all OAuth fields manually

🏗 Architecture

Token Management Flow

sequenceDiagram
    participant Admin as Admin UI
    participant API as Token API
    participant DB as OAuthToken Table
    participant Cleanup as Cleanup Job

    Admin->>API: GET /admin/oauth/tokens
    API->>DB: Query tokens with metadata
    DB-->>API: Token list (no secrets)
    API-->>Admin: Display tokens

    Admin->>API: DELETE /admin/oauth/tokens/{id}
    API->>DB: Delete token
    API-->>Admin: Token revoked

    Cleanup->>DB: DELETE WHERE expires_at < retention
    DB-->>Cleanup: Deleted count

OAuth Coverage Extension

flowchart TD
    A[MCP Request] --> B{Request Type}
    B -->|tools/call| C[Tool OAuth Handler]
    B -->|resources/read| D[Resource OAuth Handler]
    B -->|prompts/get| E[Prompt OAuth Handler]

    C --> F[Token Storage Service]
    D --> F
    E --> F

    F --> G{Token Valid?}
    G -->|Yes| H[Execute with Token]
    G -->|No| I[Refresh or Re-auth]
    I --> H

📋 Implementation Tasks

Phase 1: Token Management UI

• Add /admin/oauth/tokens endpoint
• Create OAuth Tokens section in Admin UI
• Display token list with metadata
• Add revoke single token functionality
• Add bulk revoke functionality

Phase 2: OAuth for Resources

• Extend gateway_service.py resource fetching with OAuth
• Add token lookup before resource requests
• Handle OAuth errors in resource responses

Phase 3: OAuth for Prompts

• Extend prompt execution with OAuth support
• Add token handling in prompt rendering

Phase 4: Automated Cleanup

• Add OAUTH_TOKEN_RETENTION_DAYS setting
• Implement cleanup task in background scheduler
• Add cleanup metrics and logging
• Test cleanup with large token sets

Phase 5: Provider Templates

• Define template schema
• Add templates for: GitHub, Google, Microsoft, Okta, Auth0
• Update Admin UI gateway form with template dropdown
• Add "Custom" option for manual configuration

Phase 6: Debug Code Cleanup (Tech Debt)

• Remove print statements from oauth_manager.py
• Remove print statements from gateway_service.py
• Replace with proper logger calls

⚙️ Configuration Example

# OAuth Token Management
OAUTH_TOKEN_RETENTION_DAYS=90
OAUTH_CLEANUP_ENABLED=true
OAUTH_CLEANUP_INTERVAL_HOURS=24

# Provider Templates (built-in, no config needed)
# Templates auto-populate: GitHub, Google, Microsoft, Okta, Auth0

✅ Success Criteria

• Admin UI shows all OAuth authorizations
• Tokens can be revoked individually and in bulk
• OAuth works for tools, resources, and prompts
• Expired tokens are automatically cleaned up
• Provider templates simplify gateway configuration
• Debug print statements removed

🏁 Definition of Done

• Token management UI implemented
• OAuth extended to resources and prompts
• Automated cleanup running
• Provider templates available
• Unit tests for all new functionality (>90% coverage)
• Integration tests with real OAuth providers
• Debug code removed
• Code passes make verify
• Documentation updated

🔗 Related Issues

• PR feat: Experimental Oauth 2.0 support in gateway #768 - Original OAuth 2.0 implementation
• mcpgateway/services/token_storage_service.py - Token storage
• mcpgateway/services/oauth_manager.py - OAuth flows
• Migration: add_oauth_tokens_table.py