使用OAuth 2.0及按工具划分的作用域来保护Spring AI MCP服务器的安全。
构建一个OAuth授权服务器,将Spring AI MCP服务器转换为资源服务器,在MCP Inspector中进行测试,然后通过作用域限制单个工具的访问。
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中的操作步骤如下:
- 点击左上角的“添加服务器”,使用URL http://localhost:3000创建一个服务器,然后点击“添加”。此时会出现一个服务器面板。
- 在连接之前,需提供客户端凭证。打开面板右下角的“设置”链接,滚动到底部的“OAuth设置”部分,展开它,将“Client ID”填为“myclient”,将“Client Secret”填为“mysecret”。
现在 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 认证的服务器,进而实现针对各个工具的基于权限范围的授权。
相关阅读
- 用通俗语言解读 MCP:AI 助手与软件之间的共享接口 — 介绍模型上下文协议是什么,客户端与服务器如何连接,读、写、创建操作的实现方式,以及为何该技术在 2026 年迅速普及。