Strona główna / Artykuły

Zabezpiecz serwer Spring AI MCP przy użyciu OAuth 2.0 oraz zakresów dostępu dla poszczególnych narzędzi.

Stwórz serwer autoryzacji OAuth i przekształć serwer Spring AI MCP w serwer zasobów, przetestuj go w MCP Inspector, a następnie ogranicz dostęp do poszczególnych narzędzi za pomocą zakresów.

Wydawca: REACTAPP.TOP8 min czytania1762 słów

Źródła: Spring AI Recipe: Securing an MCP Server with OAuth

Klucz API to prosty sposób na ochronę serwera MCP, ale jest to również narzędzie mało precyzyjne. Gdy potrzebna jest silniejsza ochrona, naturalnym następnym krokiem jest OAuth 2.0, który Spring AI może wykorzystać zarówno do zabezpieczenia serwera, jak i do stosowania szczegółowej autoryzacji dla poszczególnych narzędzi. OAuth od ponad dziesięciu lat zabezpiecza aplikacje i API, a kilka dodatków specyficznych dla MCP umożliwia mu ochronę również serwerów MCP. Konfiguracja wymaga dwóch elementów: serwera autoryzacji, który wydaje tokeny, oraz serwera MCP, który je przyjmuje.

Budowa serwera autoryzacji

Serwer autoryzacji to miejsce, gdzie użytkownik się loguje i umożliwia klientowi dostęp do serwera zasobów w jego imieniu. W kontekście MCP serwer MCP jest serwerem zasobów, a klientem jest dowolny agent lub aplikacja wyposażona w AI, która do niego się odwołuje.

Zacznij od nowego projektu Spring Boot za pomocą Initializr, zarówno na stronie start.spring.io, jak i w środowisku IDE, wybierając trzy zależności: Spring Web, Spring Security oraz OAuth2 Authorization Server. Po utworzeniu projektu konieczna jest dodatkowa zależność do pliku build.

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

Biblioteka Spring AI Community wprowadza funkcje specyficzne dla MCP do serwera autoryzacji, w szczególności dynamiczną rejestrację klientów (DCR) oraz wskaźniki zasobów.

Następnie pojawia się klasa konfiguracyjna, która definiuje łańcuch filtrów bezpieczeństwa.

@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();
  }

}

Klasa ta wykonuje cztery zadania. Włącza zabezpieczenia sieciowe, wymaga autoryzacji dla żądań skierowanych do serwera autoryzacji, aktywuje formularz logowania Spring Security wraz z jego domyślną stroną logowania oraz uruchamia funkcje specyficzne dla serwera autoryzacji MCP.

Pozostała praca dotyczy właściwości konfiguracyjnych. YAML w pliku src/main/resources/application.yaml lepiej nadaje się do tego celu niż plik 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

Większość tego pliku deklaruje jeden klient OAuth. System produkcyjny przechowywałby rejestracje klientów w bazie danych, ale dla demonstracji wystarczy klient zdefiniowany w konfiguracji. Klient demonstracyjny używa identyfikatora myclient oraz sekretu mysecret. Sekret ma przedrostek {noop}, który informuje Spring Security, że jest przechowywany jako zwykły tekst. Jest to wygodne w tym przypadku, ale niezalecane w żadnym rzeczywistym środowisku.

Klient autoryzuje się u serwera autoryzacji za pomocą protokołu HTTP Basic i wykorzystuje mechanizm grantu kodu autoryzacji, aby uzyskać token dostępu. Narzędziem testowym będzie MCP Inspector. Może działać na localhost lub 127.0.0.1, nasłuchiwać na porcie 6274 oraz obsługiwać powroty w adresie /oauth/callback, więc URI przekierowania są ustawione dla obu nazw hosta.

Klient może poprosić o jeden z trzech zakresów uprawnień przy żądaniu tokena: ogólny dostęp, meteorologia oraz administracja. Konfiguracja określa również jednego użytkownika demonstracyjnego. Podobnie jak w przypadku klienta, w rzeczywistym wdrożeniu użytkownicy byliby ładowani z odpowiedniego magazynu użytkowników. Serwer nasłuchuje na porcie 9999.

To zamyka tę część konfiguracji. Można ją uruchomić od razu lub poczekać, aż serwer MCP będzie gotowy.

Przekształcenie serwera MCP w serwer zasobów

Dla serwera MCP należy zacząć od kodu wcześniejszej wersji opartej na kluczu API. Do skompilowania potrzebne są trzy zależności.

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'

Pierwsze dwa powinny już być obecne po ustawieniu klucza API. Trzeci dodaje wsparcie dla serwera zasobów OAuth 2.0 w Spring Security.

Serwer zasobów musi również wiedzieć, gdzie znajduje się jego serwer autoryzacji. Ponieważ ten serwer działa na localhost pod portem 9999, wystarczy jedna właściwość w pliku application.properties, aby to zapewnić.

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

Automatyczna konfiguracja obejmuje większość zadań, ale bezpieczeństwo serwera MCP jest konfigurowane wyraźnie, aby wsparcie bezpieczeństwa MCP wiedziało, gdzie znaleźć serwer autoryzacji.

@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();
  }

}

Lokalizacja serwera autoryzacji pochodzi od właściwości zdefiniowanej chwilę wcześniej, a łańcuch filtrów wymaga autoryzacji dla każdej żądania. To wszystko, co jest potrzebne, aby serwer MCP stał się serwerem zasobów chronionym przez OAuth.

Próba w MCP Inspector

