Zum Hauptinhalt springen

MCP-Server hinter dem Casdoor MCP-Gateway bereitstellen, End-to-End

Dieses Handbuch führt durch ein vollständiges Beispiel: Ein Unternehmen veröffentlicht einen MCP-Server für seine Mitarbeiter, die ihn von ChatGPT, Claude, Cursor und VS Code aus nutzen. Casdoor fungiert sowohl als Gateway vor dem Server als auch als Autorisierungsserver, der die Benutzer authentifiziert. Der MCP-Server selbst benötigt keinen OAuth 2.0-Code.

Lernziele​

  • Bereiten Sie eine Organisation so vor, dass sich MCP-Clients dort registrieren und anmelden können.
  • Registrieren Sie einen MCP-Server in Casdoor und legen Sie fest, wer ihn nutzen darf und welche Tools verfügbar sind.
  • Verbinden Sie die vier gängigen MCP-Clients.
  • Bedienen Sie mehrere Organisationen von einer einzigen Casdoor-Instanz aus.
  • Überprüfen, prüfen und widerrufen Sie Zugriffe.

Voraussetzungen​

  • Eine Casdoor-Instanz, die über HTTPS vom Internet aus erreichbar ist, beispielsweise https://auth.example.com. ChatGPT- und Claude-custom Connectors rufen sie aus der Cloud auf.
  • Ein MCP-Server, der den Streamable HTTP Transport unterstützt, beispielsweise https://tickets.example.com/mcp, optional geschützt durch ein statisches Bearer Token
  • Globaler Administratorzugriff auf die Casdoor-Admin-Konsole

Das Beispiel​

Acme betreibt einen MCP-Server für sein Ticketsystem. Acme möchte:

  • Mitarbeiter melden sich mit ihrem Acme-Konto an, über die Anmeldeverfahren, die Acme bereits in Casdoor eingerichtet hat.
  • Nur das Support-Team darf den Server nutzen.
  • Niemand darf das Tool delete_ticket über einen KI-Client aufrufen.
  • Der eigene API-Token des Servers verlässt niemals Casdoor.
  • Ein Administrator kann jeden Client sehen und sperren.

Schritt 1: Die Organisation vorbereiten​

  1. Wechseln Sie im Casdoor Admin Console zu User Management > Organizations und öffnen Sie acme.
  2. Aktivieren Sie Use organization issuer. Die Organisation wird zu einem eigenen Autorisierungsserver mit dem Issuer https://auth.example.com/orgs/acme und dem Discovery Document https://auth.example.com/.well-known/oauth-authorization-server/orgs/acme. MCP-Clients, die dies entdecken, registrieren sich in acme und authentifizieren Benutzer auf der Anmeldeseite von acme.
  3. Aktivieren Sie Enable dynamic client registration. Dies ermöglicht Clients, sich über ein Client-ID-Metadaten-Dokument (Claude, VS Code, ChatGPT) zu identifizieren oder sich selbst zu registrieren (Cursor, ältere Clients). Nur ein globaler Administrator kann diesen Schalter ändern.
  4. Speichern Sie die Organisation.

Ohne Use organization issuer gibt das Gateway den globalen Issuer von Casdoor als Autorisierungsserver an, und Clients registrieren sich in built-in. Aktivieren Sie dies für jede Organisation außer built-in, die MCP-Server veröffentlicht.

Schritt 2: Festlegen, wer den Server nutzen darf​

Das Gateway lässt die Benutzer der Organisation des Servers zu, die sich bei der Anwendung des Servers anmelden dürfen.

  1. Wechseln Sie zu Identity > Applications und fügen Sie eine Anwendung in acme hinzu, beispielsweise app-tickets. Es werden keine Redirect URLs benötigt: MCP-Clients melden sich nicht bei ihr an, sie trägt nur die Zugriffsregeln.
  2. Um nur das Support-Team zuzulassen, wechseln Sie zu Authorization > Permissions und fügen Sie eine Berechtigung in acme hinzu:
    • Resource type: Application
    • Resources: app-tickets
    • Groups or Roles: das Support-Team
    • Actions: Read, Effect: Allow

Ohne Berechtigungen für die Anwendung darf jeder Benutzer von acme den Server nutzen. Administratoren von acme und globale Administratoren dürfen ihn immer nutzen.

