Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Mithilfe eines Client-ID-Metadatendokuments (CIMD) kann Ihr OAuth-Client eine öffentliche HTTPS-URL als seine client_idverwenden. In diesem Artikel wird erläutert, wie Sie ein CIMD-Dokument veröffentlichen und damit ein Token für delegierten Zugriff von Microsoft Entra ID anfordern.
Important
Die Unterstützung von Client-ID-Metadatendokumenten in Microsoft Entra ID befindet sich in der öffentlichen Vorschau. Diese Vorschau wird ohne Vereinbarung auf Serviceebene bereitgestellt und wird für Produktionsworkloads nicht empfohlen. Einige Features werden möglicherweise nicht unterstützt oder verfügen über eingeschränkte Funktionen. Weitere Informationen finden Sie unter "Universelle Lizenzbedingungen für Onlinedienste".
Überprüfen Sie vor der Implementierung von CIMD client-ID-Metadatendokumente in Microsoft Entra ID, um die unterstützten Szenarien, das Sicherheitsmodell und die Einschränkungen zu verstehen.
Voraussetzungen
Für dieses Verfahren benötigen Sie Folgendes:
- Ein OAuth-Client, der den Autorisierungscodefluss und PKCE unterstützt.
- Ein stabiler öffentlicher HTTPS-Endpunkt, unter dem Sie ein JSON-Dokument veröffentlichen können.
- Ein MCP-Server, der mit Microsoft Entra ID gesichert ist. Siehe Vorbereitung des MCP-Servers.
- Ein Microsoft Entra Mandant, in dem CIMD-Unterstützung verfügbar ist.
- Ein Mandantenadministrator, der den CIMD-Client hinzufügen und delegierte Berechtigungen erteilen kann, wenn die Benutzerzustimmung nicht verfügbar ist. Weisen Sie dem Administrator die Dokument-URL, Zielressource und angeforderten Berechtigungsbereiche zu, bevor Sie die Anmeldung testen.
Vorbereiten des MCP-Servers
Ein CIMD-Client lernt alles über den MCP-Server aus den geschützten Ressourcenmetadaten des Servers und von Microsoft Entra ID. Richten Sie den Server gemäß Einen MCP-Server mit Microsoft Entra ID schützen ein. Dieser Artikel befasst sich mit der Registrierung des Servers, dem Verfügbarmachen eines delegierten Bereichs, dem Veröffentlichen geschützter Ressourcenmetadaten und der Überprüfung von Zugriffstoken.
Hosten Sie den MCP-Endpunkt auf einem nicht leeren Pfad ohne nachgestellten Schrägstrich, z. B. https://mcp.contoso.com/mcp. Verwenden Sie nicht den Hoststamm: Einige MCP-Clients hängen einen Schrägstrich an, wodurch der Tokenerwerb fehlschlägt, da der Ressourcenbezeichner nicht mehr übereinstimmt. Microsoft Entra ID akzeptiert keine nachgestellten Schrägstriche für Anwendungs-ID-URIs.
Bestätigen Sie dann die folgenden Einstellungen. In den Beispielen in diesem Artikel wird ein MCP-Server verwendet, der unter https://mcp.contoso.com/mcp den mcp.access-Bereich verfügbar macht.
| Setting | Erforderlicher Wert | Beispiel |
|---|---|---|
| Anwendungs-ID-URI der App-Registrierung des Servers | Die kanonische Endpunkt-URL des Servers mit einem nicht leeren Pfad und ohne nachgestellten Schrägstrich. | https://mcp.contoso.com/mcp |
resource in den Metadaten der geschützten Ressource |
Derselbe Wert wie der Anwendungs-ID-URI. Der Client sendet diesen Wert in seinem resource Parameter. Das v2-Zugriffstoken aud ist die Client-ID-GUID der Ressourcenanwendung. |
https://mcp.contoso.com/mcp |
authorization_servers in den Metadaten der geschützten Ressource |
Die Microsoft Entra Autorisierungsserver-URL für den Mandanten oder organizations für einen mehrinstanzenfähigen Server. |
https://login.microsoftonline.com/{tenant}/oauth21/2026-08 |
scopes_supported in den Metadaten der geschützten Ressource |
Der vollqualifizierte delegierte Scope, den der Client anfordert. | https://mcp.contoso.com/mcp/mcp.access |
Überprüfen Sie, ob der Server seine Metadaten veröffentlicht:
GET https://mcp.contoso.com/.well-known/oauth-protected-resource
Die Antwort muss die Werte resource, authorization_servers und scopes_supported aus der vorherigen Tabelle enthalten.
Metadatendokument veröffentlichen
Veröffentlichen Sie ein JSON-Dokument unter der URL, die Sie als Client-ID verwenden möchten. Beispiele:
GET https://client.contoso.com/oauth/client-metadata.json
Content-Type: application/json
{
"client_id": "https://client.contoso.com/oauth/client-metadata.json",
"client_name": "Contoso Agent",
"client_uri": "https://client.contoso.com",
"logo_uri": "https://client.contoso.com/logo.png",
"redirect_uris": [
"https://client.contoso.com/oauth/callback"
],
"grant_types": [
"authorization_code",
"refresh_token"
],
"response_types": [
"code"
],
"token_endpoint_auth_method": "none"
}
Befolgen Sie diese Anforderungen:
- Verwenden Sie eine HTTPS-URL mit einem nicht leeren Pfad.
- Legen Sie für
client_iddie genaue URL fest, unter der das Dokument bereitgestellt wird. - Halten Sie die URL kurz und stabil. Sie kann in Zustimmungs- und Verwaltungsabläufen angezeigt werden.
- Listen Sie jeden Umleitungs-URI auf, den der Client verwenden kann. Microsoft Entra ID verwendet exakten Zeichenfolgenabgleich.
- Verwenden Sie HTTPS-Umleitungs-URIs. Loopback-Umleitungs-URIs können für lokale native Clientszenarien verwendet werden, in denen die entsprechende OAuth-Spezifikation sie zulässt.
- Verlassen Sie sich nicht auf HTTP-Umleitungen, wenn Microsoft Entra ID das Dokument abruft.
- Gibt einen erfolgreichen HTTP-Statuscode und eine gültige JSON-Antwort zurück.
- Setze
token_endpoint_auth_methodaufnone. Verwenden Sie keinen geheimen Clientschlüssel oder eine Client-Assertion mit privatem Schlüssel während der Vorschau.
Das Dokumentformat wird durch die OAuth-Client-ID-Metadatendokumentspezifikation definiert.
Caution
Behandeln Sie die Dokument-URL und ihre Domäne als dauerhafte Sicherheitsressourcen. Wenn Sie das Dokument in eine andere URL verschieben, behandelt Microsoft Entra ID es als einen anderen Client. Vorhandene Zustimmungserteilungen übertragen nicht.
Überprüfen der Autorisierungsserverunterstützung
Vergewissern Sie sich vor dem Senden einer URL als Client-ID, dass der Autorisierungsserver für den Zielmandanten CIMD unterstützt.
Identifizieren Sie den Autorisierungsserver. Rufen Sie für einen MCP-Server die geschützten Ressourcenmetadaten aus der url ab, die in der
WWW-AuthenticateKopfzeile angekündigt wurde, und lesen Sie denauthorization_serversWert. Im folgenden Beispiel werden Metadaten am Serverursprung getrennt vom/mcpEndpunkt gehostet:GET https://mcp.contoso.com/.well-known/oauth-protected-resource{ "resource": "https://mcp.contoso.com/mcp", "authorization_servers": ["https://login.microsoftonline.com/{tenant}/oauth21/2026-08"] }Verwenden Sie für andere geschützte Ressourcen
https://login.microsoftonline.com/{tenant}/oauth21/2026-08, wobei{tenant}common, die Mandanten-ID oder eine überprüfte Domäne der Organisation ist.Rufen Sie die Autorisierungsservermetadaten ab, indem Sie
/.well-known/openid-configurationan die Autorisierungsserver-URL anfügen:GET https://login.microsoftonline.com/{tenant}/oauth21/2026-08/.well-known/openid-configurationÜberprüfen Sie die Antwort auf die
client_id_metadata_document_supportedEigenschaft. Ein CIMD-fähiger Autorisierungsserver gibt folgendes zurücktrue:{ "client_id_metadata_document_supported": true }
Senden Sie keine CIMD-Client-ID, wenn die Eigenschaft fehlt oder false ist. Verwenden Sie eine registrierte Client-ID oder eine andere Registrierungsmethode, die der Autorisierungsserver unterstützt.
Senden Sie die Autorisierungsanforderung
Setzen Sie client_id auf die URL Ihres Metadatendokuments. Fügen Sie für einen MCP-Server auch die geschützte Ressourcen-URL in den resource Parameter ein.
GET https://login.microsoftonline.com/{tenant}/oauth21/2026-08/authorize
?client_id=https%3A%2F%2Fclient.contoso.com%2Foauth%2Fclient-metadata.json
&response_type=code
&redirect_uri=https%3A%2F%2Fclient.contoso.com%2Foauth%2Fcallback
&scope=offline_access%20https%3A%2F%2Fmcp.contoso.com%2Fmcp%2Fmcp.access
&resource=https%3A%2F%2Fmcp.contoso.com%2Fmcp
&code_challenge={PKCE_challenge}
&code_challenge_method=S256
&state={opaque_value}
Ersetzen Sie:
-
{tenant}mit dem Mandantenbezeichner oder der überprüften Domäne für die Organisation. -
{PKCE_challenge}mit der S256-Challenge, die aus Ihrem Code-Verifier generiert wurde. -
{opaque_value}mit einem Wert, den Ihr Client überprüft, wenn die Autorisierungsantwort zurückgegeben wird. - Gleichen Sie die Ressourcen- und Bereichswerte mit den vom MCP-Server veröffentlichten Werten ab.
Microsoft Entra ID ruft das Metadatendokument ab und überprüft es. Die angeforderte redirect_uri Muss genau mit einem der Werte übereinstimmen in redirect_uris.
Je nach Mandantenrichtlinie und ob ein Administrator den Client im Voraus hinzugefügt hat, kann der Benutzer folgende Aktionen durchführen:
- Fahren Sie ohne eine neue Eingabeaufforderung fort, da ein Administrator bereits die erforderlichen Bereiche für alle Benutzer im Mandanten erteilt hat.
- Stimmen Sie den spezifischen delegierten Berechtigungen zu, die von der Zustimmungsrichtlinie des Mandanten zulässig sind.
- Ihnen wird mitgeteilt, dass die Administratorgenehmigung erforderlich ist.
- Sie werden daran gehindert, den Client hinzuzufügen.
Lösen Sie den Autorisierungscode ein
Nachdem Microsoft Entra ID einen Autorisierungscode zurückgegeben hat, überprüfen Sie den state-Wert und lösen Sie dann den Autorisierungscode bei dem im versionierten Discoverydokument zurückgegebenen token_endpoint ein:
POST https://login.microsoftonline.com/{tenant}/oauth21/2026-08/token
Content-Type: application/x-www-form-urlencoded
client_id=https%3A%2F%2Fclient.contoso.com%2Foauth%2Fclient-metadata.json&
grant_type=authorization_code&
code={authorization_code}&
redirect_uri=https%3A%2F%2Fclient.contoso.com%2Foauth%2Fcallback&
code_verifier={PKCE_code_verifier}&
scope=https%3A%2F%2Fmcp.contoso.com%2Fmcp%2Fmcp.access&
resource=https%3A%2F%2Fmcp.contoso.com%2Fmcp
Häufige Fehler beheben
| Failure | Was soll überprüft werden? |
|---|---|
| Das Metadatendokument kann nicht abgerufen werden. | Vergewissern Sie sich, dass die URL über HTTPS öffentlich erreichbar ist, eine erfolgreiche Antwort direkt zurückgibt und nicht umgeleitet wird. |
| Die Client-ID wird abgelehnt. | Vergewissern Sie sich, dass die angeforderte client_id, die Abruf-URL und die client_id des Dokuments identisch sind. |
| Der Umleitungs-URI wird abgelehnt. | Vergleichen Sie den angeforderten Umleitungs-URI mit den Angaben im Dokument, einschließlich des Schemas, Hosts, Pfads, Ports, der Groß-/Kleinschreibung und des abschließenden Schrägstrichs. |
| Die Tokenbeschaffung schlägt bei einer Ressourcen-URL mit Host-Root oder abschließendem Schrägstrich fehl. | Stellen Sie den MCP-Endpunkt unter einem Pfad wie z. B. /mcp ohne nachgestellten Schrägstrich bereit. Verwenden Sie diese genaue URL für den Anwendungs-ID-URI, Metadaten resourceund OAuth-Parameter resource . |
| Der Benutzer kann den Client nicht genehmigen. | Überprüfen Sie zugewiesene Zustimmungsrichtlinien, risikobasierte Schritt-up-Zustimmung und ob die angeforderten Berechtigungen die Administratorgenehmigung erfordern. Unter der strengen Konfiguration gewährt ein Administrator Berechtigungsbereiche für alle Benutzer. Befolgen Sie unter der lockeren Konfiguration die CIMD-Richtlinie und die risikobasierte Schritt-für-Schritt-Konfiguration im Management-Artikel. |
| CIMD wird nicht ermittelt, oder die URL-Client-ID wird vom Autorisierungsserver abgelehnt. | Verwenden Sie das versionierte /oauth21/2026-08-Discovery-Dokument und die Endpunkte, die es angibt. Stellen Sie sicher, dass client_id_metadata_document_supportedtrue ist. |
| Der MCP-Server gibt HTTP 401 nach dem Tokenerwerb zurück. | Überprüfen Sie die serverseitige Signatur, die Lebensdauer, den Mandanten, den Aussteller und die Zielgruppenüberprüfung. Setzen Sie den versionsgesteuerten Discoverybezeichner nicht mit dem mandantenspezifischen /v2.0 Aussteller des Tokens gleich. |
| Das Token hat die falsche Zielgruppe. | Senden Sie die kanonische URL des MCP-Servers als resource und fordern Sie einen Scope an, den diese Ressource verfügbar macht. |
| Ein Client mit der URL ist bereits vorhanden. | Verwenden Sie die vorhandene mandantenlokale Identität wieder. In einem Mandanten kann nur eine CIMD-gesicherte Identität für eine kanonische URL vorhanden sein. |
| Der Client funktionierte nach einer URL-Änderung nicht mehr. | Stellen Sie die ursprüngliche URL wieder her, oder integrieren Sie die neue URL als neue Identität, und holen Sie die Einwilligung erneut ein. |