mcp-cisco-support

# OAuth 2.1 Implementation Summary ## Overview This document summarizes the complete OAuth 2.1 authentication implementation for the MCP Cisco Support server, which resolves [GitHub Issue #1](https://github.com/sieteunoseis/mcp-cisco-support/issues/1). ## What Was Implemented ### Core OAuth 2.1 Features 1. **Full OAuth 2.1 Authorization Server** (`src/oauth2.ts`) - Authorization Code Flow with PKCE (RFC 7636) - Token endpoint with multiple authentication methods - Dynamic Client Registration (RFC 7591) - Client ID Metadata Document (CIMD) support - Protected Resource Metadata (RFC 9728) - HTTP Basic Auth support (RFC 6749 Section 2.3.1) - Refresh token support 2. **Fine-Grained Access Control via Scopes** - `mcp` - Full access to all APIs (default) - `mcp:bug` - Bug Search API only - `mcp:case` - Case Management API only - `mcp:eox` - End-of-Life API only - `mcp:psirt` - Security Advisory API only - `mcp:product` - Product Information API only - `mcp:software` - Software Suggestions API only - `mcp:serial` - Serial Number API only - `mcp:rma` - RMA API only - `mcp:smart_bonding` - Smart Bonding API only (experimental) 3. **JSON-Based Client Configuration** - Pre-configured client support with hot reload - Separate secrets file for enhanced security - Support for both public (PKCE-only) and confidential (with secret) clients - Client enable/disable without server restart 4. **Security Features** - PKCE required for all authorization code flows - S256 code challenge method support - State parameter validation - Redirect URI validation (with wildcard support for localhost) - Token expiration and refresh - Proper authentication bypass fix (critical security bug) ## Files Created/Modified ### Core Implementation - `src/oauth2.ts` - Complete OAuth 2.1 authorization server - `src/sse-server.ts` - Updated to include OAuth metadata endpoints ### Configuration Files - `config/oauth-clients.json` - Active client configuration (gitignored) - `config/oauth-secrets.json` - Client secrets (gitignored) - `config/oauth-clients.example.json` - Template with scope examples - `config/oauth-secrets.example.json` - Secrets template ### Documentation - `docs/OAUTH_CLIENTS_CONFIG.md` - Complete configuration guide - `OAUTH_SCRIPTS.md` - NPM script reference - `OAUTH_2.1_IMPLEMENTATION_SUMMARY.md` - This document ### Configuration Updates - `.gitignore` - Added OAuth config files - `.env.example` - Added OAuth environment variables - `package.json` - Added OAuth convenience scripts ## OAuth 2.1 Endpoints ### Discovery Endpoints (Public) - `GET /.well-known/oauth-authorization-server` - Authorization server metadata - `GET /.well-known/oauth-protected-resource/mcp` - Protected resource metadata ### OAuth Flow Endpoints (Public) - `GET /authorize` - Authorization endpoint (displays consent page) - `POST /authorize/approve` - Authorization approval - `POST /token` - Token endpoint (supports multiple grant types) - `POST /register` - Dynamic client registration (optional) ### Protected Endpoints (Require OAuth) - `POST /mcp` - MCP JSON-RPC endpoint - `GET /sse` - Server-Sent Events connection - All other MCP tool endpoints ## Authentication Modes The server now supports **three authentication modes**: ### 1. stdio Mode (No Auth) ```bash npx mcp-cisco-support ``` - Used by Claude Desktop and local MCP clients - No authentication required (inherits from host) ### 2. Bearer Token Mode (HTTP) ```bash npx mcp-cisco-support --http export MCP_BEARER_TOKEN=your_token ``` - Simple token-based authentication - Backward compatible with existing setups ### 3. OAuth 2.1 Mode (HTTP) ✨ NEW ```bash AUTH_TYPE=oauth2.1 npx mcp-cisco-support --http # or npm run oauth:dev ``` - Industry-standard OAuth flows - Pre-configured and dynamic clients - Fine-grained scope-based access control ## Configuration Examples ### Example 1: Full Access Client (Development) ```json { "client_id": "mcp_inspector_dev", "client_uri": "http://localhost:6274", "redirect_uris": [ "http://localhost:6274/oauth/callback", "http://localhost:6274/oauth/callback/debug" ], "scopes": ["mcp"], "grant_types": ["authorization_code"], "description": "MCP Inspector - Local Development (public client with PKCE)", "enabled": true } ``` ### Example 2: Limited Scope Client (Production) ```json { "client_id": "bug_search_app", "client_uri": "https://bugs.company.com", "redirect_uris": ["https://bugs.company.com/oauth/callback"], "scopes": ["mcp:bug", "mcp:psirt"], "grant_types": ["authorization_code", "refresh_token"], "description": "Bug Search Application - Limited to Bug and Security APIs only", "enabled": true } ``` ### Example 3: Confidential Client with Secret ```json // In oauth-clients.json { "client_id": "mcp_inspector_prod", "client_uri": "http://localhost:6274", "redirect_uris": [ "http://localhost:6274/oauth/callback", "http://localhost:6274/oauth/callback/debug" ], "scopes": ["mcp"], "grant_types": ["authorization_code", "refresh_token"], "description": "MCP Inspector - Production (confidential client)", "enabled": true } // In oauth-secrets.json { "secrets": { "mcp_inspector_prod": "supersecretproductionkey123changeme" } } ``` ## Testing Summary ### Successful Test Scenarios 1. **MCP Inspector v0.17.2 Connection** - ✅ OAuth discovery via `.well-known` endpoints - ✅ Dynamic client registration - ✅ Authorization code flow with PKCE - ✅ Token exchange - ✅ Authenticated MCP tool calls 2. **Pre-configured Clients** - ✅ Hot reload of client configuration - ✅ Separate secrets file loading - ✅ Both public and confidential client types - ✅ Multiple redirect URIs per client 3. **Security Testing** - ✅ Authentication bypass bug fixed - ✅ Redirect URI validation - ✅ PKCE validation - ✅ Proper 401 responses for unauthenticated requests ## Critical Bug Fixes ### Authentication Bypass Bug (CRITICAL) **Problem**: All MCP endpoints were publicly accessible without authentication because `'/'` in the `publicPaths` array matched every path. **Fix**: Changed to exact match for root path only: ```typescript // Check for exact match on root path only if (req.path === '/') { return next(); } // Check other public paths with startsWith if (publicPaths.some(path => req.path.startsWith(path))) { return next(); } ``` This ensures only explicitly public endpoints (OAuth discovery, authorization, token) are accessible without authentication. ## NPM Scripts ```bash # Development mode (auto-reload) npm run oauth:dev # Production mode npm run oauth:start # Test OAuth metadata npm run oauth:test ``` ## Environment Variables ```bash # OAuth 2.1 Configuration AUTH_TYPE=oauth2.1 # Enable OAuth mode OAUTH2_ISSUER_URL=https://your-server.com # Optional custom issuer OAUTH_CLIENTS_CONFIG=config/oauth-clients.json # Client config path OAUTH_SECRETS_CONFIG=config/oauth-secrets.json # Secrets file path ``` ## Integration with MCP Clients ### MCP Inspector 1. Select "OAuth 2.0 Auto-Discovery" 2. Enter server URL: `http://localhost:3000/mcp` 3. MCP Inspector automatically discovers OAuth endpoints 4. Complete authorization flow in browser 5. Access MCP tools with OAuth token ### Custom Clients 1. Fetch `/.well-known/oauth-authorization-server` for endpoints 2. Implement authorization code flow with PKCE 3. Request appropriate scopes for your use case 4. Use access token in `Authorization: Bearer <token>` header ## Security Best Practices 1. **Never commit secrets** - `config/oauth-secrets.json` is gitignored - Use environment variables for production secrets 2. **Use separate secrets file** - Keep client metadata in version control - Keep secrets out of version control 3. **Disable dynamic registration in production** ```json { "settings": { "allow_dynamic_registration": false } } ``` 4. **Use HTTPS in production** - All redirect URIs should use `https://` - Only allow `http://localhost` for development 5. **Use least privilege scopes** - Only grant scopes that the application needs - Avoid using `mcp` scope unless full access is required 6. **Rotate secrets periodically** - Update `oauth-secrets.json` regularly - Server hot-reloads automatically ## How This Resolves GitHub Issue #1 GitHub Issue #1 requested OAuth 2.0 authentication support based on MCP specifications. This implementation: ✅ **Implements OAuth 2.1** - Latest OAuth standard with security enhancements ✅ **Maintains backward compatibility** - Bearer token auth still works ✅ **Provides standardized authentication** - Industry-standard flows ✅ **Better security** - PKCE, scopes, client types ✅ **Seamless MCP integration** - Works with MCP Inspector and other clients ✅ **Future compatibility** - Follows OAuth 2.1 best practices ✅ **Complete documentation** - Setup guides, examples, troubleshooting ✅ **Comprehensive testing** - Validated with real OAuth clients ## Migration Guide ### For Existing Users (Bearer Token) No changes required! Bearer token authentication continues to work: ```bash # Still works exactly as before export MCP_BEARER_TOKEN=your_token npx mcp-cisco-support --http ``` ### For New Users (OAuth 2.1) 1. **Copy example configuration**: ```bash cp config/oauth-clients.example.json config/oauth-clients.json cp config/oauth-secrets.example.json config/oauth-secrets.json ``` 2. **Edit configuration** for your clients 3. **Start server**: ```bash npm run oauth:dev ``` 4. **Connect MCP clients** using OAuth discovery ## Next Steps 1. ✅ Merge with main branch (v1.18.0) 2. ✅ Bump version to v1.19.0 3. ✅ Update README.md with OAuth 2.1 features 4. ✅ Close GitHub Issue #1 5. ✅ Create release notes ## References - [OAuth 2.1 Specification](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-07) - [PKCE (RFC 7636)](https://datatracker.ietf.org/doc/html/rfc7636) - [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) - [Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728) - [Model Context Protocol](https://modelcontextprotocol.io/) - [MCP Authentication Documentation](https://spec.modelcontextprotocol.io/specification/2025-11-05/authentication/) ## Conclusion This implementation provides a production-ready, standards-compliant OAuth 2.1 authorization server integrated into the MCP Cisco Support server. It offers: - **Security**: Industry-standard authentication with PKCE - **Flexibility**: Multiple client types and fine-grained scopes - **Usability**: Hot reload, auto-discovery, comprehensive documentation - **Compatibility**: Works alongside existing Bearer token authentication The OAuth 2.1 implementation fully resolves GitHub Issue #1 and positions the server for seamless integration with the evolving MCP ecosystem.