首页 / 文章

使用OAuth 2.0及按工具划分的作用域来保护Spring AI MCP服务器的安全。

构建一个OAuth授权服务器,将Spring AI MCP服务器转换为资源服务器,在MCP Inspector中进行测试,然后通过作用域限制单个工具的访问。

发布者:REACTAPP.TOP阅读约 8 分钟1762 词

来源: Spring AI Recipe: Securing an MCP Server with OAuth

API密钥是保护MCP服务器的简便方法,但同时也是一种较为粗放的手段。当需要更强的保护措施时,OAuth 2.0便是自然而然的下一步选择,Spring AI可以利用它来保护服务器,并为各个工具实现细粒度的授权控制。OAuth已为各类应用和API提供安全保障超过十年,而一些针对MCP的扩展功能则使其也能用于保护MCP服务器。其实现需要两个组件:一个用于颁发令牌的授权服务器,以及一个用于接收这些令牌的MCP服务器。

构建授权服务器

授权服务器是用户登录并允许客户端以他们的名义访问资源服务器的地方。在MCP体系中,MCP服务器即为资源服务器,而客户端则是指任何调用它的代理或具备AI功能的应用程序。

首先通过 Initializr 在 start.spring.io 或 IDE 中创建一个新的 Spring Boot 项目,并选择三个依赖项:Spring Web、Spring Security 和 OAuth2 Authorization Server。项目创建完成后还需再添加一个依赖项到构建配置中。

implementation 'org.springaicommunity:mcp-authorization-server:0.1.14'

Spring AI Community 库为授权服务器带来了针对 MCP 的特定功能,尤其是动态客户端注册(DCR)和资源指示器。

接下来是一个用于定义安全过滤链的配置类。

@Configuration
@EnableWebSecurity
public class SecurityConfig {

  @Bean
  SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth ->
            auth.anyRequest().authenticated())
        .formLogin(withDefaults())
        .with(
            McpAuthorizationServerConfigurer.mcpAuthorizationServer(),
            withDefaults())
        .build();
  }

}

这个类负责四项功能:启用网页安全机制,要求对授权服务器的请求进行身份验证,开启Spring Security的表单登录功能及其默认登录页面,同时激活针对MCP的授权服务器功能。

其余的工作则涉及配置属性,使用src/main/resources/application.yaml中的YAML格式比使用属性文件更为合适。

spring:
  application:
    name: recipes-authorization-server
  security:
    oauth2:
      authorizationserver:
        client:
          default-client:
            token:
              access-token-time-to-live: 1h
            registration:
              client-id: "myclient"
              client-secret: "{noop}mysecret"
              client-authentication-methods:
                - "client_secret_basic"
              authorization-grant-types:
                - "authorization_code"
              redirect-uris:
                - "http://localhost:6274/oauth/callback"
                - "http://127.0.0.1:6274/oauth/callback"
              scopes:
                - general-access
                - meteorology
                - administration
    user:
      name: craig
      password: letmein

server:
  port: 9999

该文件中大部分内容用于定义一个OAuth客户端。在实际生产系统中,客户端信息通常会存储在数据库等地方,但演示用途只需在配置中定义客户端即可。此演示客户端使用的标识为myclient,密钥为mysecret。该密钥前带有{noop}前缀,用以告知Spring Security该密钥以明文形式存储。这种方式在演示中很方便,但在实际应用中是不可取的。

该客户端通过HTTP Basic协议向授权服务器进行身份验证,并使用授权码授权方式获取访问令牌。MCP Inspector将作为测试工具,它可以在localhost或127.0.0.1上运行,监听6274端口,并在/oauth/callback路径处处理回调请求,因此需要为这两个主机名分别设置重定向URI。

客户端在请求令牌时可以选择三种权限范围之一:普通访问、气象数据访问以及管理功能访问。配置中还定义了一个演示用户。与客户端类似,实际部署时会从合适的用户存储中加载用户。该服务在端口9999上监听请求。

至此,这部分的设置已完成。可以立即启动,也可以等到MCP服务器准备就绪后再启动。

将MCP服务器转换为资源服务器

