Schützen Sie einen Spring AI MCP-Server mit OAuth 2.0 und Tool-spezifischen Scopes.
Erstellen Sie einen OAuth-Autorisierungsserver und wandeln Sie einen Spring AI MCP-Server in einen Ressourcenserver um, testen Sie ihn im MCP Inspector und beschränken Sie anschließend einzelne Tools durch Scope.
Quellen: Spring AI Recipe: Securing an MCP Server with OAuth
Eine API-Schlüssel ist die einfache Methode, um einen MCP-Server zu schützen, doch sie ist auch ein unpräzises Mittel. Wenn stärkere Schutzmaßnahmen erforderlich sind, ist OAuth 2.0 der natürliche nächste Schritt, und Spring AI kann es sowohl zur Sicherung des Servers als auch zur Anwendung feingranularer Autorisierungen für einzelne Tools nutzen. OAuth sichert bereits seit über zehn Jahren Apps und APIs, und einige spezielle Erweiterungen für MCP ermöglichen es ihm ebenfalls, MCP-Server zu schützen. Die Einrichtung erfordert zwei Komponenten: einen Autorisierungsserver, der Token ausstellt, und einen MCP-Server, der diese akzeptiert.
Aufbau des Autorisierungs Servers
Der Autorisierungsserver ist der Ort, an dem sich ein Benutzer anmeldet und einem Client erlaubt, im Namen dieses Benutzers auf einen Ressourcenserver zuzugreifen. In MCP-Begriffen ist der MCP-Server der Ressourcenserver, und der Client ist jede Art von Agent oder AI-fähiger Anwendung, die darauf zugreift.
Beginnen Sie mit einem neuen Spring Boot-Projekt über Initializr, sei es auf start.spring.io oder innerhalb einer IDE, wobei drei Abhängigkeiten ausgewählt werden müssen: Spring Web, Spring Security und OAuth2 Authorization Server. Nachdem das Projekt erstellt wurde, muss noch eine weitere Abhängigkeit zur Kompilierung hinzugefügt werden.
implementation 'org.springaicommunity:mcp-authorization-server:0.1.14'
Die Spring AI Community-Bibliothek bringt MCP-spezifische Funktionen zum Autorisierungsserver, insbesondere die dynamische Client-Registrierung (DCR) sowie Ressourcenindikatoren.
Danach folgt eine Konfigurationsklasse, die die Sicherheitsfilterkette definiert.
@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();
}
}
Diese Klasse erledigt vier Aufgaben. Sie aktiviert die Web-Sicherheit, erfordert eine Authentifizierung für Anfragen an den Autorisierungsserver, schaltet den Form-Anmeldemodus von Spring Security zusammen mit seiner Standard-Anmeldeseite ein und aktiviert die für MCP spezifischen Funktionen des Autorisierungs Servers.
Die verbleibende Arbeit betrifft die Konfigurationseinstellungen. YAML in src/main/resources/application.yaml eignet sich hier besser als eine Properties-Datei.
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
Der größte Teil dieser Datei deklariert einen OAuth-Client. Ein Produktivsystem würde die Client-Anmeldungen an einem Ort wie einer Datenbank speichern, aber für eine Demonstration reicht ein in der Konfiguration definierter Client aus. Der Demo-Client verwendet die ID „myclient“ sowie das Geheimniswort „mysecret“. Das Geheimniswort trägt das Präfix „{noop}“, was Spring Security mitteilt, dass es als einfacher Text gespeichert wird. Das ist hier praktisch, aber an keinem echten Ort empfehlenswert.
Der Client authentifiziert sich beim Autorisierungsserver mit HTTP Basic und verwendet den Authorization-Code-Grant, um einen Zugriffstoken zu erhalten. MCP Inspector wird das Testwerkzeug sein. Es kann auf localhost oder 127.0.0.1 laufen, hört auf Port 6274 zu und handhabt Callbacks am Pfad /oauth/callback; daher werden für beide Hostnamen Redirect-URI eingestellt.
Der Client kann bei der Anfrage nach einem Token einen von drei Berechtigungsmodi angeben: allgemeiner Zugriff, Meteorologie und Verwaltung. Die Konfiguration definiert außerdem einen Demo-Benutzer. Im Gegensatz zum Client würde eine echte Implementierung die Benutzer aus einem geeigneten Benutzerspeicher laden. An Port 9999 wird zugehört.
Damit ist diese Seite der Einrichtung abgeschlossen. Sie kann sofort gestartet werden oder bis zum Bereitsein des MCP-Servers aufgeschoben werden.
Den MCP-Server in einen Ressourcenserver umwandeln
Für den MCP-Server sollte man mit dem Code der früheren API-Schlüssel-Version beginnen. Die Kompilierung erfordert drei Abhängigkeiten.
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'
Die ersten beiden sollten bereits durch die Einstellung der API-Schlüssel vorhanden sein. Der dritte fügt die Unterstützung für den OAuth 2.0-Ressourcenserver von Spring Security hinzu.
Der Ressourcenserver muss außerdem wissen, wo sich sein Autorisierungsserver befindet. Da dieser Server auf localhost an Port 9999 läuft, reicht eine Eigenschaft in application.properties aus.
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:9999
Die Automatisierung übernimmt den größten Teil der Arbeit, doch die Sicherheit des MCP-Servers wird explizit konfiguriert, damit die MCP-Sicherheitsfunktionen wissen, wo der Autorisierungsserver zu finden ist.
@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();
}
}
Die Adresse des Autorisierungs Servers stammt von der zuvor definierten Eigenschaft, und die Filterkette erfordert für jede Anfrage eine Authentifizierung. Das ist alles, was benötigt wird, um den MCP Server zu einem durch OAuth geschützten Ressourcenserver zu machen.
Testen im MCP Inspector
Führen Sie sowohl den Autorisierungs Server als auch den MCP Server aus und starten Sie anschließend den MCP Inspector gemäß den Anweisungen in der MCP-Dokumentation. Die Schritte im Inspector lauten wie folgt:
- Klicken Sie oben links auf „Server hinzufügen“ und erstellen Sie einen Server mit der URL http://localhost:3000, klicken Sie dann auf „Hinzufügen“. Ein Server-Panel erscheint.
- Vor der Verbindung geben Sie die Client-Zertifikate an. Öffnen Sie den Link „Einstellungen“ unten rechts im Panel, scrollen Sie zur Abschnitt „OAuth-Einstellungen“ am Ende, erweitern Sie diesen und geben Sie „myclient“ als Client-ID sowie „mysecret“ als Client-Secret ein.
Der MCP Server verlangt nun eine OAuth-Autorisierung. Bisher gilt jedoch das Prinzip: Ein Client, der zur Verbindung autorisiert ist, kann alles nutzen, was der Server bereitstellt.
Schutz einzelner Tools
Die bisher angewandte Sicherheit umfasst den Server als Ganzes. Tools, Ressourcen, Anfragen und weitere Funktionen sind alle hinter einer authentifizierten Verbindung geschützt, doch sobald ein Client diese „Haupteingangstür“ passiert, steht alles zur Verfügung. Falls verschiedene Tools, Anfragen oder Ressourcen unterschiedliche Autorisierungsanforderungen haben, ermöglicht die Methodensicherheit von Spring Security präzisere Regeln.
Die erste Änderung betrifft die Sicherheitskonfiguration des MCP-Servers.
@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();
}
}
Zwei Dinge unterscheiden sich. Die Klasse enthält nun @EnableMethodSecurity, wodurch es möglich ist, Autorisierungsregeln direkt auf Tool-Methoden anzuwenden. Zudem erlaubt authorizeHttpRequests() es nun, Anfragen an den /mcp-Endpunkt bedingungslos durchzulassen, während an anderen Stellen weiterhin eine Authentifizierung erforderlich ist. Die Autorisierung jeder Tool-Aufruf wird anschließend auf Methodenebene durchgesetzt.
Nehmen wir an, der Aufruf von get-weather-for-zipcode sollte den Meteorologie-OAuth-Bereich erfordern. Die @PreAuthorize-Anmerkung drückt das aus.
@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);
}
Die Anmerkung verlangt, dass die aktuelle Autorisierung den meteorologischen Anwendungsbereich umfasst. Spring Security modelliert OAuth-Anwendungsbereiche als mit SCOPE_ vorangestellte, erteilte Befugnisse, was erklärt, warum die Prüfung nach SCOPE_meteorology erfolgt.
Auch die Definition der Tool erhält einige optionale Hinweisattribute, die über das attributes-Attribut bereitgestellt werden und den Clients nützliche Informationen liefern:
- Das Tool ist kein Open-World-Tool. Es ist vollständig selbstständig und ruft keine externen APIs auf. Sollte es umgeschrieben werden, um eine Wetter-API zu verwenden, sollte der Hinweis wahr sein oder einfach weggelassen werden, da er standardmäßig wahr ist.
- Das Tool ändert oder löscht nichts, da es lediglich Wetterdaten abruft, sodass es nicht zerstörerisch ist.
- Durch seine Nichtzerstörerischkeit ist es idempotent. Bei einem zerstörerischen Tool erfordert die Idempotenz besondere Betrachtung, und das idempotentHint-Attribut sollte entsprechend gesetzt werden.
Beobachtung der Funktionsweise der Bereichskontrolle
Starten Sie den MCP-Server erneut, wechseln Sie zurück zum MCP Inspector und öffnen Sie die OAuth-Einstellungen, bevor Sie sich wieder verbinden. Der Button „Gespeicherten OAuth-Zustand löschen“ am unteren Rand entfernt alle aus der vorherigen Autorisierung verbleibenden Token – nutzen Sie ihn daher.
Verbinden Sie sich erneut, melden Sie sich an, kehren Sie zu „get-weather-for-zipcode“ zurück und rufen Sie die Funktion erneut auf. Dieses Mal wird der Aufruf höchstwahrscheinlich fehlschlagen, da der Autorisierungsserver nie um die Gewährung des Meteorologie-Bereichs gebeten wurde; daher reicht allein die Authentifizierung für dieses Tool nicht mehr aus.
Fügen Sie nun „Meteorologie“ zum Feld „Bereiche“ in den OAuth-Einstellungen hinzu, löschen Sie gegebenenfalls den gespeicherten Zustand, verbinden Sie sich erneut und führen Sie das Tool ein weiteres Mal aus. Es sollte erfolgreich sein, da das neu ausgestellte Zugriffstoken den von @PreAuthorize geforderten Meteorologie-Bereich enthält.
Nur einige Ergänzungen zur bereits vorhandenen OAuth-Unterstützung von Spring Security reichten aus, um von einem mit API-Schlüsseln geschützten MCP-Server zu einem überzugehen, der OAuth erfordert, und anschließend zu einer auf den jeweiligen Tools basierenden Berechtigungsvergabe.
Verwandte Artikel
- MCP in einfachen Worten: Eine gemeinsame Schnittstelle zwischen KI-Assistenten und Software — Was das Model Context Protocol ist, wie Clients und Server miteinander verbunden sind, wie Lese-, Schreib- und Erstellungsrechte aussehen und warum die Adoption im Jahr 2026 stark anstieg.