13.3 MCP 身份验证

第 13 章 · MCP 高级应用 · 第4部分：模型上下文协议 MCP

MCP 支持多种身份验证方式，确保安全地连接到 MCP 服务器。

OAuth 2.0#

OAuth 2.0 流程#

MCP 服务器可以使用 OAuth 2.0 进行身份验证：

  1. Claude Code 发起 OAuth 请求
  2. 用户重定向到授权页面
  3. 用户授权应用
  4. 授权服务器返回访问令牌
  5. Claude Code 使用令牌访问 MCP 服务器

配置 OAuth 2.0#

添加 OAuth 服务器

bash
复制
# 添加需要 OAuth 的服务器claude mcp add --transport http github https://api.githubcopilot.com/mcp/

进行身份验证

bash
复制
# 在 Claude Code 中进行身份验证/mcp
# 选择需要身份验证的服务器# 选择 "github"

OAuth 流程

bash
复制
# 1. Claude Code 显示授权 URL# 请访问以下 URL 进行授权：# https://github.com/login/oauth/authorize?client_id=...
# 2. 用户访问 URL 并授权# 3. 授权服务器返回访问令牌# 4. Claude Code 保存令牌

OAuth 2.0 作用域#

定义作用域

OAuth 2.0 使用作用域限制权限：

bash
复制
# 添加带作用域的服务器claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \--scope "repo,user"

常见作用域

  • repo: 仓库访问权限
  • user: 用户信息访问权限
  • admin: 管理员权限
  • read: 只读权限
  • write: 读写权限

令牌管理#

查看令牌

bash
复制
# 查看已保存的令牌显示 OAuth 令牌

刷新令牌

bash
复制
# 刷新访问令牌刷新 GitHub 令牌

撤销令牌

bash
复制
# 撤销访问令牌撤销 GitHub 令牌

API 密钥#

使用 API 密钥#

添加带 API 密钥的服务器

bash
复制
# Bearer 令牌claude mcp add --transport http api https://api.example.com/mcp \--header "Authorization: Bearer your-api-key"
# API 密钥claude mcp add --transport http api https://api.example.com/mcp \--header "X-API-Key: your-api-key"
# 自定义标头claude mcp add --transport http api https://api.example.com/mcp \--header "X-Custom-Auth: your-custom-key"

环境变量

使用环境变量传递 API 密钥：

bash
复制
# 设置环境变量exportAPI_KEY="your-api-key"
# 使用环境变量claude mcp add --transport http api https://api.example.com/mcp \  --header "Authorization: Bearer ${API_KEY}"

密钥安全#

加密存储

Claude Code 加密存储 API 密钥：

bash
复制
# 密钥自动加密存储claude mcp add --transport http api https://api.example.com/mcp \--header "Authorization: Bearer your-api-key"

密钥轮换

定期轮换 API 密钥：

bash
复制
# 1. 生成新密钥# 2. 更新服务器配置claude mcp remove api
claude mcp add --transport http api https://api.example.com/mcp \  --header "Authorization: Bearer new-api-key"
# 3. 撤销旧密钥

证书身份验证#

使用证书#

添加带证书的服务器

bash
复制
# 使用客户端证书claude mcp add --transport http secure-api https://api.example.com/mcp \--cert /path/to/cert.pem \--key /path/to/key.pem

# 使用 CA 证书claude mcp add --transport http secure-api https://api.example.com/mcp \--cacert /path/to/ca.pem

证书格式

支持的证书格式：

  • PEM: 最常用的格式
  • DER: 二进制格式
  • PKCS12: 包含私钥和证书

证书管理#

查看证书

bash
复制
# 查看证书信息openssl x509 -in /path/to/cert.pem -text -noout

验证证书

bash
复制
# 验证证书openssl verify -CAfile /path/to/ca.pem /path/to/cert.pem

更新证书

bash
复制
# 1. 获取新证书# 2. 更新服务器配置claude mcp remove secure-api
claude mcp add --transport http secure-api https://api.example.com/mcp \  --cert /path/to/new-cert.pem \  --key /path/to/new-key.pem