Schritt 3: Den MCP-Server registrieren​

  1. Gehen Sie zu LLM AI > MCP Servers und fügen Sie einen Server in acme hinzu:

    FeldWert
    Nametickets
    URLhttps://tickets.example.com/mcp
    Applicationapp-tickets
    Access tokenDas API-Token des Ticket-Servers, falls erforderlich

  2. Speichern Sie den Server und wählen Sie dann Sync unter Tool. Casdoor ruft die Tool-Liste des Servers ab.

  3. Blockieren Sie delete_ticket und speichern Sie. Das Gateway antwortet auf einen Aufruf eines blockierten Tools oder eines Tools, das nicht in der Liste enthalten ist, mit einer Fehlermeldung und leitet es nicht weiter.

  4. Kopieren Sie die Base URL: https://auth.example.com/api/server/acme/tickets. Dies ist die URL, die Benutzer zu ihren MCP-Clients hinzufügen.

Das Gateway entfernt den Cookie-Header und den Authorization-Header des Benutzers aus jeder Anfrage und sendet stattdessen das Access token des Servers. Casdoor gibt das Token niemals in seinen API-Antworten zurück.

Notiz

Für einen Server einer Organisation außer built-in muss die URL eine öffentliche Internetadresse sein: Das Gateway verweigert den Zugriff auf private und Loopback-Adressen im Namen eines Mandanten. Um einen MCP-Server in Ihrem internen Netzwerk zu veröffentlichen, registrieren Sie ihn in built-in.

Schritt 4: Die Discovery-Kette überprüfen​

Jeder MCP-Client folgt derselben Kette. Prüfen Sie sie mit curl, bevor Sie einen Client verbinden:

curl -i -X POST https://auth.example.com/api/server/acme/tickets

Casdoor antwortet mit HTTP 401 und nennt die Metadaten der geschützten Ressource dieses Servers:

