Защита сервера Spring AI MCP с использованием OAuth 2.0 и диапазонов доступа для каждого инструмента.
Создайте сервер авторизации OAuth и преобразуйте сервер Spring AI MCP в сервер ресурсов, протестируйте его в MCP Inspector, затем ограничьте доступ к отдельным инструментам с помощью диапазонов.
Источники: Spring AI Recipe: Securing an MCP Server with OAuth
Ключ API — это простой способ защиты сервера MCP, но он также является довольно грубым инструментом. Когда требуется более строгая защита, следующим логичным шагом становится OAuth 2.0, который Spring AI может использовать как для защиты сервера, так и для настройки тонкой аутентификации отдельных инструментов. OAuth уже более десяти лет обеспечивает безопасность приложений и API, а несколько дополнений, специально разработанных для MCP, позволяют применять его и к серверам MCP. Для настройки требуются два компонента: сервер авторизации, выдающий токены, и сервер MCP, принимающий их.
Создание сервера авторизации
Сервер авторизации — это место, где пользователь входит в систему, разрешая клиенту получать доступ к серверу ресурсов от его имени. В терминах MCP сервер MCP является сервером ресурсов, а клиентом выступает любой агент или приложение с поддержкой ИИ, обращающееся к нему.
Начните с нового проекта Spring Boot через Initializr — либо на сайте start.spring.io, либо внутри IDE — выбрав три зависимости: 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.
Оставшаяся работа связана с настройками свойств. Для этого лучше подходит YAML-файл в src/main/resources/application.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 и метода authorization code grant для получения токена доступа. В качестве инструмента тестирования будет использоваться 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-ключа. Третий добавляет поддержку сервера ресурсов OAuth 2.0 от Spring Security.
Сервер ресурсов также должен знать, где находится его сервер авторизации. Поскольку этот сервер запущен на localhost по порту 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 Inspector согласно инструкциям в документации MCP. Шаги в Inspector выглядят следующим образом:
- Нажмите «Добавить серверы» в левом верхнем углу и создайте сервер с URL http://localhost:3000, затем нажмите «Добавить». Появится панель серверов.
- Перед подключением укажите учетные данные клиента. Откройте ссылку «Настройки» в правом нижнем углу панели, прокрутитесь до раздела «Настройки OAuth» внизу, раскройте его и введите «myclient» в качестве Client ID, а «mysecret» — в качестве Client Secret.
Теперь сервер 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 meteorology. Это указывается с помощью аннотации @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.
Достаточно было лишь нескольких дополнений к существующей поддержке OAuth в Spring Security, чтобы перейти от сервера MCP с защитой с помощью API-ключей к серверу, требующему OAuth, а затем к авторизации на уровне диапазонов полномочий для отдельных инструментов.