Mcp-Swagger-Server

# 企业级API认证方式详解 ## 概述 本文档详细解释了企业级API认证的各种方式，包括JWT令牌、API Key、Basic Auth、OAuth 2.0和自定义Header等。结合mcp-swagger-server项目的实际应用场景，帮助您理解每种认证方式的工作原理、使用场景和具体实现。 ## 1. JWT令牌认证 (Bearer Token) ### 1.1 什么是JWT JWT（JSON Web Token）是一种开放标准（RFC 7519），用于在网络应用环境间安全地传输信息。JWT令牌包含三个部分： ``` eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ``` 这个令牌分为三部分，用点（`.`）分隔： - **Header（头部）**：包含令牌类型和签名算法 - **Payload（载荷）**：包含用户信息和权限数据 - **Signature（签名）**：用于验证令牌的完整性 ### 1.2 JWT的结构详解 #### Header（头部） ```json { "alg": "HS256", "typ": "JWT" } ``` - `alg`: 签名算法（如HS256、RS256等） - `typ`: 令牌类型，固定为JWT #### Payload（载荷） ```json { "sub": "1234567890", "name": "John Doe", "iat": 1516239022, "exp": 1516242622, "roles": ["admin", "user"], "permissions": ["read", "write"] } ``` - `sub`: 用户ID - `name`: 用户名 - `iat`: 令牌签发时间 - `exp`: 令牌过期时间 - `roles`: 用户角色 - `permissions`: 用户权限 #### Signature（签名） ```javascript HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), secret ) ``` ### 1.3 在mcp-swagger-server中的应用 #### 1.3.1 配置方式 ```typescript const serverConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'bearer', credentials: { token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' } } }; ``` #### 1.3.2 HTTP请求示例 ```http GET /api/users/profile HTTP/1.1 Host: api.company.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... Content-Type: application/json ``` #### 1.3.3 实际应用场景 - **用户身份验证**：登录后获取JWT令牌 - **API访问控制**：每次API调用携带JWT令牌 - **权限管理**：基于JWT中的角色和权限信息控制访问 - **单点登录**：跨系统使用同一个JWT令牌 ### 1.4 JWT的优势和劣势 #### 优势 - **无状态**：服务器不需要存储会话信息 - **跨域友好**：可以在不同域名间使用 - **包含信息**：令牌本身包含用户信息和权限 - **标准化**：遵循RFC 7519标准 #### 劣势 - **令牌大小**：包含信息较多，令牌较大 - **安全性**：一旦泄露，在过期前都有效 - **撤销困难**：无法主动撤销未过期的令牌 ## 2. API Key认证 ### 2.1 什么是API Key API Key是一种简单的认证方式，使用一个静态的字符串作为身份标识。通常用于系统间的认证，而不是用户认证。 ### 2.2 API Key的特点 - **静态性**：一旦生成，通常长期有效 - **简单性**：实现和使用都很简单 - **系统级**：主要用于系统间认证 - **权限控制**：可以配置不同的权限级别 ### 2.3 在mcp-swagger-server中的应用 #### 2.3.1 配置方式 ```typescript const serverConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'apikey', credentials: { apiKey: 'sk-1234567890abcdef', apiKeyHeader: 'X-API-Key' // 可自定义header名称 } } }; ``` #### 2.3.2 HTTP请求示例 ```http GET /api/data HTTP/1.1 Host: api.company.com X-API-Key: sk-1234567890abcdef Content-Type: application/json ``` #### 2.3.3 常见的API Key放置位置 **1. Header中（推荐）** ```http X-API-Key: sk-1234567890abcdef Authorization: Bearer sk-1234567890abcdef ``` **2. Query参数中** ```http GET /api/data?api_key=sk-1234567890abcdef HTTP/1.1 ``` **3. 请求体中** ```json { "api_key": "sk-1234567890abcdef", "data": "..." } ``` ### 2.4 实际应用场景 #### 2.4.1 微服务间认证 ```typescript // 用户服务调用订单服务 const userServiceConfig = { openapi: 'https://order-service.company.com/openapi.json', auth: { type: 'apikey', credentials: { apiKey: process.env.ORDER_SERVICE_API_KEY, apiKeyHeader: 'X-Service-Key' } } }; ``` #### 2.4.2 第三方API集成 ```typescript // 集成OpenAI API const openaiConfig = { openapi: 'https://api.openai.com/v1/openapi.json', auth: { type: 'apikey', credentials: { apiKey: process.env.OPENAI_API_KEY, apiKeyHeader: 'Authorization' // OpenAI使用Bearer格式 } } }; ``` #### 2.4.3 不同API Key格式示例 ```typescript // Stripe API const stripeConfig = { auth: { type: 'apikey', credentials: { apiKey: 'sk_test_...', apiKeyHeader: 'Authorization' // Bearer sk_test_... } } }; // GitHub API const githubConfig = { auth: { type: 'apikey', credentials: { apiKey: 'ghp_...', apiKeyHeader: 'Authorization' // token ghp_... } } }; // SendGrid API const sendgridConfig = { auth: { type: 'apikey', credentials: { apiKey: 'SG.xxx', apiKeyHeader: 'Authorization' // Bearer SG.xxx } } }; ``` ## 3. Basic Auth认证 ### 3.1 什么是Basic Auth Basic Auth是HTTP协议中最简单的认证方式，使用用户名和密码进行认证。用户名和密码通过Base64编码后放在Authorization header中。 ### 3.2 Basic Auth的工作原理 #### 3.2.1 编码过程 ```javascript // 用户名：admin，密码：password123 const credentials = 'admin:password123'; const encoded = Buffer.from(credentials).toString('base64'); // 结果：YWRtaW46cGFzc3dvcmQxMjM= ``` #### 3.2.2 HTTP请求格式 ```http GET /api/data HTTP/1.1 Host: api.company.com Authorization: Basic YWRtaW46cGFzc3dvcmQxMjM= Content-Type: application/json ``` ### 3.3 在mcp-swagger-server中的应用 #### 3.3.1 配置方式 ```typescript const serverConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'basic', credentials: { username: 'admin', password: 'password123' } } }; ``` #### 3.3.2 环境变量配置 ```typescript const serverConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'basic', credentials: { username: process.env.API_USERNAME, password: process.env.API_PASSWORD } } }; ``` ### 3.4 实际应用场景 #### 3.4.1 内部系统认证 ```typescript // 内部监控系统 const monitoringConfig = { openapi: 'https://monitoring.company.com/openapi.json', auth: { type: 'basic', credentials: { username: 'monitoring_user', password: 'secure_password' } } }; ``` #### 3.4.2 数据库REST API ```typescript // 连接数据库REST API const databaseConfig = { openapi: 'https://db-api.company.com/openapi.json', auth: { type: 'basic', credentials: { username: 'db_user', password: 'db_password' } } }; ``` ### 3.5 安全考虑 #### 3.5.1 安全问题 - **明文传输**：Base64编码不是加密，容易被破解 - **重放攻击**：认证信息可以被重复使用 - **密码泄露**：如果传输不安全，密码容易被截获 #### 3.5.2 安全建议 - **使用HTTPS**：确保传输加密 - **强密码策略**：使用复杂密码 - **定期更换**：定期更换密码 - **IP限制**：限制访问IP地址 ## 4. OAuth 2.0认证 ### 4.1 什么是OAuth 2.0 OAuth 2.0是一个开放标准的授权协议，允许用户授权第三方应用访问其在某个服务提供者上的资源，而无需将用户名和密码提供给第三方应用。 ### 4.2 OAuth 2.0的角色 - **Resource Owner（资源所有者）**：用户 - **Client（客户端）**：第三方应用 - **Resource Server（资源服务器）**：API服务器 - **Authorization Server（授权服务器）**：OAuth服务器 ### 4.3 OAuth 2.0的授权流程 #### 4.3.1 授权码流程（Authorization Code Flow） ``` 1. 用户 → 客户端：访问应用 2. 客户端 → 用户：重定向到授权服务器 3. 用户 → 授权服务器：登录并授权 4. 授权服务器 → 客户端：返回授权码 5. 客户端 → 授权服务器：用授权码换取访问令牌 6. 授权服务器 → 客户端：返回访问令牌 7. 客户端 → 资源服务器：使用访问令牌访问API ``` #### 4.3.2 客户端凭证流程（Client Credentials Flow） ``` 1. 客户端 → 授权服务器：发送客户端凭证 2. 授权服务器 → 客户端：返回访问令牌 3. 客户端 → 资源服务器：使用访问令牌访问API ``` ### 4.4 在mcp-swagger-server中的应用 #### 4.4.1 配置方式 ```typescript const serverConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'oauth2', credentials: { clientId: 'your_client_id', clientSecret: 'your_client_secret', tokenUrl: 'https://auth.company.com/oauth/token', scope: 'read write' }, refresh: { enabled: true, refreshInterval: 3600 // 1小时刷新一次 } } }; ``` #### 4.4.2 获取访问令牌的过程 ```typescript // 1. 发送请求到令牌端点 const tokenRequest = { method: 'POST', url: 'https://auth.company.com/oauth/token', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, data: { grant_type: 'client_credentials', client_id: 'your_client_id', client_secret: 'your_client_secret', scope: 'read write' } }; // 2. 响应包含访问令牌 const tokenResponse = { access_token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', token_type: 'Bearer', expires_in: 3600, scope: 'read write' }; ``` ### 4.5 实际应用场景 #### 4.5.1 Google API集成 ```typescript const googleConfig = { openapi: 'https://sheets.googleapis.com/$discovery/rest?version=v4', auth: { type: 'oauth2', credentials: { clientId: process.env.GOOGLE_CLIENT_ID, clientSecret: process.env.GOOGLE_CLIENT_SECRET, tokenUrl: 'https://oauth2.googleapis.com/token', scope: 'https://www.googleapis.com/auth/spreadsheets' } } }; ``` #### 4.5.2 Microsoft Graph API ```typescript const microsoftConfig = { openapi: 'https://graph.microsoft.com/v1.0/$metadata', auth: { type: 'oauth2', credentials: { clientId: process.env.AZURE_CLIENT_ID, clientSecret: process.env.AZURE_CLIENT_SECRET, tokenUrl: 'https://login.microsoftonline.com/tenant/oauth2/v2.0/token', scope: 'https://graph.microsoft.com/.default' } } }; ``` #### 4.5.3 Salesforce API ```typescript const salesforceConfig = { openapi: 'https://your-instance.salesforce.com/services/data/v54.0/sobjects', auth: { type: 'oauth2', credentials: { clientId: process.env.SALESFORCE_CLIENT_ID, clientSecret: process.env.SALESFORCE_CLIENT_SECRET, tokenUrl: 'https://login.salesforce.com/services/oauth2/token', scope: 'full api' } } }; ``` ## 5. 自定义Header认证 ### 5.1 什么是自定义Header 自定义Header是企业根据自己的需求定义的认证方式，通常用于内部系统之间的认证。企业可以定义任意的Header名称和值来进行认证。 ### 5.2 常见的自定义Header #### 5.2.1 企业内部认证 ```http X-Company-Token: abc123def456 X-Service-Key: service_key_123 X-Client-ID: client_12345 X-Request-ID: req_67890 ``` #### 5.2.2 版本控制 ```http X-API-Version: v1 X-Client-Version: 1.2.3 ``` #### 5.2.3 环境标识 ```http X-Environment: production X-Tenant-ID: tenant_123 ``` ### 5.3 在mcp-swagger-server中的应用 #### 5.3.1 单个自定义Header ```typescript const serverConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'custom', credentials: { customHeaders: { 'X-Company-Token': 'abc123def456' } } } }; ``` #### 5.3.2 多个自定义Header ```typescript const serverConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'custom', credentials: { customHeaders: { 'X-Company-Token': process.env.COMPANY_TOKEN, 'X-Service-Key': process.env.SERVICE_KEY, 'X-Client-Version': '1.0.0', 'X-Environment': process.env.NODE_ENV } } } }; ``` ### 5.4 实际应用场景 #### 5.4.1 微服务架构 ```typescript // 用户服务调用订单服务 const orderServiceConfig = { openapi: 'https://order-service.company.com/openapi.json', auth: { type: 'custom', credentials: { customHeaders: { 'X-Service-Token': process.env.ORDER_SERVICE_TOKEN, 'X-Calling-Service': 'user-service', 'X-Correlation-ID': generateCorrelationId() } } } }; ``` #### 5.4.2 多租户系统 ```typescript const tenantConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'custom', credentials: { customHeaders: { 'X-Tenant-ID': 'tenant_123', 'X-Organization': 'company_abc', 'X-User-Role': 'admin' } } } }; ``` #### 5.4.3 负载均衡和路由 ```typescript const routingConfig = { openapi: 'https://api.company.com/openapi.json', auth: { type: 'custom', credentials: { customHeaders: { 'X-Target-Service': 'user-service', 'X-Load-Balancer': 'primary', 'X-Request-Priority': 'high' } } } }; ``` ## 6. 认证方式对比 ### 6.1 适用场景对比 | 认证方式 | 适用场景 | 优点 | 缺点 | |---------|----------|------|------| | JWT | 用户认证、跨域、微服务 | 无状态、包含信息、标准化 | 令牌较大、难以撤销 | | API Key | 系统间认证、第三方集成 | 简单、稳定、易管理 | 静态、权限粗糙 | | Basic Auth | 内部系统、简单认证 | 简单、兼容性好 | 安全性差、明文传输 | | OAuth 2.0 | 第三方授权、企业集成 | 安全、标准、灵活 | 复杂、需要多次交互 | | 自定义Header | 企业内部、特殊需求 | 灵活、可定制 | 非标准、兼容性差 | ### 6.2 安全性对比 | 认证方式 | 安全等级 | 传输安全 | 存储安全 | 撤销能力 | |---------|----------|----------|----------|----------| | JWT | 高 | 需要HTTPS | 客户端存储 | 困难 | | API Key | 中 | 需要HTTPS | 服务器存储 | 容易 | | Basic Auth | 低 | 必须HTTPS | 明文传输 | 容易 | | OAuth 2.0 | 高 | HTTPS | 服务器存储 | 容易 | | 自定义Header | 中 | 需要HTTPS | 取决于实现 | 取决于实现 | ### 6.3 实现复杂度对比 | 认证方式 | 客户端复杂度 | 服务器复杂度 | 维护复杂度 | |---------|-------------|-------------|-------------| | JWT | 中 | 中 | 中 | | API Key | 低 | 低 | 低 | | Basic Auth | 低 | 低 | 低 | | OAuth 2.0 | 高 | 高 | 高 | | 自定义Header | 低 | 中 | 中 | ## 7. 在mcp-swagger-server中的最佳实践 ### 7.1 环境变量配置 ```bash # .env文件 # JWT配置 JWT_SECRET=your_jwt_secret JWT_ISSUER=company.com JWT_AUDIENCE=api.company.com # API Key配置 OPENAI_API_KEY=sk-... GITHUB_API_KEY=ghp_... STRIPE_API_KEY=sk_test_... # Basic Auth配置 DB_USERNAME=admin DB_PASSWORD=secure_password # OAuth 2.0配置 GOOGLE_CLIENT_ID=your_client_id GOOGLE_CLIENT_SECRET=your_client_secret SALESFORCE_CLIENT_ID=your_client_id SALESFORCE_CLIENT_SECRET=your_client_secret # 自定义Header配置 COMPANY_TOKEN=abc123def456 SERVICE_KEY=service_key_123 TENANT_ID=tenant_123 ``` ### 7.2 多环境配置 ```typescript // config/auth.ts export const authConfig = { development: { jwt: { secret: process.env.JWT_SECRET || 'dev_secret', issuer: 'dev.company.com', expiresIn: '1h' }, apiKey: { header: 'X-API-Key', validate: false // 开发环境不验证 } }, production: { jwt: { secret: process.env.JWT_SECRET, issuer: 'api.company.com', expiresIn: '15m' }, apiKey: { header: 'X-API-Key', validate: true, encryption: true } } }; ``` ### 7.3 错误处理 ```typescript // 认证错误处理 const handleAuthError = (error: any, authType: string) => { switch (error.status) { case 401: console.error(`${authType} authentication failed: Invalid credentials`); break; case 403: console.error(`${authType} authorization failed: Insufficient permissions`); break; case 429: console.error(`${authType} rate limit exceeded`); break; default: console.error(`${authType} unexpected error:`, error.message); } }; ``` ### 7.4 监控和日志 ```typescript // 认证日志记录 const logAuthAttempt = (authType: string, success: boolean, details?: any) => { const logEntry = { timestamp: new Date().toISOString(), authType, success, details, userAgent: details?.userAgent, ip: details?.ip }; if (success) { console.log('Auth success:', logEntry); } else { console.warn('Auth failure:', logEntry); } }; ``` ## 8. 总结 ### 8.1 选择认证方式的建议 1. **用户认证**：使用JWT Token，提供丰富的用户信息和权限控制 2. **系统间认证**：使用API Key，简单稳定，易于管理 3. **内部系统**：使用Basic Auth或自定义Header，根据安全要求选择 4. **第三方集成**：使用OAuth 2.0，标准化且安全 5. **企业特殊需求**：使用自定义Header，满足特定业务需求 ### 8.2 安全建议 1. **传输安全**：始终使用HTTPS 2. **存储安全**：敏感信息使用环境变量或密钥管理服务 3. **权限最小化**：只授予必要的权限 4. **定期轮换**：定期更换密钥和令牌 5. **监控审计**：记录所有认证事件 ### 8.3 实施建议 1. **分阶段实施**：从简单的认证方式开始，逐步升级 2. **统一管理**：使用配置文件统一管理认证信息 3. **错误处理**：完善的错误处理和重试机制 4. **文档完善**：详细的认证配置文档 5. **测试充分**：针对不同认证方式进行充分测试 通过理解这些认证方式的原理和应用场景，您可以根据具体需求选择最合适的认证方式，并在mcp-swagger-server中正确配置和使用它们。