Accueil / Articles

Sécuriser un serveur Spring AI MCP avec OAuth 2.0 et des portées par outil.

Créer un serveur d’autorisation OAuth et transformer un serveur Spring AI MCP en serveur de ressources, le tester dans MCP Inspector, puis restreindre les outils individuels par portée.

Éditeur : REACTAPP.TOP8 min de lecture1762 mots

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

Une clé API est un moyen simple de protéger un serveur MCP, mais c’est aussi un outil peu précis. Lorsqu’une protection plus forte est nécessaire, OAuth 2.0 constitue la solution naturelle suivante, et Spring AI peut l’utiliser tant pour sécuriser le serveur que pour appliquer une autorisation fine aux outils individuels. OAuth assure la sécurité des applications et des API depuis plus de dix ans, et quelques fonctionnalités spécifiques à MCP lui permettent également de couvrir les serveurs MCP. La configuration nécessite deux éléments : un serveur d’autorisation qui émet des jetons, et un serveur MCP qui les accepte.

Création du serveur d’autorisation

Le serveur d’autorisation est l’endroit où l’utilisateur se connecte et autorise un client à accéder à un serveur de ressources en son nom. En termes MCP, le serveur MCP est le serveur de ressources, et le client est tout agent ou application dotée d’intelligence artificielle qui l’appelle.

Commencez par un nouveau projet Spring Boot via Initializr, que ce soit sur start.spring.io ou à l’intérieur d’un IDE, en sélectionnant trois dépendances : Spring Web, Spring Security et OAuth2 Authorization Server. Une autre dépendance doit être ajoutée au projet une fois celui-ci créé.

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

Cette bibliothèque Spring AI Community apporte des fonctionnalités spécifiques à MCP au serveur d’autorisation, notamment l’enregistrement dynamique des clients (DCR) et les indicateurs de ressources.

Ensuite vient une classe de configuration qui définit la chaîne de filtres de sécurité.

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

}

Cette classe effectue quatre tâches : elle active la sécurité web, exige une authentification pour les demandes adressées au serveur d’autorisation, active le formulaire de connexion de Spring Security ainsi que sa page de connexion par défaut, et active les fonctionnalités spécifiques au serveur d’autorisation MCP.

Le reste consiste en des propriétés de configuration. Le format YAML dans src/main/resources/application.yaml convient mieux à ces besoins qu’un fichier 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

La majeure partie de ce fichier définit un seul client OAuth. Un système en production conserverait les enregistrements des clients dans une base de données, mais un client défini dans la configuration suffit pour une démonstration. Le client de démonstration utilise l’ID « myclient » et le secret « mysecret ». Le secret comporte un préfixe « {noop} », ce qui indique à Spring Security qu’il est stocké en texte brut. Cela est pratique ici, mais déconseillé dans tout environnement réel.

Le client s’authentifie auprès du serveur d’autorisation via HTTP Basic et utilise le mécanisme d’attribution par code d’autorisation pour obtenir un jeton d’accès. MCP Inspector servira d’outil de test. Il peut fonctionner sur localhost ou 127.0.0.1, écoute sur le port 6274 et gère les appels de retour sur le chemin /oauth/callback ; par conséquent, des URI de redirection sont configurées pour ces deux noms d’hôte.

Le client peut demander l’un des trois niveaux d’accès lors de la demande d’un jeton : accès général, météorologie et administration. La configuration définit également un utilisateur de démonstration. Tout comme pour le client, un déploiement réel chargerait les utilisateurs depuis un stockage d’utilisateurs approprié. Le port 9999 est celui sur lequel il écoute.

Cela termine cette partie de la configuration. Elle peut être lancée immédiatement ou attendre que le serveur MCP soit prêt.

Transformer le serveur MCP en serveur de ressources

Pour le serveur MCP, partez du code de la version précédente basée sur des clés API. La compilation nécessite trois dépendances.

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'

Les deux premiers devraient déjà être présents suite à la configuration de la clé API. Le troisième ajoute le support du serveur de ressources OAuth 2.0 de Spring Security.

Le serveur de ressources doit également connaître l’emplacement de son serveur d’autorisation. Étant donné que ce dernier tourne sur localhost sur le port 9999, une propriété dans application.properties s’en charge.

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

L’auto-configuration prend en charge une grande partie du travail, mais la sécurité du serveur MCP est configurée explicitement afin d’indiquer au mécanisme de sécurité MCP où trouver le serveur d’autorisation.

@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 localisation du serveur d’autorisation provient de la propriété définie il y a un instant, et la chaîne de filtres exige une authentification pour chaque requête. C’est tout ce qui est nécessaire pour faire du serveur MCP un serveur de ressources protégé par OAuth.

Essayer dans MCP Inspector