Zainstaluj i uruchom zarówno serwer autoryzacji, jak i serwer MCP, a następnie uruchom MCP Inspector zgodnie z instrukcjami zawartymi w dokumentacji MCP. Kroki w inspektorze wyglądają następująco:

  1. Kliknij „Add Servers” w lewym górnym rogu i utwórz serwer przy użyciu adresu http://localhost:3000, a następnie kliknij „Add”. Pojawi się panel serwerów.
  2. Przed połączeniem podaj dane klienta. Otwórz link „Settings” w prawym dolnym rogu panelu, przewiń się do sekcji „OAuth Settings” na dole, rozwiń ją i wpisz „myclient” jako Client ID oraz „mysecret” jako Client Secret.
  3. Na razie zostaw wszystko inne bez zmian, włączając Scopes, i zamknij panel ustawień.
  4. Połącz się za pomocą przycisku suwaka w prawym górnym rogu panelu serwera. Jeśli wszystko jest w porządku, przeglądarka przekieruje Cię na stronę logowania serwera autoryzacji. Zaloguj się jako użytkownik demo zdefiniowany w pliku YAML.
  5. Po zalogowaniu przeglądarka wraca do MCP Inspector z poinformowaniem o udanej łączności, a żądania niezbędne do jej ustanowienia pojawiają się w panelu po prawej stronie.
  6. Otwórz zakładkę Narzędzia. Lista powinna zawierać opcję get-weather-for-zipcode. Wybierz ją, wpisz dowolny kod pocztowy do pola zipcode i kliknij Execute Tool. Wynik z serwera MCP zostanie przesłany w formacie JSON.

Teraz serwer MCP wymaga autoryzacji OAuth. Ale jak dotąd obowiązuje zasada „wszystko albo nic”: klient uprawniony do połączenia może korzystać ze wszystkiego, co udostępnia serwer.

Ochrona poszczególnych narzędzi

Obecnie stosowana ochrona obejmuje cały serwer. Narzędzia, zasoby, polecenia oraz inne funkcje znajdują się za zabezpieczonym połączeniem, ale po przejściu klienta przez tę „przednią bramę” wszystko staje się dostępne. Jeśli różne narzędzia, polecenia lub zasoby wymagają różnych uprawnień, mechanizm bezpieczeństwa Spring Security umożliwia ustalenie bardziej precyzyjnych reguł.

Pierwszą zmianą jest konfiguracja bezpieczeństwa serwera 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();
  }

}

Dwie rzeczy się różnią. Klasa zawiera teraz @EnableMethodSecurity, co umożliwia umieszczanie reguł autoryzacji bezpośrednio w metodach narzędziowych. Ponadto zamiast wymagać autoryzacji przy każdej prośbie, metoda authorizeHttpRequests() pozwala na bezwarunkowe przekierowanie żądań do endpointu /mcp, zachowując jednocześnie wymóg autoryzacji w innych miejscach. Autoryzacja każdego wywołania narzędzia jest następnie realizowana na poziomie metody.

Załóżmy, że wywołanie metody get-weather-for-zipcode powinno wymagać zakresu OAuth związанego z meteorologią. To właśnie wyraża adnotacja @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);
}

Anotacja wymaga, aby obecna autoryzacja obejmowała zakres meteorologii. Spring Security traktuje zakresy OAuth jako uprawnienia o prefiksie SCOPE_, co wyjaśnia, dlaczego wyrażenie sprawdza wartość SCOPE_meteorology.

Definicja narzędzia otrzymuje również kilka opcjonalnych atrybutów informacyjnych, dostarczanych przez atrybut annotations, które przekazują klientom przydatne informacje:

  • Narzędzie nie jest typu „otwarty świat”. Jest w pełni samodzielne i nie korzysta z żadnych zewnętrznych API. Gdyby zostało przepisane tak, aby używać API pogodowego, informacja ta powinna być prawdziwa lub po prostu pominięta, ponieważ domyślnie ma wartość prawdziwą.
  • Narzędzie nic nie zmienia ani nie usuwa, ponieważ pobiera jedynie dane pogodowe, więc nie jest destruktywne.
  • Fakt, że nie jest destruktywne, sprawia, że jest idempotentne. W przypadku narzędzia destruktywnego idempotentność wymaga szczególnej uwagi, a atrybut idempotentHint powinien być ustawiony odpowiednio.

Zobaczenie, jak działa sprawdzanie zakresu uprawnień

Uruchom ponownie serwer MCP, wróć do MCP Inspector i otwórz Ustawienia OAuth przed ponownym połączeniem. Przycisk „Czyść zapisany stan OAuth” u dołu usuwa wszystkie tokeny pozostałe po poprzedniej autoryzacji, więc skorzystaj z niego.

Ponownie się połącz, zaloguj, wróć do funkcji get-weather-for-zipcode i wywołaj ją ponownie. Tym razem wywołanie najprawdopodobniej się nie powiedzie – serwer autoryzacji nigdy nie został poproszony o przyznanie uprawnień związanych z meteorologią, więc sama autoryzacja już nie wystarcza dla tego narzędzia.

Teraz dodaj „meteorologia” do pola „Zakresy” w Ustawieniach OAuth, w razie potrzeby wytrzyj zapisany stan, ponownie się połącz i uruchom narzędzie jeszcze raz. Powinno to się udać, ponieważ świeżo wydany token dostępu zawiera zakres uprawnień związanych z meteorologią, który wymaga @PreAuthorize.

Wystarczyło zaledwie kilka ulepszeń istniejącego wsparcia OAuth w Spring Security, aby przejść od serwera MCP chronionego kluczem API do takiego, który wymaga OAuth, a następnie do autoryzacji opartej na zakresach dostępu dla poszczególnych narzędzi.

Literatura pokrewna