目录

Better Auth 可以签发 OAuth 令牌,让 Claude 等 AI 智能体以当前登录用户的身份操作应用。登录仍交由 Microsoft Entra ID 处理,资源限制、作用域和撤销则由应用端执行。

要点#

  • 将 Entra ID 令牌保留在服务器内部,为 MCP 端点签发单独的令牌。
  • 强制要求 PKCE,以及与 MCP URL 完全匹配的显式 resource。
  • 在签发令牌时和每次 MCP 请求中验证授权同意,并在客户端断开连接后阻断访问。
  • 此处介绍的附加检查依赖内部实现细节,因此需固定 Better Auth 版本。

分离登录与授权#

设置两个独立的信任边界。Entra ID 通过 SSO 验证用户身份,Better Auth 则授权 AI 客户端访问应用。MCP 服务器只接受应用签发的令牌,不接受 Entra ID 令牌。

为 OAuth 资源设置一个精确的 URL,例如 https://example.com/mcp。它用于标识令牌的预期接收方。AI 客户端的注册和授权同意由应用管理,让用户无需更改 Entra ID 的应用注册即可断开客户端连接。

这里的实现面向 Better Auth 1.7.12 和 MCP 2026-07-28 元数据配置规范。请将以下行为视为特定版本的行为,并在采用配置前使用已安装的软件包进行确认。

配置 OAuth 流程#

在现有的 socialProviders.microsoft 配置之外,添加 mcp() 和 cimd()。设置 loginPage、consentPage、resource,允许 authorization_code 和 refresh_token,并公开 items:read、items:write、offline_access。设置 disableJwtPlugin: true,使访问令牌采用不透明令牌,并保留 storeTokens: "hashed"。在 Hono 中,将 /api/auth/* 和 /.well-known/* 路由到 Better Auth 处理器。

连接按以下顺序进行。

1. MCP 端点返回 401,并附带包含 resource_metadata URL 的 WWW-Authenticate 响应头。 2. 客户端发现授权服务器,通过客户端 ID 元数据文档(CIMD)标识自身,或使用动态客户端注册(DCR)通过 /oauth2/register 注册。 3. 客户端指定 PKCE 质询和精确的 MCP resource 来请求授权。应用在 Entra ID 登录期间保留已签名的 OAuth 查询参数,随后显示授权同意页面。 4. 批准后,客户端将授权码交换为访问令牌和刷新令牌。

跳转至登录时,将包含 sig 的完整已签名查询参数作为 oauth_query 传递。授权同意页面应显示客户端名称、请求的作用域及重定向目标主机。注册名称由客户端自行声明,不能作为身份证明。

在签发令牌前添加检查#

这里的实现在 Better Auth 默认行为的基础上增加了四项限制。

  • 授权时强制要求资源。 除非 resource 与 MCP URL 完全匹配,否则对 /oauth2/authorize 返回 invalid_target。否则,即使请求未指定资源,也可能在之后获取特定资源的令牌。
  • 仅注册公共客户端。 对于无需身份验证的 DCR,强制要求 token_endpoint_auth_method: "none"。RFC 7591 规定,省略时的默认值为 client_secret_basic。
  • 对两条路径都应用重定向规则。 允许 HTTPS 重定向和 HTTP 回环重定向。DCR 元数据在注册时验证,CIMD 重定向则通过 validateRedirectUri 验证。CIMD 不经过注册端点。
  • 在交换令牌前重新确认授权同意。 如果原有授权同意已不存在,则对授权码和刷新令牌返回 invalid_grant。

除 CIMD 重定向验证外,这些检查均放在 hooks.before 中。请检查与插件读取位置相同的参数来源。注册时使用请求体;授权时,首次 POST 使用请求体,GET 和登录后继续流程使用查询参数。如果不加区分地检查两者,可能会利用插件忽略的参数绕过验证。

使用 CIMD 时,服务器还会访问由客户端控制的 URL。必须要求目标为公开 HTTPS 地址,并拒绝回环地址和特殊用途地址。请使用能够安全处理 DNS 解析和重定向的 fetch 实现。仅检查初始 URL 并不足够。

实施访问控制与断开连接#

在 /mcp 中,仅通过 Bearer 令牌进行身份验证。对令牌进行哈希处理,并在数据库中检查有效期、撤销状态、资源是否完全匹配,以及授权同意是否仍然有效。在这条仅支持 Bearer 的路径中,拒绝绑定到 DPoP 的令牌。将验证后的用户、客户端、作用域和有效期传递给 MCP 处理器。

使用不透明令牌,以便通过数据库检查立即阻断访问。写入工具必须要求 items:write,并调用与 Web 界面相同的服务层,确保所有权检查和输入验证保持一致。工具注解用于描述行为,并不强制执行权限控制。初始工具集应排除不可撤销的操作。

将断开连接实现为一个事务,同时删除授权同意、访问令牌和刷新令牌。保留共享的客户端记录。禁用应用不需要的插件端点,例如其他删除授权同意的路径和 /get-access-token。仅执行删除无法阻止并发刷新写入另一个令牌,因此仍需在请求时检查授权同意。

了解仍然存在的限制#

基于时间戳的授权同意检查无法区分同一秒内的操作。撤销、并发刷新和重新同意可能导致旧授权被视为有效。使用授权同意的代际标识符可以更可靠地区分。此外,这里的配置保留了 30 秒的刷新重试宽限期,允许重复使用上一个刷新令牌。

即使禁用 Entra ID 账户,应用签发的令牌也不会自动失效。请在应用端添加撤销处理。测试实际客户端的 Origin 请求头是否符合策略;由于钩子依赖内部数据结构,请固定 Better Auth 版本,并测试授权、刷新和断开连接流程。

下一步#

添加集成测试,确认断开客户端连接后,现有的访问令牌和刷新令牌均被拒绝。

来源: https://zenn.dev/sakagi/articles/8caa896e649005

目录