Головна / Статті

Забезпечте безпеку сервера Spring AI MCP за допомогою OAuth 2.0 та сфер дії для кожного інструменту.

Створіть сервер авторизації OAuth та перетворіть сервер Spring AI MCP на сервер ресурсів, протестуйте його в MCP Inspector, а потім обмежте використання окремих інструментів за межами їхньої сфери дії.

Видавець: REACTAPP.TOP8 хв читання1762 слів

Джерела: 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 краще підходить для цього, ніж файл properties.

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-ключа. Третій додає підтримку сервера ресурсів 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. Кроки у інспекторі виглядають так:

  1. Натисніть «Додати сервери» у верхньому лівому куті та створіть сервер із URL http://localhost:3000, після чого натисніть «Додати». З’явиться панель серверів.
  2. Перед підключенням введіть облікові дані клієнта. Відкрийте посилання «Налаштування» у нижньому правому куті панелі, прокрутіться до розділу «Налаштування OAuth» унизу, розгорніть його та введіть «myclient» як Client ID та «mysecret» як Client Secret.
  • Наразі залиште все інше як є, включаючи Scopes, та закрийте панель налаштувань.
  • Підключіться за допомогою кнопки-слайдера у верхньому правому куті панелі сервера. Якщо все гаразд, браузер перенаправить вас на сторінку входу сервера автентифікації. Увійдіть як користувач демо-версії, визначений у YAML-файлі.
  • Після входу браузер повертається до MCP Inspector із повідомленням про успішне підключення, а запити, які його налаштували, з’являються у панелі з правого боку.
  • Відкрийте вкладку «Інструменти». У списку має бути опція get-weather-for-zipcode. Виберіть її, введіть будь-який ZIP-код у поле zipcode та натисніть Execute Tool. Результат від сервера 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 та спробуйте її викликати ще раз. Цього разу виклик, найімовірніше, зазнає невдачі. Сервер авторизації так і не отримував запиту на надання діапазону повноважень для метеорології, тому лише автентифікація більше недостатня для цього інструменту.

    Тепер додайте «метеорологію» у поле Scopes у налаштуваннях OAuth, за потреби очистіть збережений стан, підключіться знову та запустіть інструмент ще раз. Це має спрацювати, оскільки нещодавно виданий токен доступу містить діапазон повноважень для метеорології, який вимагається @PreAuthorize.

    Лише кілька доповнень до існуючої підтримки OAuth у Spring Security було достатньо, щоб перейти від сервера MCP, захищеного API-ключем, до сервера, який вимагає OAuth, а потім до авторизації на основі обмежень для окремих інструментів.