自定义身份验证#

自定义认证头#

bash
复制
# 使用自定义认证头claude mcp add --transport http custom-api https://api.example.com/mcp \--header "X-Custom-Auth: custom-value"

多因素认证#

bash
复制
# 使用多因素认证claude mcp add --transport http secure-api https://api.example.com/mcp \  --header "X-Auth-Token: token"\  --header "X-Auth-Code: code"

签名请求#

bash
复制
# 使用签名请求claude mcp add --transport http signed-api https://api.example.com/mcp \--header "X-Signature: signature"\--header "X-Timestamp: timestamp"

身份验证最佳实践#

1. 使用最小权限原则#

bash
复制
# 只请求必要的权限claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \  --scope "repo:read"

2. 定期轮换凭证#

bash
复制
# 每 90 天轮换一次 API 密钥
# 设置提醒

3. 使用环境变量#

bash
复制
# 使用环境变量存储敏感信息exportAPI_KEY="your-api-key"claude mcp add --transport http api https://api.example.com/mcp \  --header "Authorization: Bearer ${API_KEY}"

4. 加密存储#

bash
复制
# 使用加密存储
# Claude Code 自动加密存储敏感信息

5. 审计访问#

bash
复制
# 定期审计访问日志显示身份验证日志

故障排除#

OAuth 2.0 问题#

授权失败

问题: OAuth 授权失败

解决方案:

bash
复制
# 1. 检查授权 URL/mcp

# 2. 确认用户授权# 确保用户完成了授权流程
# 3. 检查作用域# 确认请求的作用域正确
# 4. 重新授权撤销 GitHub 令牌
/mcp
# 重新进行授权

令牌过期

问题: 访问令牌过期

解决方案:

bash
复制
# 1. 刷新令牌刷新 GitHub 令牌

# 2. 如果刷新失败，重新授权撤销 GitHub 令牌
/mcp
# 重新进行授权

API 密钥问题#

密钥无效

问题: API 密钥无效

解决方案:

bash
复制
# 1. 验证密钥# 检查密钥是否正确
# 2. 检查密钥权限# 确认密钥有足够的权限
# 3. 更新密钥claude mcp remove api
claude mcp add --transport http api https://api.example.com/mcp \--header "Authorization: Bearer new-api-key"

密钥过期

问题: API 密钥过期

解决方案:

bash
复制
# 1. 生成新密钥# 2. 更新服务器配置claude mcp remove api
claude mcp add --transport http api https://api.example.com/mcp \  --header "Authorization: Bearer new-api-key"

证书问题#

证书无效

问题: 证书无效

解决方案:

bash
复制
# 1. 验证证书openssl verify -CAfile /path/to/ca.pem /path/to/cert.pem

# 2. 检查证书有效期openssl x509 -in /path/to/cert.pem -text -noout |grep"Not After"
# 3. 更新证书claude mcp remove secure-api
claude mcp add --transport http secure-api https://api.example.com/mcp \--cert /path/to/new-cert.pem \--key /path/to/new-key.pem

证书过期

问题: 证书过期

解决方案:

bash
复制
# 1. 获取新证书# 2. 更新服务器配置claude mcp remove secure-api
claude mcp add --transport http secure-api https://api.example.com/mcp \  --cert /path/to/new-cert.pem \  --key /path/to/new-key.pem

安全建议#

1. 保护凭证#

bash
复制
# 不要在代码中硬编码凭证
# 使用环境变量
export API_KEY="your-api-key"

# 不要在版本控制中提交凭证
# 添加到 .gitignore
echo ".env" >> .gitignore

2. 使用强凭证#

bash
复制
# 使用强密码# 使用长随机字符串作为 API 密钥# 定期轮换凭证

3. 限制权限#

bash
复制
# 使用最小权限原则
# 只授予必要的权限
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--scope "repo:read"

4. 监控使用#

bash
复制
# 定期监控 API 使用显示 API 使用统计

# 检查异常活动显示异常访问日志

5. 及时撤销#

bash
复制
# 及时撤销不需要的凭证撤销 GitHub 令牌
撤销 API 密钥