OAuth 2.1: Phase 4 - Advanced Features and Security Enhancements

[richardwooding]

Overview

Implement advanced OAuth 2.1 features for enhanced security, usability, and enterprise readiness.

Prerequisites

• Phase 1 (Core OAuth) completed ✅
• Phase 2 (Discovery & Refresh) recommended
• Phase 3 (GitHub Actions) recommended

Phase 4 Goals

Add enterprise-grade features and security enhancements to the OAuth implementation.

Tasks

Dynamic Client Registration (RFC 7591)

• Implement DCR for automatic client registration
• Add --oauth-use-dcr flag to enable DCR
• Handle registration endpoint discovery
• Support for client metadata (redirect_uris, grant_types, etc.)
• Store registered client credentials securely
• Automatic re-registration on client_id expiry

OS Keychain Integration

• macOS Keychain Services integration
• Windows Credential Manager support
• Linux Secret Service (freedesktop.org) support
• Add --oauth-use-keychain flag
• Fallback to file-based storage if keychain unavailable
• Migration utility for existing file-based tokens

Token Revocation (RFC 7009)

• Implement token revocation on logout
• Add mcp-server-dump logout command
• Revoke tokens when clearing cache
• Support for revocation endpoint discovery
• Handle revocation errors gracefully

Token Introspection (RFC 7662)

• Implement token introspection endpoint support
• Validate token status before use
• Add --oauth-introspect flag to check token validity
• Better scope validation
• Audience claim verification

Multi-Server Token Management

• Token management CLI commands:
  • mcp-server-dump oauth list - List cached tokens
  • mcp-server-dump oauth revoke <server> - Revoke specific token
  • mcp-server-dump oauth clear - Clear all tokens
  • mcp-server-dump oauth info <server> - Show token details
• Interactive token selection for multiple servers
• Token expiry warnings
• Automatic cleanup of expired tokens

Headless/SSH Support

• Detect headless environment (no DISPLAY, no browser)
• Print authorization URL to console
• Accept authorization code via stdin
• Support for out-of-band (oob) redirect URIs
• Manual code entry flow

Configuration File Support

• OAuth config file: ~/.config/mcp-server-dump/oauth.yaml
• Per-server configuration profiles
• Default client ID/secret storage
• Scope templates
• Priority: CLI flags > env vars > config file > defaults

Security Enhancements

• Certificate pinning for authorization servers (optional)
• Configurable HTTPS enforcement
• Token binding (RFC 8471) support
• Pushed Authorization Requests (PAR, RFC 9126)
• JWT access token validation
• Audience claim validation (prevent token passthrough)

Scope Management

• Automatic scope detection from server capabilities
• Scope-specific error handling
• Add --oauth-request-all-scopes flag
• Interactive scope selection (optional)
• Scope upgrade flow (request additional scopes)

Logging and Debugging

• Add --oauth-debug flag for verbose OAuth logging
• Log OAuth flow steps (without secrets)
• Token refresh event logging
• Discovery process logging
• Debug-friendly error messages

Example Usage

Dynamic Client Registration

mcp-server-dump --transport=streamable \
  --endpoint="https://mcp.example.com/stream" \
  --oauth-use-dcr

OS Keychain Integration

mcp-server-dump --transport=streamable \
  --endpoint="https://mcp.example.com/stream" \
  --oauth-client-id="..." \
  --oauth-use-keychain

Token Management

# List all cached tokens
mcp-server-dump oauth list

# Revoke token for specific server
mcp-server-dump oauth revoke https://mcp.example.com/stream

# Clear all tokens
mcp-server-dump oauth clear

# Show token info
mcp-server-dump oauth info https://mcp.example.com/stream

Configuration File

# ~/.config/mcp-server-dump/oauth.yaml
servers:
  - endpoint: https://mcp.example.com/stream
    client_id: your-client-id
    scopes:
      - mcp:tools
      - mcp:resources
    use_keychain: true
    
  - endpoint: https://staging.example.com/stream
    client_id: staging-client-id
    use_dcr: true

defaults:
  scopes:
    - mcp:tools
    - mcp:resources
    - mcp:prompts
  use_keychain: true
  redirect_port: 0

Success Criteria

• DCR works with supporting authorization servers
• Tokens stored securely in OS keychain
• Token management commands work correctly
• Configuration file support functional
• Headless/SSH authentication works
• Comprehensive security features enabled

Estimated Timeline

2-3 weeks of development + testing

Dependencies

• github.com/99designs/keyring - Cross-platform keychain access
• github.com/pkg/browser - Browser launching (already using os/exec)

Security Considerations

• Never log tokens, secrets, or authorization codes
• Clear sensitive data from memory when possible
• Use secure random generation for state/nonce
• Validate all server-provided URLs
• Implement rate limiting for token requests

References

• RFC 7591: OAuth 2.0 Dynamic Client Registration
• RFC 7009: OAuth 2.0 Token Revocation
• RFC 7662: OAuth 2.0 Token Introspection
• RFC 8471: Token Binding
• RFC 9126: OAuth 2.0 Pushed Authorization Requests
• OAuth 2.1 Draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13