Inicio / Artículos

Proteger un servidor Spring AI MCP con OAuth 2.0 y ámbitos por herramienta.

Construir un servidor de autorización OAuth y convertir un servidor Spring AI MCP en un servidor de recursos, probarlo en MCP Inspector y luego restringir las herramientas individuales por ámbito.

Editor: REACTAPP.TOP8 min de lectura1762 palabras

Fuentes: Spring AI Recipe: Securing an MCP Server with OAuth

Una clave API es la forma sencilla de proteger un servidor MCP, pero también es un instrumento poco preciso. Cuando se necesita una protección más robusta, OAuth 2.0 es el siguiente paso lógico, y Spring AI puede utilizarlo tanto para proteger el servidor como para aplicar autorizaciones detalladas a herramientas individuales. OAuth ha protegido aplicaciones y APIs durante más de diez años, y algunos complementos específicos para MCP le permiten proteger también a los servidores MCP. La configuración requiere dos componentes: un servidor de autorización que emite tokens y un servidor MCP que los acepta.

Construcción del servidor de autorización

El servidor de autorización es el lugar donde el usuario inicia sesión y permite que un cliente acceda a un servidor de recursos en su nombre. En términos de MCP, el servidor MCP es el servidor de recursos, y el cliente es cualquier agente o aplicación con capacidad de IA que lo llama.

Comience con un nuevo proyecto Spring Boot desde Initializr, ya sea en start.spring.io o dentro de un IDE, seleccionando tres dependencias: Spring Web, Spring Security y OAuth2 Authorization Server. Después de crear el proyecto, será necesario agregar otra dependencia al proyecto.

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

Esa biblioteca Spring AI Community aporta funciones específicas de MCP al servidor de autorización, en particular el registro dinámico de clientes (DCR) e indicadores de recursos.

A continuación se encuentra una clase de configuración que define la cadena de filtros de seguridad.

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

}

Esta clase realiza cuatro funciones: activa la seguridad web, exige autenticación para las solicitudes al servidor de autorización, habilita el inicio de sesión por formulario de Spring Security junto con su página de inicio de sesión predeterminada, y activa las capacidades del servidor de autorización específicas para MCP.

El trabajo restante corresponde a las propiedades de configuración. El formato YAML en src/main/resources/application.yaml es más adecuado para esto que un archivo de propiedades tradicional.

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

La mayor parte de este archivo declara un único cliente OAuth. Un sistema en producción guardaría los registros de los clientes en algún lugar como una base de datos, pero un cliente definido en la configuración es suficiente para una demostración. El cliente de demostración utiliza el ID “myclient” y la clave secreta “mysecret”. La clave secreta lleva un prefijo “{noop}”, lo que indica a Spring Security que se almacena como texto plano. Esto es conveniente aquí, pero no es recomendable en entornos reales.

El cliente se autentica ante el servidor de autorización mediante HTTP Basic y utiliza el método de concesión de código de autorización para obtener un token de acceso. MCP Inspector será la herramienta de prueba. Puede ejecutarse en localhost o 127.0.0.1, escucha en el puerto 6274 y maneja las llamadas de retorno en la ruta /oauth/callback, por lo que se configuran URI de redirección para ambos nombres de host.

El cliente puede solicitar cualquiera de los tres alcances al pedir un token: acceso general, meteorología y administración. La configuración también define un usuario de demostración. Al igual que en el caso del cliente, una implementación real cargaría los usuarios desde un almacén de usuarios adecuado. El puerto 9999 es donde escucha.

Esto completa esta parte de la configuración. Se puede iniciar de inmediato o esperar hasta que el servidor MCP esté listo.

Conviirtiendo el servidor MCP en un servidor de recursos

Para el servidor MCP, se debe partir del código de la versión anterior con clave API. La compilación requiere tres dependencias.

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'

Los dos primeros ya deberían estar presentes gracias a la configuración de la API-key. El tercero agrega el soporte del servidor de recursos OAuth 2.0 de Spring Security.

El servidor de recursos también debe saber dónde se encuentra su servidor de autorización. Dado que ese servidor está ejecutándose en localhost en el puerto 9999, una propiedad en application.properties se encarga de ello.

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

La autoconfiguración abarca gran parte del trabajo, pero la seguridad del servidor MCP se configura de forma explícita para indicarle al soporte de seguridad de MCP dónde encontrar el servidor de autorización.

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

}

La ubicación del servidor de autorización proviene de la propiedad definida hace un momento, y la cadena de filtros requiere autenticación para cada solicitud. Eso es todo lo necesario para convertir al servidor MCP en un servidor de recursos protegido por OAuth.

Probándolo en MCP Inspector