Exécutez à la fois le serveur d’autorisation et le serveur MCP, puis lancez MCP Inspector en suivant les instructions de la documentation MCP. Les étapes dans l’Inspecteur sont les suivantes :

  1. Cliquez sur « Ajouter des serveurs » en haut à gauche et créez un serveur avec l’URL http://localhost:3000, puis cliquez sur « Ajouter ». Un panneau des serveurs apparaît.
  2. Avant de vous connecter, saisissez les identifiants du client. Ouvrez le lien « Paramètres » en bas à droite du panneau, faites défiler jusqu’à la section « Paramètres OAuth » en bas, développez-la, et entrez « myclient » comme identifiant de client et « mysecret » comme secret de client.
  3. Laissez tout le reste de côté pour l’instant, y compris Scopes, et fermez le panneau des paramètres.
  4. Connectez-vous en utilisant le bouton glissière en haut à droite du panneau du serveur. Si tout est en ordre, le navigateur redirige vers la page de connexion du serveur d’autorisation. Connectez-vous en tant qu’utilisateur de démon défini dans le fichier YAML.
  5. Après connexion, le navigateur revient à MCP Inspector avec une connexion réussie, et les requêtes qui l’ont configurée apparaissent dans le panneau de droite.
  6. Ouvrez l’onglet Outils. La liste doit inclure get-weather-for-zipcode. Sélectionnez-la, saisissez un code postal dans le champ zipcode et cliquez sur Exécuter l’outil. Le résultat provenant du serveur MCP est renvoyé sous forme de JSON.

Le serveur MCP exige maintenant une authentification OAuth. Mais pour l’instant, c’est soit tout, soit rien : un client autorisé à se connecter peut utiliser tout ce que le serveur met à disposition.

Protéger les outils individuels

La sécurité mise en œuvre jusqu’à présent couvre l’ensemble du serveur. Les outils, les ressources, les commandes et autres fonctionnalités se trouvent tous derrière une connexion authentifiée, mais une fois que le client a franchi cette porte d’entrée, tout devient accessible. Si différents outils, commandes ou ressources exigent des niveaux d’autorisation différents, la sécurité de méthode de Spring Security permet d’établir des règles plus précises.

La première modification concerne la configuration de sécurité du serveur 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();
  }

}

Deux éléments diffèrent. La classe porte désormais l’annotation @EnableMethodSecurity, ce qui permet d’appliquer des règles d’autorisation directement sur les méthodes utilitaires. De plus, au lieu d’exiger une authentification pour chaque requête, la méthode authorizeHttpRequests() autorise désormais les requêtes vers l’endpoint /mcp sans condition, tout en exigeant encore une authentification ailleurs. L’autorisation de chaque appel à une méthode utilitaire est alors appliquée au niveau de la méthode elle-même.

Supposons que l’appel de get-weather-for-zipcode doive nécessiter la portée OAuth météorologique. L’annotation @PreAuthorize exprime cela.

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

L’annotation exige que l’autorisation actuelle inclue la portée météorologique. Spring Security représente les portées OAuth sous forme d’autorisations accordées préfixées par SCOPE_, ce qui explique pourquoi l’expression vérifie la présence de SCOPE_meteorology.

La définition de l’outil dispose également de quelques attributs d’indication optionnels, fournis via l’attribut annotations, qui fournissent aux clients des informations utiles :

  • L’outil n’est pas de type monde ouvert. Il est entièrement autonome et n’appelle aucune API externe. S’il était réécrit pour utiliser une API météorologique, l’indication devrait être vraie, ou simplement omise, étant donné qu’elle vaut par défaut vraie.
  • L’outil ne modifie ni ne supprime rien, car il ne fait que récupérer des données météorologiques ; il n’est donc pas destructeur.
  • Le fait d’être non destructeur en fait un outil idempotent. Pour un outil destructeur, l’idempotence nécessite une réflexion approfondie, et l’attribut idempotentHint doit être configuré en conséquence.

Voir le fonctionnement de la vérification des droits

Redémarrez le serveur MCP, revenez à l’inspecteur MCP et ouvrez les Paramètres OAuth avant de vous reconnecter. Le bouton « Effacer l’état OAuth stocké » en bas supprime tous les tokens restants de l’autorisation précédente, alors utilisez-le.

Reconnectez-vous, connectez-vous, retournez sur get-weather-for-zipcode et appelez-le à nouveau. Cette fois, l’appel échouera très probablement. Le serveur d’autorisation n’a jamais été sollicité pour accorder les droits liés à la météorologie, donc l’authentification seule ne suffit plus pour cet outil.

Ajoutez maintenant « météorologie » au champ « Scopes » dans les Paramètres OAuth, effacez l’état stocké si nécessaire, reconnectez-vous et exécutez l’outil une fois de plus. Cela fonctionnera, car le token d’accès nouvellement émis contient les droits de météorologie exigés par @PreAuthorize.

Quelques ajouts au support OAuth existant de Spring Security ont suffi pour passer d’un serveur MCP protégé par une clé API à un serveur exigeant OAuth, puis à une autorisation basée sur des scopes pour chaque outil individuel.