Галоўная / Артыкулы

Забезпечыце сервер 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 ёсць серверам рэсурсаў, а кліентам выступае будзь-які агент або аплікацыя, якая выкарыстоўвае тэхналогіі AI, і якая з’яўляецца да яго.

Пачніце з новага праекта 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. У прыметнай сістэме рэўістрацыя кліента была бы зберагвана ў базе дадзенаў, але для дамастрацыі дастатнекі кліент, заданы ў настройках. Кліент для дамастрацыі выкарыстоўвае ID «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. Крокі ў Inspector выглядаюць так:

  1. Клікніце на «Add Servers» у верхнім левым канцы і створыце сервер з URL http://localhost:3000, пасля чаго клікніце «Add». Апыяецца панель сервераў.
  2. Перад падключэннем укажыце даны кліента. Ачыніце лінк «Settings» у ніжнім правым канцы панелі, праскруціцеся да раздзела «OAuth Settings» у ніжней частцы, раскройце яго і уведзіце «myclient» як Client ID, а «mysecret» — як Client Secret.
  • Зараз залішыце все іншае каля сабе, укладаючы і Scopes, і закрыце панель налашоўкаў.
  • З’яўіцеся на панелі сервера за дапамогай кнопкі-слайдэра ў верхнім правым канцы. Якшто все гаразд, браузер пераправіце на стороннюю сторону абмовы, дзе трэба абмовіцца. Абмовіцеся як дэмавы корыстнік, заданы ў YAML-файле.
  • Пасля абмовы браузер вернуецеся на MCP Inspector з паведамленнем пра успехаванае з’яўленне, а запыты, якія яго налаштавалі, пакажуцца ў панелі справа.
  • Ачыніце вікно «Інструменты». У спісе павінен быць элемент get-weather-for-zipcode. Выберыце яго, упісце будзь-які код ZIP у поле 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.

    Дастык дадзеных функцыяй да існуючага падтрымкі OAuth у Spring Security быў достатны, каб перайсці з сервера MCP, захішчанага API-клучамі, да сервера, які выкарыстоўвае OAuth, а пасля — да автарызаціі на адзінаковых інструментах на адной основе дыячоў.

    Спадневаная літэратура

  • Практычныя прыміткі: Я створыў сервер Kubernetes MCP з 453 тэстамі, якія працавалі. Потым я — Паспэўны апіс практычных прымітак: Я створыў сервер Kubernetes MCP з 453 тэстамі, якія працавалі. Потым я: контракты, перакананні і месцы для коду для команд, якія вікорыстоўваюць гэты патэрн.
  • Нямаяная колькасць нараджэнняў сярод столькі коду? Аўдыт 300 пакетаў npm MCP — Аўдыт у вачынку tarball 300 пакетаў npm MCP паказаў, што 217 з іх мелі код, які сканер ніколі не чытаў, і чаму чысты статычны рэзультат трэбуе паказніка паверхні пакрыцця.
  • З’еднання сервера Oracle Integration Cloud MCP з Codex на macOS — налаштаванне крэдытнаўх даных кліента OAuth, запрашэнне токена доступу, рэгістрацыя сервера MCP праекта OIC у Codex і паўтарчыя перакананні, што яго інструменты прадстаўляюцца ў CLI і дэсктопным прыкладзе.
  • Запуск сервера Neo4j MCP на вашай сабе машыне з Docker і VS Code — самастойны хостынг Neo4j і яго афіцыйнага сервера MCP за дапамогою Docker Compose, захаванне яго за дапамогою Basic Auth праз HTTP, з’еднанне VS Code у рэжыме Agent і запыт дэмавага графа.
  • Практычныя прыемкі: Стварэнне публічнага, аўтэнтыфікованага сервера MCP: Рабочы журнал — Паследовыя інструкцыі па вікорыстоўванні Практычных прыемакоў: Стварэнне публічнага, аўтэнтыфікованага сервера MCP: Рабочы журнал: контракты, перакананні і месцы для дадзення коду для команд, якія вікорыстоўваюць гэты патэрн.
  • Практычныя прыемкі: Spring AI + MCP: Адкрываеце свае Java-інструменты для будзь-якага кліента AI (нават — Паследовыя інструкцыі па вікорыстоўванні Практычных прыемакоў: Spring AI + MCP: Адкрываеце свае Java-інструменты для будзь-якага кліента AI (нават: контракты, перакананні і месцы для дадзення коду для команд, якія вікорыстоўваюць гэты патэрн.