[Feature Request]: OAuth Enhancement following PR 768

[crivetimihai]

OAuth Enhancement Ticket

Related: PR #768 OAuth 2.0 Support
Status: Follow-up Work
Priority: High
Milestone: Release 0.7.0

Background

PR #768 successfully implemented OAuth 2.0 foundation with Authorization Code and Client Credentials flows. This ticket tracks remaining enhancements identified during review.

High Priority Items

1. Implement Refresh Token Handling

Location: mcpgateway/services/token_storage_service.py:208
Issue: Currently placeholder implementation
Impact: Tokens can't be automatically refreshed when they expire

Requirements:

• Implement _refresh_access_token() method
• Add OAuth provider refresh endpoint calls
• Handle refresh token expiration
• Update stored tokens after successful refresh
• Add error handling for refresh failures

2. Enhanced User ID Mapping

Location: mcpgateway/services/oauth_manager.py:561
Issue: Uses placeholder user ID extraction
Impact: Poor user identification and token association

Requirements:

• Extract real user ID from token response
• Make userinfo API calls to OAuth providers
• Support multiple OAuth provider user ID formats
• Add configurable user ID extraction strategies

3. Token Management UI

Location: Admin UI (mcpgateway/templates/admin.html)
Issue: No interface for managing stored tokens
Impact: No visibility into OAuth authorizations

Requirements:

• Add "OAuth Tokens" section to Admin UI
• Display authorized users per gateway
• Token expiration status and refresh capability
• Revoke token functionality
• Bulk token cleanup tools

Medium Priority Items

4. OAuth for Resources and Prompts

Location: mcpgateway/services/gateway_service.py
Issue: OAuth only implemented for tools
Impact: Incomplete OAuth coverage

Requirements:

• Extend OAuth authentication to resource fetching
• Add OAuth support for prompt operations
• Update gateway service to handle OAuth for all entity types
• Test OAuth flows with all MCP capabilities

5. PKCE Support (OAuth 2.1)

Location: mcpgateway/services/oauth_manager.py
Issue: Missing PKCE for enhanced security
Impact: Less secure authorization flows

Requirements:

• Generate code verifier and challenge
• Include PKCE in authorization URLs
• Validate PKCE in token exchange
• Support both SHA256 and plain challenge methods

6. Automated Token Cleanup

Location: mcpgateway/services/token_storage_service.py:321
Issue: Manual cleanup only
Impact: Database bloat with expired tokens

Requirements:

• Scheduled cleanup job for expired tokens
• Configurable retention policies
• Cleanup metrics and logging
• Integration with gateway health checks

Low Priority Items

7. OAuth Provider Templates

Location: Admin UI gateway creation
Issue: Manual OAuth configuration required
Impact: User experience friction

Requirements:

• Pre-configured OAuth settings for popular providers
• GitHub, Google, Microsoft provider templates
• Auto-population of common OAuth endpoints
• Provider-specific documentation links

8. Advanced Token Features

Location: Various OAuth components
Issue: Basic token handling only
Impact: Limited enterprise features

Requirements:

• Token introspection with OAuth providers
• Scope validation and management
• OAuth audit logging for compliance
• Token rotation policies

Technical Debt

9. Remove Debug Code

Location: Various files with print() statements
Issue: Debug prints left in production code
Impact: Log noise and unprofessional output

Files to clean:

• mcpgateway/services/oauth_manager.py:81,97,182,197
• mcpgateway/services/gateway_service.py:646,658-665,705-725

10. Error Message Improvements

Location: OAuth error handling
Issue: Generic error messages
Impact: Poor developer experience

Requirements:

• Provider-specific error interpretation
• Actionable error messages with next steps
• Error code mapping for common OAuth issues
• Troubleshooting documentation links

Success Criteria

Definition of Done

• All refresh token flows work end-to-end
• User ID extraction works with major OAuth providers
• Token management UI allows full CRUD operations
• OAuth works for tools, resources, and prompts
• PKCE implementation passes security audit
• Automated cleanup runs without issues
• Debug code removed from all production files
• Error messages provide clear next steps

Testing Requirements

• Unit tests for all new functionality (>90% coverage)
• Integration tests with real OAuth providers
• Security testing for PKCE and token handling
• Performance testing for token operations
• End-to-end testing with GitHub MCP server

Dependencies

• OAuth Provider Access: GitHub app registration for testing
• Security Review: For PKCE and token encryption validation
• UI/UX Design: For token management interface design
• Documentation: OAuth setup guides for different providers

[shams858]

PKCE Support Design Document

---

1 Overview

