快速手搓一个MCP服务指南（五）：FastMCP 中 Bearer Token 认证的实现与最佳实践

在构建现代 API 服务时，安全认证是不可忽视的关键环节。FastMCP 作为一个强大的工具调用框架，提供了对 Bearer Token 认证的支持，使开发者能够轻松保护 HTTP 端点的安全。本文将深入解析 FastMCP 中 Bearer Token 认证的实现原理、配置方法及最佳实践，帮助你在实际项目中构建安全可靠的认证体系。

认证机制概述

Bearer Token 认证是一种基于令牌的身份验证方式，客户端通过在请求头中携带 Authorization: Bearer <token> 格式的令牌来证明身份。FastMCP 从 2.6.0 版本开始引入这一特性，为 HTTP 传输（http 和 sse）提供了实用的安全保护方案。

需要注意的是，FastMCP 的 Bearer Token 认证实现并未完全遵循 MCP 规范中的 OAuth 2.1 流程，而是针对服务间通信和编程环境设计的简化方案。这种设计避免了复杂的 OAuth 流程，同时通过非对称加密确保了认证的安全性。

非对称加密策略

FastMCP 采用非对称加密实现令牌验证，这种设计带来了显著的安全优势：

• 无共享密钥：服务器无需访问私钥或客户端密钥，仅需公钥即可验证令牌
• 公钥验证机制：支持通过静态公钥或 JWKS 端点获取公钥进行签名验证
• 安全的令牌发行：令牌由外部服务使用私钥签名，私钥不暴露给 FastMCP 服务器
• 可扩展架构：多台服务器可独立验证令牌，无需协调密钥

这种设计使得 FastMCP 能够无缝集成到现有认证基础设施中，同时保持严格的安全边界。

核心配置指南

基本配置流程

在 FastMCP 中启用 Bearer Token 认证非常简单，通过 BearerAuthProvider 类即可完成配置。以下是基本的配置示例：

from fastmcp import FastMCP
from fastmcp.server.auth import BearerAuthProvider

# 配置认证提供器
auth = BearerAuthProvider(
    jwks_uri="https://my-identity-provider.com/.well-known/jwks.json",
    issuer="https://my-identity-provider.com/",
    audience="my-mcp-server"
)

# 将认证提供器应用到 FastMCP 实例
mcp = FastMCP(name="My MCP Server", auth=auth)

配置参数详解

BearerAuthProvider 支持多种配置参数，满足不同场景的认证需求：

公钥与 JWKS 配置

静态公钥配置

当拥有 PEM 格式的公钥时，可以直接提供给认证提供器：

from fastmcp.server.auth import BearerAuthProvider
import inspect

# PEM 格式公钥
public_key_pem = inspect.cleandoc("""
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy...
    -----END PUBLIC KEY-----
""")

# 使用公钥配置认证提供器
auth = BearerAuthProvider(public_key=public_key_pem)

JWKS URI 配置

推荐在生产环境中使用 JWKS URI，以支持密钥自动轮换：

from fastmcp.server.auth import BearerAuthProvider

# 配置 JWKS 端点
provider = BearerAuthProvider(
    jwks_uri="https://idp.example.com/.well-known/jwks.json"
)

令牌生成与管理

开发测试令牌生成

为了便于开发和测试，FastMCP 提供了 RSAKeyPair 工具类用于生成测试令牌：

from fastmcp.server.auth.providers.bearer import RSAKeyPair

# 生成新的密钥对
key_pair = RSAKeyPair.generate()

# 配置认证提供器使用公钥
auth = BearerAuthProvider(
    public_key=key_pair.public_key,
    issuer="https://dev.example.com",
    audience="my-dev-server"
)

# 生成测试令牌
token = key_pair.create_token(
    subject="dev-user",
    issuer="https://dev.example.com",
    audience="my-dev-server",
    scopes=["read", "write"],
    expires_in_seconds=3600  # 令牌有效期1小时
)

print(f"Test token: {token}")

生产环境令牌管理

需要特别注意：RSAKeyPair 仅适用于开发测试环境。在生产环境中，应使用正规的 OAuth 2.1 授权服务器或身份提供商（IdP）来生成令牌，确保安全性和合规性。

访问用户信息与权限控制

获取令牌声明

在认证通过后，工具函数可以通过 get_access_token() 依赖函数获取令牌信息：

from fastmcp import FastMCP, ToolError
from fastmcp.server.dependencies import get_access_token

