当前位置：首页 > news >正文

24_FastMCP 2.x 中文文档之FastMCP服务端认证：构建完整的 OAuth 服务器详解

news 2025/11/12 5:53:53

一、完整的 OAuth 服务器

构建一个独立的身份验证系统，让您的 FastMCP 服务器在其中管理用户、颁发令牌并验证它们。

版本 2.11.0 新增：

警告：这是一个极其高级的模式，大多数用户应该避免使用。构建安全的 OAuth 2.1 服务器需要深厚的认证协议、密码学和安全最佳实践专业知识。复杂性远远超出了初始实现，包括持续的安全监控、威胁响应和合规性维护。

除非您有外部身份提供程序无法满足的强制性要求，例如隔离环境或特殊合规性需求，否则请改用远程 OAuth。

完整 OAuth 服务器模式存在是为了支持 MCP 协议规范的要求。您的 FastMCP 服务器既成为授权服务器又成为资源服务器，处理从用户登录到令牌验证的完整认证生命周期。

本文档为了完整性而存在 - 绝大多数应用程序应该使用外部身份提供程序。

二、OAuthProvider

FastMCP 提供实现 OAuth 2.1 规范的 OAuthProvider 抽象类。要使用此模式，您必须子类化 OAuthProvider 并实现所有必需的抽象方法。

注意：OAuthProvider 处理 OAuth 端点、协议流和安全要求，但将所有存储、用户管理和业务逻辑委托给您对抽象方法的实现。

三、必需实现

您必须实现这些抽象方法来创建功能正常的 OAuth 服务器：

3.1 客户端管理

客户端管理方法

get_client（异步方法）：从您的数据库中按 ID 检索客户端信息。

参数：
- client_id (str)：要查找的客户端标识符
返回：
- OAuthClientInformationFull | None：客户端信息对象，如果未找到客户端则为 None
register_client（异步方法）：在您的数据库中存储新的客户端注册信息。

参数：
- client_info (OAuthClientInformationFull)：要存储的完整客户端注册信息
返回：
- None：无返回值

3.2 授权流程

授权流程方法

authorize（异步方法）：处理授权请求并返回重定向 URL。必须实现用户认证和同意收集。

参数：
- client (OAuthClientInformationFull)：发出授权请求的 OAuth 客户端
- params (AuthorizationParams)：来自客户端的授权请求参数
返回：
- str：发送给客户端的重定向 URL
load_authorization_code（异步方法）：按代码字符串从存储中加载授权代码。如果代码无效或过期，返回 None。

参数：
- client (OAuthClientInformationFull)：尝试使用授权代码的 OAuth 客户端
- authorization_code (str)：要查找的授权代码字符串
返回：
- AuthorizationCode | None：授权代码对象，如果未找到则为 None

3.3 令牌管理

令牌管理方法

exchange_authorization_code（异步方法）：将授权代码交换为访问令牌和刷新令牌。必须验证代码并创建新令牌。

参数：
- client (OAuthClientInformationFull)：交换授权代码的 OAuth 客户端
- authorization_code (AuthorizationCode)：要交换的有效授权代码对象
返回：
- OAuthToken：包含访问令牌和刷新令牌的新 OAuth 令牌
load_refresh_token（异步方法）：按令牌字符串从存储中加载刷新令牌。如果令牌无效或过期，返回 None。

参数：
- client (OAuthClientInformationFull)：尝试使用刷新令牌的 OAuth 客户端
- refresh_token (str)：要查找的刷新令牌字符串
返回：
- RefreshToken | None：刷新令牌对象，如果未找到则为 None
exchange_refresh_token（异步方法）：将刷新令牌交换为新的访问/刷新令牌对。必须验证范围和令牌。

参数：
- client (OAuthClientInformationFull)：使用刷新令牌的 OAuth 客户端
- refresh_token (RefreshToken)：要交换的有效刷新令牌对象
- scopes (list[str])：新访问令牌的请求范围
返回：
- OAuthToken：带有更新的访问令牌和刷新令牌的新 OAuth 令牌
load_access_token（异步方法）：按令牌字符串加载访问令牌。

参数：
- token (str)：要验证的访问令牌
返回：
- AccessToken | None：访问令牌对象，如果令牌无效则为 None
revoke_token（异步方法）：撤销访问或刷新令牌，在存储中将其标记为无效。

参数：
- token (AccessToken | RefreshToken)：要撤销并标记为无效的令牌对象
返回：
- None：无返回值
verify_token（异步方法）：验证传入请求的持有者令牌。如果有效则返回 AccessToken，如果无效则返回 None。

参数：
- token (str)：来自传入请求的持有者令牌字符串
返回：
- AccessToken | None：如果有效则为访问令牌对象，如果无效或过期则为 None