WWW-Authenticate: Bearer realm="casdoor", resource_metadata="https://auth.example.com/.well-known/oauth-protected-resource/api/server/acme/tickets"
curl https://auth.example.com/.well-known/oauth-protected-resource/api/server/acme/tickets
{
  "resource": "https://auth.example.com/api/server/acme/tickets",
  "authorization_servers": ["https://auth.example.com/orgs/acme"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"]
}
curl https://auth.example.com/.well-known/oauth-authorization-server/orgs/acme

In diesem Dokument prüfen Sie:

  • issuer ist https://auth.example.com/orgs/acme, derselbe Wert wie in authorization_servers.
  • client_id_metadata_document_supported ist true, und registration_endpoint endet mit ?organization=acme.
  • token_endpoint_auth_methods_supported enthält none, und code_challenge_methods_supported enthält S256.

Schritt 5: Die Clients verbinden​

Jeder Benutzer fügt die Gateway-URL seinem Client hinzu und meldet sich mit seinem Acme-Konto an.

ClientWo der Server hinzugefügt wirdWie er sich identifiziertLeitfaden
ChatGPTPlugins > + > Add custom MCP serverCIMD https://chatgpt.com/oauth/client.jsonChatGPT verbinden
Claude Desktop, claude.aiCustomize > Connectors > Add custom connectorCIMD https://claude.ai/oauth/mcp-oauth-client-metadataClaude verbinden
Claude Codeclaude mcp add --transport http tickets <url>CIMD https://claude.ai/oauth/claude-code-client-metadataClaude verbinden
Cursor~/.cursor/mcp.jsonDCRCursor verbinden
VS Code.vscode/mcp.jsonCIMD https://vscode.dev/oauth/client-metadata.jsonVS Code verbinden

Beispielsweise in Cursor:

{
  "mcpServers": {
    "tickets": {
      "url": "https://auth.example.com/api/server/acme/tickets"
    }
  }
}

Und in VS Code:

{
  "servers": {
    "tickets": {
      "type": "http",
      "url": "https://auth.example.com/api/server/acme/tickets"
    }
  }
}

Ein Client, der ein Client-ID-Metadatendokument verwendet, erhält eine Anwendung in Casdoor, mit seiner URL als Client-ID, dem Tag cimd und einem Namen, der mit cimd_ beginnt. Ein Client, der sich selbst registriert, erhält eine Anwendung pro Registrierung, mit dem Tag dcr. Sie erstellen keine Anwendungen für die Clients.

Was den Server schützt​

PrüfungWoWas passiert sonst
Das Token gehört zu einem Benutzer von acmeGatewayHTTP 401
Der Benutzer darf sich bei app-tickets anmeldenGatewayHTTP 401
Das Token wurde für diesen Server ausgestellt (RFC 8707)GatewayHTTP 401: "The access token is for another resource"
Das Tool ist in der Liste und erlaubtGatewayJSON-RPC-Fehler, der Aufruf wird nicht weitergeleitet
Der Client ist ein selbst registrierter ClientJede APISeine Tokens können nur den Anmeldeablauf, /api/userinfo, /api/mcp und /api/server/* aufrufen, niemals die Management-APIs

Clients fordern das Token mit resource=https://auth.example.com/api/server/acme/tickets an, und Casdoor setzt diese URL in die aud-Claim. Ein Token für einen anderen MCP-Server, auch wenn er zur selben Organisation gehört, funktioniert hier nicht, so dass ein bösartiger Server die empfangenen Tokens nicht wiederverwenden kann.

Mehrere Organisationen bedienen​

Eine Casdoor-Instanz kann MCP-Server für viele Organisationen veröffentlichen, z. B. für die Kunden eines SaaS-Anbieters. Wiederholen Sie die Schritte 1 bis 3 für jede Organisation. Dann:

  • Jede Organisation hat ihren eigenen Issuer, ihre eigene Anmeldeseite, Benutzer und Berechtigungen. Ein Benutzer von globex kann sich nicht auf der Seite von acme anmelden und die Server von acme nicht nutzen.
  • Die Metadaten-Dokumente der Client-IDs von ChatGPT, Claude und VS Code haben jeweils eine URL, die von allen Organisationen genutzt wird. Casdoor verwaltet pro URL eine gemeinsame Anwendung in built-in und stellt sie als Anwendung der Organisation bereit, bei der sich der Benutzer anmeldet. Jede Organisation muss dennoch Enable dynamic client registration aktivieren, um diese Clients zu akzeptieren.
  • Tokens enthalten den Issuer der Organisation des Benutzers, auch nach einer Aktualisierung (Refresh).
  • Ein selbst registrierter Client (DCR) registriert sich in der Organisation des Discovery-Dokuments über den Parameter organization des Registrierungsendpunkts.

Überprüfen, prüfen und widerrufen​

  • Clients: Unter Identity > Applications werden Clients mit den Tags cimd und dcr aufgelistet. Löschen Sie eine dcr_-Anwendung, um eine Registrierung zu entfernen.
  • Tokens: Unter Auditing > Tokens wird jedes Token mit seinem Benutzer, seiner Anwendung, dem Scope und der Ressource aufgelistet. Löschen Sie ein Token, um einen Client sofort zu sperren.
  • Users: Sperren Sie einen Benutzer, und seine Tokens funktionieren am Gateway ab der nächsten Anfrage nicht mehr.
  • Tools: Blockieren Sie ein Tool auf der Bearbeitungsseite des Servers. Die Änderung tritt beim nächsten Aufruf in Kraft.

Unternehmensbenutzern das Überspringen des Browsers ermöglichen​

Wenn sich die Mitarbeiter einer Organisation über einen Enterprise-Identitätsanbieter wie Okta anmelden, können Clients, die Enterprise-Managed Authorization unterstützen (Claude Team und Enterprise), das Gateway-Token ohne Browser-Anmeldung erhalten: Der Identitätsanbieter stellt ein ID-JAG aus, und Casdoor tauscht es gegen ein Access Token. Siehe Enterprise-managed authorization.

Fehlerbehebung​

Das Gateway antwortet nach der Anmeldung mit 401​

  • Der Server hat keine Application. Ohne eine solche dürfen nur Administratoren den Server nutzen. Wählen Sie eine Anwendung aus, siehe Schritt 2.
  • Eine Berechtigung auf der Anwendung schließt den Benutzer aus.
  • Der Benutzer gehört einer anderen Organisation an als der Server.
  • Der Client hat das Token für eine andere Ressource angefordert. Überprüfen Sie den aud-Claim des Tokens: Es muss die Gateway-URL sein.

Der Client meldet Benutzer in der falschen Organisation an​

Use organization issuer ist deaktiviert, sodass die Metadaten der geschützten Ressource den globalen Issuer nennen. Aktivieren Sie dies und verbinden Sie den Client erneut.

"client ID metadata documents are not accepted"​

Enable dynamic client registration ist für die Organisation deaktiviert. Casdoor muss zudem über das Internet auf die Dokument-URL des Clients zugreifen können.

Das Gateway antwortet mit 502​

Casdoor kann die URL des Servers nicht erreichen. Überprüfen Sie die URL und stellen Sie sicher, dass sie für Organisationen außer built-in eine öffentliche Adresse ist.

Siehe auch​