OAuth 2.1: Phase 2 - Automatic Discovery and Token Refresh Enhancements

[richardwooding]

Overview

Enhance the OAuth 2.1 implementation with improved automatic discovery and token refresh capabilities.

Phase 1 Status

✅ Core authorization code flow with PKCE implemented in main branch

Phase 2 Goals

Improve the OAuth discovery and refresh mechanisms for a more polished user experience.

Tasks

Discovery Enhancements

• Improve WWW-Authenticate header parsing robustness
• Add support for multiple authorization servers in metadata
• Better error messages when discovery fails
• Cache discovered metadata to avoid repeated lookups
• Add --oauth-discover flag to test discovery without connecting

Token Refresh Improvements

• Preemptive token refresh (refresh before expiry)
• Configurable refresh buffer time (e.g., refresh 5 minutes before expiry)
• Better handling of refresh token errors
• Retry logic for transient refresh failures
• Log token refresh events (optional verbose mode)

Error Handling

• Detect and handle specific OAuth error codes (invalid_grant, etc.)
• Provide actionable error messages with remediation steps
• Handle authorization server downtime gracefully
• Support for token revocation on errors

Configuration

• Support for OAuth config file (~/.config/mcp-server-dump/oauth.yaml)
• Per-server OAuth configuration profiles
• Environment variable support (OAUTH_CLIENT_ID, etc.)

Success Criteria

• Discovery works without manual endpoint configuration
• Tokens refresh automatically without user intervention
• Long-running operations (>1 hour) work seamlessly
• Clear error messages guide users to solutions

Estimated Timeline

1 week of development + testing

Dependencies

• Phase 1 (Core OAuth) must be completed
• golang.org/x/oauth2 v0.33.0+

References

• RFC 9728: OAuth 2.0 Protected Resource Metadata
• RFC 8414: OAuth 2.0 Authorization Server Metadata
• MCP Authorization Specification: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization