Claude Code 教程

简体中文

繁體中文
English

简体中文

繁體中文
English

主题

13.3 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
    bash

    # 设置环境变量
    export API_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

    # 使用环境变量存储敏感信息
    export API_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 密钥

基于 MIT 许可发布

Copyright © 2024-present