对于MCP服务器,应从早期API密钥版本的代码开始。构建该服务器需要三个依赖项。

implementation 'org.springaicommunity:mcp-server-security:0.1.14'
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'

前两个在设置 API 密钥时就应该已经存在了。第三个则是为了添加 Spring Security 对 OAuth 2.0 资源服务器的支持。

资源服务器还必须知道其授权服务器的位置。由于该授权服务器运行在本地主机的 9999 端口上,只需在 application.properties 中设置一个属性即可实现。

spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:9999

自动配置可以完成大部分工作,但MCP服务器的安全设置需要明确指定,以便让MCP安全支持功能知道去何处查找授权服务器。

@Configuration
@EnableWebSecurity
class McpSecurityConfig {

  @Value("${spring.security.oauth2.resourceserver.jwt.issuer-uri}")
  private String issuerUrl;

  @Bean
  SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth ->
            auth.anyRequest().authenticated())
        .with(
            McpServerOAuth2Configurer.mcpServerOAuth2(),
            (mcpAuthorization) -> {
              mcpAuthorization.authorizationServer(issuerUrl);
            }
        )
        .build();
  }

}

授权服务器的位置来自刚才定义的属性,而过滤链要求对每个请求进行身份验证。这就是将MCP服务器变为受OAuth保护的资源服务器所需的一切。

在MCP Inspector中尝试

