18 KiB

Raw Blame History

企业级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（头部）

{
  "alg": "HS256",
  "typ": "JWT"
}

alg: 签名算法（如HS256、RS256等）
typ: 令牌类型，固定为JWT

Payload（载荷）

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "exp": 1516242622,
  "roles": ["admin", "user"],
  "permissions": ["read", "write"]
}

sub: 用户ID
name: 用户名
iat: 令牌签发时间
exp: 令牌过期时间
roles: 用户角色
permissions: 用户权限

Signature（签名）

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

1.3 在mcp-swagger-server中的应用

1.3.1 配置方式

const serverConfig = {
  openapi: 'https://api.company.com/openapi.json',
  auth: {
    type: 'bearer',
    credentials: {
      token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    }
  }
};

1.3.2 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 配置方式

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请求示例

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中（推荐）

X-API-Key: sk-1234567890abcdef
Authorization: Bearer sk-1234567890abcdef

2. Query参数中

GET /api/data?api_key=sk-1234567890abcdef HTTP/1.1

3. 请求体中

{
  "api_key": "sk-1234567890abcdef",
  "data": "..."
}

2.4 实际应用场景

2.4.1 微服务间认证

// 用户服务调用订单服务
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集成

// 集成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格式示例

// 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 编码过程

// 用户名：admin，密码：password123
const credentials = 'admin:password123';
const encoded = Buffer.from(credentials).toString('base64');
// 结果：YWRtaW46cGFzc3dvcmQxMjM=

3.2.2 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 配置方式

const serverConfig = {
  openapi: 'https://api.company.com/openapi.json',
  auth: {
    type: 'basic',
    credentials: {
      username: 'admin',
      password: 'password123'
    }
  }
};

3.3.2 环境变量配置

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 内部系统认证

// 内部监控系统
const monitoringConfig = {
  openapi: 'https://monitoring.company.com/openapi.json',
  auth: {
    type: 'basic',
    credentials: {
      username: 'monitoring_user',
      password: 'secure_password'
    }
  }
};

3.4.2 数据库REST API

// 连接数据库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 配置方式

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 获取访问令牌的过程

// 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集成

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

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

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 企业内部认证

X-Company-Token: abc123def456
X-Service-Key: service_key_123
X-Client-ID: client_12345
X-Request-ID: req_67890

5.2.2 版本控制

X-API-Version: v1
X-Client-Version: 1.2.3

5.2.3 环境标识

X-Environment: production
X-Tenant-ID: tenant_123

5.3 在mcp-swagger-server中的应用

5.3.1 单个自定义Header

const serverConfig = {
  openapi: 'https://api.company.com/openapi.json',
  auth: {
    type: 'custom',
    credentials: {
      customHeaders: {
        'X-Company-Token': 'abc123def456'
      }
    }
  }
};

5.3.2 多个自定义Header

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 微服务架构

// 用户服务调用订单服务
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 多租户系统

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 负载均衡和路由

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 环境变量配置

# .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 多环境配置

// 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 错误处理

// 认证错误处理
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 监控和日志

// 认证日志记录
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 选择认证方式的建议

用户认证：使用JWT Token，提供丰富的用户信息和权限控制
系统间认证：使用API Key，简单稳定，易于管理
内部系统：使用Basic Auth或自定义Header，根据安全要求选择
第三方集成：使用OAuth 2.0，标准化且安全
企业特殊需求：使用自定义Header，满足特定业务需求

8.2 安全建议

传输安全：始终使用HTTPS
存储安全：敏感信息使用环境变量或密钥管理服务
权限最小化：只授予必要的权限
定期轮换：定期更换密钥和令牌
监控审计：记录所有认证事件

8.3 实施建议

分阶段实施：从简单的认证方式开始，逐步升级
统一管理：使用配置文件统一管理认证信息
错误处理：完善的错误处理和重试机制
文档完善：详细的认证配置文档
测试充分：针对不同认证方式进行充分测试

通过理解这些认证方式的原理和应用场景，您可以根据具体需求选择最合适的认证方式，并在mcp-swagger-server中正确配置和使用它们。

18 KiB Raw Blame History Unescape Escape