The Gateway currently supports OAuth 2.0 Client-Credentials and Authorization-Code flows but does not satisfy providers that mandate RFC 7636 Proof-Key for Code Exchange (PKCE). This document describes the design required to add first-class PKCE support while maintaining backward compatibility for existing gateways. PKCE support is key requirement from MCP specification as well.

2 Goals

• Allow any gateway configured with grant_type = "authorization_code" to optionally enable PKCE.
• Support the industry-standard S256 method (SHA-256) with room for future plain support.
• Keep code_verifiers secure (never log them, store with TTL, encrypt when at rest).
• No breaking changes for existing clients that do not enable PKCE.

3 Glossary

Term	Meaning
code_verifier	High-entropy cryptographically random string (43-128 chars) generated by the client.
code_challenge	Derived value sent on /authorize (base64url( SHA256( code_verifier ) )).
PKCE	Proof-Key for Code Exchange – adds verifier/challenge to mitigate stolen auth codes.

4 High-Level Flow

sequenceDiagram
    autonumber
    participant UI as Admin UI
    participant GW as MCP Gateway
    participant IDP as Identity Server

    UI->>GW: Configure gateway (PKCE enabled)
    GW->>GW: generate code_verifier + code_challenge
    GW->>IDP: GET /authorize?...&code_challenge=...&code_challenge_method=S256
    Note right of GW: store (state, code_verifier)
    IDP-->>UI: Redirect back with code & state
    UI->>GW: /oauth/callback?code=...&state=...
    GW->>GW: lookup code_verifier via (state)
    GW->>IDP: POST /token {code, code_verifier, ...}
    IDP-->>GW: {access_token, refresh_token, ...}
    GW->>DB: save tokens

Loading

5 Component Changes

5.1 Configuration Schema

{
  "grant_type": "authorization_code",
  // …existing fields…
  "pkce": {
    "enabled": true,
    "method": "S256" // only S256 supported initially
  }
}

Validation will live in the gateway Pydantic model (config-schema-pkce task).

5.2 PKCE Utilities (mcpgateway/utils/pkce_utils.py)

• generate_verifier() -> str (43 – 128 chars)
• challenge_from_verifier(verifier: str, method: str="S256") -> str

5.3 Verifier Storage

Option A – Extend TokenStorageService tables to hold code_verifier with expires_at.
Option B – Lightweight in-memory dict with asyncio-based TTL cleanup.
Chosen: A to survive restarts and share across workers.
New table oauth_pkce_state (gateway_id, state, code_verifier, expires_at).*
Reuse encryption helper for the verifier column.

5.4 OAuthManager Updates

1. _create_authorization_url
   • When PKCE enabled: generate verifier & challenge, store record, append params to URL.
2. _exchange_code_for_tokens
   • Retrieve verifier via (gateway_id, state); add code_verifier to POST body when present.
3. Cleanup task to purge expired PKCE records (>10 min).

5.5 Admin UI

• Add checkbox “Enable PKCE (S256)”.
• Hide client_secret field when pkce.enabled && public_client pattern in future (out-of-scope for now).

6 Error Handling & Edge Cases

• Missing verifier – return 400 and instruct user to restart flow.
• Expired verifier – treat same as missing (default TTL = 10 min).
• Provider rejects challenge – surface provider’s error to UI.

7 Security Considerations

• Verifier stored encrypted at rest.
• TTL cleanup prevents buildup.
• Verifier never logged.
• Admin UI treats verifier as secret, not displayed after creation.

8 Backward Compatibility

• Gateways with pkce.enabled = false continue unchanged.
• Database migrations are additive.

9 Testing Strategy

• Unit tests: pkce_utils, config validation.
• Integration: happy-path flow against local IdentityServer.
• Negative tests: missing verifier, wrong state, expired record.

10 Open Questions

1. Do we support plain method? (default: no)

Implementation Notes:

• PKCE should be implemented as an optional feature that can be enabled per gateway
• Default PKCE method should be S256 (SHA-256) for security
• Code verifiers are automatically generated and stored with 10-minute TTL
• Backward compatibility: existing OAuth flows continue unchanged
• Security: code verifiers are encrypted at rest and never logged

[sbweeden]

In the admin UI, at least with the current build, if I edit a Gateway MCP Server that was created with Authentication Type = OAuth 2.0, I don't see the OAuth configuration properties and cannot edit them. I end up having to delete and re-create the connection. Is the completion of edit capabilities in the Admin UI in scope for this feature request?

[sbweeden]

Also regarding PKCE, I wouldn't even include the support of plain method in a future roadmap. It's against security best current practices.