Ejecuta tanto el servidor de autorización como el servidor MCP, luego inicia MCP Inspector siguiendo las instrucciones de la documentación de MCP. Los pasos en el Inspector son los siguientes:

  1. Haz clic en Add Servers en la esquina superior izquierda y crea un servidor con la URL http://localhost:3000, luego haz clic en Add. Aparecerá un panel de servidores.
  2. Antes de conectarte, proporciona las credenciales del cliente. Abre el enlace Settings en la esquina inferior derecha del panel, desplázate hasta la sección OAuth Settings en la parte inferior, expande ella y escribe myclient como Client ID y mysecret como Client Secret.
  3. Deje todo lo demás como está por ahora, incluidos los Scopes, y cierre el panel de configuración.
  4. Conéctese mediante el botón deslizante en la esquina superior derecha del panel del servidor. Si todo está bien, el navegador redirigirá a la página de inicio de sesión del servidor de autorización. Inicie sesión como el usuario de demostración definido en el YAML.
  5. Después de iniciar sesión, el navegador vuelve al MCP Inspector con una conexión exitosa, y las solicitudes que lo configuraron aparecen en el panel de la derecha.
  6. Abra la pestaña Herramientas. La lista debe incluir get-weather-for-zipcode. Selecciónela, escriba cualquier código postal en el campo zipcode y haga clic en Ejecutar herramienta. El resultado del servidor MCP se devuelve en formato JSON.

El servidor MCP ahora exige autenticación OAuth. Pero hasta ahora es todo o nada: un cliente autorizado para conectarse puede utilizar todo lo que expone el servidor.

Proteger herramientas individuales

La seguridad aplicada hasta ahora cubre al servidor en su totalidad. Las herramientas, recursos, comandos y otras capacidades se encuentran detrás de una conexión autenticada, pero una vez que un cliente pasa por esa puerta de entrada, todo está disponible. Si diferentes herramientas, comandos o recursos tienen requisitos de autorización distintos, la seguridad por métodos de Spring Security permite establecer reglas más detalladas.

El primer cambio se refiere a la configuración de seguridad del servidor 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();
  }

}

Hay dos diferencias. La clase ahora incluye @EnableMethodSecurity, lo que permite establecer reglas de autorización directamente en los métodos de la herramienta. Además, en lugar de requerir autenticación en cada solicitud, authorizeHttpRequests() permite que las solicitudes al endpoint /mcp pasen sin condiciones, mientras que en otros lugares sigue siendo necesaria la autenticación. La autorización de cada llamada a la herramienta se aplica entonces a nivel de método.

Supongamos que llamar a get-weather-for-zipcode debería exigir el ámbito OAuth de meteorología. La anotación @PreAuthorize expresa eso.

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

La anotación exige que la autorización actual incluya el ámbito de meteorología. Spring Security modela los ámbitos OAuth como autorizaciones otorgadas precedidas por SCOPE_, lo que explica por qué la expresión verifica la presencia de SCOPE_meteorology.

La definición de la herramienta también cuenta con algunos atributos opcionales de indicación, proporcionados a través del atributo annotations, que ofrecen información útil a los clientes:

  • La herramienta no es de tipo mundo abierto. Es completamente autónoma y no llama a ninguna API externa. Si se reescribiera para utilizar una API meteorológica, la indicación debería ser true, o simplemente omitirse, ya que su valor por defecto es true.
  • La herramienta no modifica ni elimina nada, ya que solo obtiene datos meteorológicos, por lo que no es destructiva.
  • Al ser no destructiva, resulta idempotente. En el caso de una herramienta destructiva, la idempotencia requiere consideración y el atributo idempotentHint debe ajustarse en consecuencia.

Viendo cómo funciona la verificación de alcance

Reinicie el servidor MCP, vuelva al MCP Inspector y abra Configuración de OAuth antes de reconectarse. El botón “Eliminar estado de OAuth almacenado” en la parte inferior elimina cualquier token restante de la autorización anterior, así que úselo.

Conéctese nuevamente, inicie sesión, vuelva a usar get-weather-for-zipcode e inténtelo de nuevo. Esta vez es muy probable que la llamada falle. Nunca se solicitó al servidor de autorización que concediera el alcance de meteorología, por lo que la autenticación por sí sola ya no es suficiente para esta herramienta.

Ahora agregue “meteorología” al campo “Alcances” en Configuración de OAuth, elimine el estado almacenado si es necesario, conéctese de nuevo y ejecute la herramienta una vez más. Debería tener éxito, ya que el token de acceso recién emitido incluye el alcance de meteorología que exige @PreAuthorize.

Unos pocos complementos al soporte OAuth ya existente en Spring Security fueron suficientes para pasar de un servidor MCP protegido con claves API a uno que requiere OAuth, y posteriormente a una autorización basada en alcances para cada herramienta en particular.