@mcp.tool async def protected_resource(ctx: Context) -> dict:
    # 获取访问令牌
    access_token = get_access_token()
    
    # 从令牌中获取用户ID（来自JWT的sub或client_id声明）
    user_id = access_token.client_id
    
    # 获取用户权限范围
    user_scopes = access_token.scopes
    
    # 权限检查
    if "data:read_sensitive" not in user_scopes:
        raise ToolError("权限不足，需要 'data:read_sensitive' 权限")
    
    return {
        "user": user_id,
        "message": "访问受保护资源成功",
        "granted_scopes": user_scopes
    }

AccessToken 数据结构

AccessToken 对象包含以下属性，帮助你获取令牌的关键信息：

最佳实践与安全建议

生产环境配置建议

1. 使用 JWKS 而非静态公钥：JWKS 支持自动密钥轮换，避免因密钥更新导致的服务中断
2. 严格配置 issuer 和 audience：确保只接受预期的令牌发行者和目标受众
3. 最小权限原则：通过 required_scopes 配置每个工具所需的最小权限
4. 短令牌有效期：设置合理的令牌过期时间，建议不超过 1 小时

开发测试注意事项

1. 绝不将测试密钥用于生产：RSAKeyPair 生成的密钥仅用于开发测试
2. 模拟真实权限场景：在测试时应生成包含不同权限范围的令牌，全面测试权限控制逻辑
3. 定期更新测试密钥：避免长期使用同一测试密钥，降低安全风险

权限控制策略

1. 多层级权限检查：在工具函数中进行细粒度的权限检查，而不仅仅依赖全局配置
2. 动态权限验证：根据不同的操作和资源，验证相应的权限范围
3. 错误处理优化：提供清晰的权限错误信息，帮助客户端调试

集成案例：构建安全的 API 服务

下面通过一个完整示例，展示如何在 FastMCP 中实现基于 Bearer Token 的安全认证：

from fastmcp import FastMCP, ToolError
from fastmcp.server.auth import BearerAuthProvider
from fastmcp.server.dependencies import get_access_token
from fastmcp.server.auth.providers.bearer import RSAKeyPair
import inspect

# 生成测试用密钥对（生产环境应使用正式的OAuth服务器）
key_pair = RSAKeyPair.generate()

# 配置认证提供器
auth = BearerAuthProvider(
    public_key=key_pair.public_key,
    issuer="https://auth.example.com",
    audience="data-service",
    required_scopes=["data:read"]  # 所有请求必需的全局权限
)

# 初始化FastMCP服务器
mcp = FastMCP(
    name="Secure Data Service",
    auth=auth
)

# 受保护的工具函数：需要特定权限才能访问
@mcp.tool async def get_user_data(user_id: str) -> dict:
    """获取用户数据，需要 data:read 和 data:read:user 权限"""
    access_token = get_access_token()
    
    # 检查是否有必要的权限
    if "data:read" not in access_token.scopes:
        raise ToolError("缺少 data:read 基本权限")
    if f"data:read:user:{user_id}" not in access_token.scopes:
        raise ToolError(f"缺少访问用户 {user_id} 的权限")
    
    # 模拟获取用户数据
    return {
        "user_id": user_id,
        "name": "John Doe",
        "email": "john@example.com",
        "message": "数据访问成功"
    }

# 生成测试令牌（包含必要的权限范围）
test_token = key_pair.create_token(
    subject="user-123",
    issuer="https://auth.example.com",
    audience="data-service",
    scopes=["data:read", "data:read:user:123"],
    expires_in_seconds=3600
)

# 打印测试令牌供客户端使用
print(f"测试令牌: {test_token}")
print("使用方式: Authorization: Bearer <token>")

总结

FastMCP 提供的 Bearer Token 认证机制为 HTTP 端点提供了实用的安全保护方案，通过非对称加密和灵活的配置选项，使开发者能够轻松构建安全的 API 服务。尽管它不完全符合 MCP 规范中的 OAuth 2.1 流程，但在服务间通信和编程环境中表现出色。

在实际应用中，开发者应根据环境选择合适的配置方式：开发测试时使用 RSAKeyPair 工具类，生产环境则集成正规的身份提供商或 OAuth 服务器。同时，遵循最小权限原则和最佳安全实践，确保系统的安全性和可靠性。

通过本文介绍的配置方法和示例，你可以在 FastMCP 中快速实现 Bearer Token 认证，为你的工具服务添加坚实的安全屏障。