feat: Experimental Oauth 2.0 support in gateway

[shams858]

🚀 Add OAuth 2.0 Authorization-Code flow to MCP Gateway (Experimental)

This PR introduces OAuth 2.0 support (Authorization-Code & Client-Credentials) across the Gateway, Admin UI and Tool-invocation paths.

---

✨ What’s new

1 OAuth Manager

• Async wrapper around aiohttp that:
  • Generates authorization URLs (GET /oauth/authorize/{gateway_id})
  • Exchanges authorization codes for tokens
  • Refreshes / retries with exponential back-off
• Pluggable decryptor for encrypted client_secrets (future KMS integration).

2 Token Storage

• oauth_tokens table (Alembic migration add_oauth_tokens_table.py)
  Stores access_token, optional refresh_token, expires_at, user_id, gateway_id.

CREATE TABLE oauth_tokens (
    id           TEXT PRIMARY KEY,
    gateway_id   TEXT NOT NULL,
    user_id      TEXT NOT NULL,
    access_token TEXT NOT NULL,
    refresh_token TEXT,
    expires_at   TIMESTAMP,
    created_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX ix_oauth_tokens_gateway_user ON oauth_tokens (gateway_id, user_id);

3 Gateway Service + Routers

• New /oauth/callback & /oauth/fetch-tools/{gateway_id} endpoints.
• GatewayService.fetch_tools_after_oauth() pulls tools/resources/prompts once the user finishes the consent screen.
• Admin UI surface (template / admin.js) to start / monitor OAuth.

4 Tool Service integration

Tools tagged with auth_type="oauth" automatically:

1. Look up a valid token in TokenStorageService
2. Refresh (if refresh_token present & near expiry)
3. Inject Authorization: Bearer <token> header.

5 Unit tests

• new tests covering:
  • happy-path for both flows
  • retry / refresh logic
  • DB migration up/down
• Existing suites adapted (mocks for async context-managers).

6 Docs

• docs/architecture/oauth-authorization-code-ui-design.md – sequence diagram, UI wireframe, curl examples.

---

🖼️ High-level flow

sequenceDiagram
    participant U as Browser
    participant A as Admin UI
    participant G as Gateway API
    participant GH as GitHub OAuth

    U->>A: Click "Authorize"
    A->>G: GET /oauth/authorize/{gateway}
    G->>GH: Redirect (client_id, redirect_uri, state)
    GH-->>U: Consent Screen
    U-->>GH: Approve
    GH->>G: 302  /oauth/callback?code&state
    G->>GH: POST /access_token (code,…)
    GH-->>G: access_token
    G->>DB:  INSERT oauth_tokens
    G-->>A: 200 OK (tools fetched)

Loading

---

🔧 Migration / Deployment

1. Run Alembic
   alembic upgrade head
2. Env vars (optional)

   OAUTH_REQUEST_TIMEOUT=30
   OAUTH_MAX_RETRIES=3
   

3. Configure Gateways (example):

   {
     "name": "Github",
     "url": "https://api.githubcopilot.com/mcp/",
     "transport": "STREAMABLEHTTP",
     "auth_type": "oauth",
     "oauth_config": {
       "grant_type": "authorization_code",
       "client_id": "xxxx",
       "client_secret": "Z0FBQUFB...",
       "authorization_url": "https://github.com/login/oauth/authorize",
       "token_url": "https://github.com/login/oauth/access_token",
       "redirect_uri": "http://<gateway>/oauth/callback",
       "scopes": ["repo","user","email"],
       "token_management": { "store_tokens": true, "auto_refresh": true }
     }
   }

---

⚠️ Limitations & Next steps

• Refresh-token support is provider-dependent – refresh flow untested.
• Multi-user separation is basic (user_id extracted from token response or fallback). Full RBAC still TODO.
• Implement PKCE according to OAuth 2.1 standard and other authorization flow standards according to MCP specification.
• Only tools are saved, prompts and resources saving implementation is pending.
• Admin UI improvement needed.
• Health-check for OAuth gateways is skipped until first successful consent.
• Linter surfaces many # type: ignore fixes we will address post-merge.
• Remove code duplication.
• Increase Unit test coverage.
• Rigorous testing of the end to end flow.
• Gateway status check.

---

Add Gateway with Oauth

---

Redirect, User Consent, Authorize and Fetch and Save tools

---

List Tools

---

Tool Test/Invoke

---

List Gateway with auth_type == oauth

---

Initial attempt to address this feature #605.

Thanks for reviewing!

[crivetimihai]

This is awesome! Will rebase, fix merge conflicts, test and push upstream. Review in progress.

[crivetimihai]

PR 768 Review: OAuth 2.0 Support in MCP Gateway

✅ Review Summary

APPROVED - This PR successfully implements OAuth 2.0 support addressing the core requirements from Issue #605. The implementation provides a solid foundation for OAuth-based per-user access to remote MCP servers.

Remaining tasks tracked in #782, closes #605

Issue Requirements vs Implementation

Requirement	Status	Implementation
Connect to remote MCP servers without local setup	✅ COMPLETE	SSE/HTTP transport with OAuth authentication
OAuth support for per-user credentials	✅ COMPLETE	Authorization Code + Client Credentials flows
Multiple user credentials (not shared PAT)	✅ COMPLETE	Per-user token storage with encryption
GitHub MCP server compatibility	✅ COMPLETE	OAuth configuration supports GitHub's flow

Architecture Review

✅ Strengths

• Clean OAuth abstraction with OAuthManager handling both grant types
• Secure token storage with encryption using AUTH_ENCRYPTION_SECRET
• Database schema properly designed with foreign keys and indexes
• UI integration with Admin UI forms and authorization flows
• Error handling with clear user guidance for OAuth setup
• Security best practices including CSRF protection via state parameters

✅ Code Quality

• Comprehensive testing with unit tests for OAuth flows
• Type hints and proper documentation throughout
• Database migrations properly structured
• Following project conventions for error handling and logging

🔧 Issues Fixed During Review

1. Code Quality & Linting

• ❌ Pylint issues (9.98/10 → 10.00/10)
  • Fixed import-outside-toplevel violations
  • Removed unnecessary else clauses after returns
  • Added pylint disable comments for unavoidable cases
  • Fixed import order (standard before third-party)
  • Fixed implicit string concatenation

2. Database Migration Issues

• ❌ Multiple Alembic heads causing CI/CD failures
  • Root cause: OAuth migrations created parallel migration chains
  • Fixed: Updated f8c9d3e2a1b4 to follow 34492f99a0c4 instead of eb17fd368f9d
  • Removed: Unnecessary merge migration hack (813b45a70b53)
  • Result: Clean linear migration chain without parallel branches

3. Branch Integration

• ❌ Merge conflicts with main branch
  • Fixed: Merged latest main branch features including metadata capture
  • Preserved: All OAuth functionality during merge
  • Combined: OAuth features + export/import + security headers + metadata tracking

📋 Remaining TODOs for Future Enhancements

High Priority

• Implement refresh token flow - Currently placeholder in token_storage_service.py:208
• Enhance user identification - Better user ID extraction from token responses
• Add token management UI - Admin interface for viewing/revoking user tokens
• Resource & prompt fetching - OAuth implementation focuses on tools, expand to other entities

Medium Priority

• PKCE support - OAuth 2.1 standard for enhanced security
• Token cleanup job - Automated cleanup of expired tokens
• Multi-user token selection - UI for choosing which user's tokens to use
• OAuth provider templates - Pre-configured settings for GitHub, Google, etc.

Low Priority

• OAuth token introspection - Validate tokens with OAuth provider
• Scope management - Fine-grained permission control
• OAuth audit logging - Track OAuth operations for compliance
• Performance optimization - Token caching and connection pooling

🧪 Quality Metrics

Test Coverage

• Unit Tests: ✅ 2116 passed, 15 skipped
• OAuth Manager: ✅ 7 test methods covering happy/error paths
• Integration Tests: ✅ All passing
• Doctests: ✅ 489 passed, 6 skipped

Code Quality Scores

• Pylint: ✅ 10.00/10 (perfect score)
• Flake8: ✅ No violations
• Bandit: ✅ Security checks passed
• Coverage: ✅ 76% overall coverage
• Verify: ✅ Package build/distribution checks passed

🎯 Implementation Highlights

Core Components Added

mcpgateway/
├── services/
│   ├── oauth_manager.py          # OAuth 2.0 flow management
│   └── token_storage_service.py  # Encrypted token storage
├── routers/
│   └── oauth_router.py          # OAuth endpoints (/oauth/*)  
├── utils/
│   └── oauth_encryption.py     # Token encryption utilities
├── alembic/versions/
│   ├── f8c9d3e2a1b4_*.py      # OAuth config column
│   └── add_oauth_tokens_table.py # OAuth tokens table
└── db.py                        # OAuthToken ORM model

Key Features

• Authorization Code Flow: User consent with redirect to OAuth provider
• Client Credentials Flow: Machine-to-machine authentication
• Token Encryption: All sensitive tokens encrypted at rest
• Admin UI Integration: OAuth configuration in gateway creation
• Tool Integration: Automatic OAuth token injection for MCP tool calls

🔄 CI/CD Status

Before Fixes

• ❌ Multiple Alembic heads error
• ❌ Pylint violations (9.98/10)
• ❌ Import/code style issues

After Fixes

• ✅ Single Alembic migration head
• ✅ Perfect Pylint score (10.00/10)
• ✅ All quality checks passing
• ✅ Clean merge with main branch

📝 Recommendation

APPROVE AND MERGE - This PR provides excellent OAuth 2.0 foundation that fully addresses Issue #605 requirements. The implementation follows security best practices, maintains high code quality, and integrates well with the existing architecture.

The remaining TODOs are enhancements rather than blockers, and can be addressed in future iterations.

[crivetimihai]

@shams858 thanks, merging - remaining tasks tracked in #782

@madhav165 please test as well.

[madhav165]

Worked as shown in the PR.

[sbweeden]

I know this PR is merged and closed, but how should I correctly report/suggest additional remaining TODO's?

In particular I noticed that in the admin UI when I edit an existing MCP server configuration, none of the existing OAuth configuration is visible or editable.