先运行授权服务器和MCP服务器,然后按照MCP文档中的说明启动MCP Inspector。在Inspector中的操作步骤如下:

  1. 点击左上角的“添加服务器”,使用URL http://localhost:3000创建一个服务器,然后点击“添加”。此时会出现一个服务器面板。
  2. 在连接之前,需提供客户端凭证。打开面板右下角的“设置”链接,滚动到底部的“OAuth设置”部分,展开它,将“Client ID”填为“myclient”,将“Client Secret”填为“mysecret”。
  • 暂时不要改动其他任何内容,包括 Scopes,然后关闭设置面板。
  • 点击服务器面板右上角的滑块按钮进行连接。如果一切正常,浏览器会跳转至授权服务器的登录页面,使用 YAML 文件中定义的演示用户进行登录。
  • 登录成功后,浏览器会以连接成功的状态返回到 MCP Inspector,用于配置的请求会显示在右侧面板中。
  • 打开“工具”选项卡,列表中应包含 get-weather-for-zipcode。选中它,在邮政编码字段中输入任意邮政编码,然后点击“执行工具”。MCP 服务器会以 JSON 格式返回结果。
  • 现在 MCP 服务器要求进行 OAuth 认证。但目前的情况是:只有获得授权的客户端才能使用服务器提供的所有功能。

    保护单个工具

    目前采用的安全措施覆盖了整个服务器。各类工具、资源、提示信息及其他功能都处于经过身份验证的连接之后,但一旦客户端通过了那道入口,所有内容都可供使用。如果不同的工具、提示信息或资源具有不同的授权要求,Spring Security的方法级安全机制能够实现更精细的规则控制。

    首要的改动是对MCP服务器的安全配置进行调整。

    @Configuration
    @EnableWebSecurity
    @EnableMethodSecurity
    class SecurityConfig {
    
      @Value("${spring.security.oauth2.resourceserver.jwt.issuer-uri}")
      private String issuerUrl;
    
      @Bean
      SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> {
              auth.requestMatchers("/mcp").permitAll();
              auth.anyRequest().authenticated();
            })
            .with(
                McpServerOAuth2Configurer.mcpServerOAuth2(),
                (mcpAuthorization) -> {
                  mcpAuthorization.authorizationServer(issuerUrl);
                }
            )
            .build();
      }
    
    }
    

    有两点有所不同。该类现在添加了@EnableMethodSecurity注解,这使得可以直接在工具方法上设置授权规则。此外,authorizeHttpRequests()不再要求每次请求都进行身份验证,因此前往/mcp端点的请求可以无条件通过,而在其他地方仍需进行身份验证。这样一来,每次工具调用的授权都在方法层面得到执行。

    假设调用get-weather-for-zipcode方法时需要气象领域的OAuth权限范围,@PreAuthorize注解即可用来表达这一要求。

    @PreAuthorize("hasAuthority('SCOPE_meteorology')")
    @McpTool(
        name = "get-weather-for-zipcode",
        description = "Gets the weather for a given zipcode",
        annotations = @McpTool.McpAnnotations(
            openWorldHint = false,
            destructiveHint = false,
            idempotentHint = true))
    Weather getWeatherForZipcode(
        @McpToolParam(description = "The zipcode to get weather for")
        String zipcode) {
      var context = SecurityContextHolder.getContext();
      var username = context.getAuthentication().getName();
      return new Weather(
          zipcode,
          "Raining cats and dogs",
          78.0f,
          username);
    }
    

    该注解要求当前的授权必须包含气象相关权限范围。Spring Security将OAuth权限范围视为以SCOPE_为前缀的已授予权限,这也解释了为何要检查SCOPE_meteorology这一条件。

    工具定义还通过annotations属性获得了一些可选的提示属性,这些属性能为客户端提供有用信息:

    • 该工具并非开放型工具,而是完全自包含的,不会调用任何外部API。如果重新编写该工具以使用天气API,那么提示值应为true,或者直接省略,因为其默认值即为true。
    • 该工具不会修改或删除任何内容,因为它仅用于获取天气数据,因此不具有破坏性。
    • 由于没有破坏性,该工具具备幂等性。对于具有破坏性的工具,则需要考虑其幂等性问题,并相应设置idempotentHint属性。

    查看范围检查的运行情况

    重新启动MCP服务器,切换回MCP Inspector,然后在重新连接之前打开OAuth设置。底部的“清除存储的OAuth状态”按钮会删除上一次授权后剩余的令牌,因此请使用它。

    重新连接后登录,再次进入get-weather-for-zipcode并调用该功能。这次调用很可能会失败,因为从未请求授权服务器授予气象学相关权限,所以仅靠身份验证已不足以使用此工具。

    现在在OAuth设置的“范围”字段中添加“气象学”,如有必要则清除存储的状态,重新连接后再运行一次该工具。这次应该能够成功,因为新生成的访问令牌包含了@PreAuthorize所要求的气象学权限范围。

    只需对 Spring Security 现有的 OAuth 支持进行少量扩展,就能将原本依赖 API 密钥保护的 MCP 服务器升级为需要 OAuth 认证的服务器,进而实现针对各个工具的基于权限范围的授权。

    相关阅读

  • 实践笔记:我构建了一个通过了453次测试的Kubernetes MCP服务器,然后…… —— 对《实践笔记:我构建了一个通过了453次测试的Kubernetes MCP服务器,然后……》的详细操作指南:为采用该模式的团队提供契约、检查项以及可直接插入的代码模板。
  • 审核了300个MCP相关npm包,结果竟毫无问题? —— 对300个MCP npm包的压缩包审核显示,有217个包的运行时代码从未被扫描工具读取,同时也解释了为何仅靠静态分析的结果不足以证明代码覆盖率。
  • 在 macOS 上将 Oracle Integration Cloud MCP 服务器连接到 Codex — 设置 OAuth 客户端凭据,获取访问令牌,在 Codex 中注册 OIC 项目的 MCP 服务器,并确认其工具能显示在 CLI 和桌面应用中。
  • 使用 Docker 和 VS Code 在本地运行 Neo4j MCP 服务器 — 使用 Docker Compose 自主托管 Neo4j 及其官方 MCP 服务器,通过 HTTP 的基本认证进行安全保护,以 Agent 模式连接 VS Code,然后查询演示图谱。
  • 实用笔记:构建公共的、经过身份验证的MCP服务器:实战指南 — 该指南提供了详细的操作步骤,包括合同定义、检查项以及供采用该模式的团队直接使用的代码片段。
  • 实用笔记:Spring AI + MCP:将你的Java工具暴露给任何AI客户端 — 该指南同样提供了详细的操作步骤,包括合同定义、检查项以及供采用该模式的团队直接使用的代码片段。