Microsoft Identity Platform – Zugriffstoken

Artikel
04/10/2024

Zugriffstoken ermöglichen Clients das sichere Aufrufen von geschützten Web-APIs. Web-APIs verwenden Zugriffstoken zur Authentifizierung und Autorisierung.

Gemäß der OAuth-Spezifikation sind Zugriffstoken nicht transparente Zeichenfolgen ohne ein bestimmtes Format. Einige Identitätsanbieter (IDPs) verwenden GUIDs und andere verschlüsselte Blobs. Das Format des Zugriffstokens kann davon abhängen, wie die API konfiguriert ist, die es akzeptiert.

Für benutzerdefinierte APIs, die von Entwicklern auf Microsoft Identity Platform registriert wurden, stehen zwei unterschiedliche JWT-Formate (JSON Web Token) mit der Bezeichnung v1.0 und v2.0 zur Auswahl. Von Microsoft Graph entwickelte APIs (z. B. Microsoft Graph) oder APIs in Azure weisen andere proprietäre Tokenformate auf. Bei diesen proprietären Formaten, die nicht überprüft werden können, kann es sich um verschlüsselte Token, JWTs oder spezielle JWT-ähnliche Token handeln.

Der Inhalt des Tokens ist nur für die API vorgesehen, was bedeutet, dass Zugriffstoken als nicht transparente Zeichenfolgen behandelt werden müssen. Ausschließlich zu Prüfungs- und Debugzwecken können Entwickler JWTs mit einer Website wie jwt.ms decodieren. Token, die eine Microsoft API empfängt, sind nicht notwendigerweise immer ein JWT, das dekodiert werden kann.

Ausführliche Informationen zum Inhalt des Zugriffstokens können Clients über die Tokenantwortdaten erhalten, die mit dem Zugriffstoken an den Client zurückgegeben werden. Wenn der Client ein Zugriffstoken anfordert, gibt Microsoft Identity Platform auch einige Metadaten zum Zugriffstoken zurück, die von der Anwendung genutzt werden können. Diese Informationen umfassen die Ablaufzeit eines Zugriffstokens und die Bereiche, für die es gilt. Die Daten ermöglichen der Anwendung das intelligente Zwischenspeichern von Zugriffstoken, ohne das Zugriffstoken selbst analysieren zu müssen.

In den folgenden Abschnitten erfahren Sie, wie eine API die Ansprüche in einem Zugriffstoken überprüfen und verwenden kann.

Hinweis

Die gesamte Dokumentation auf dieser Seite gilt, sofern nichts Gegenteiliges erwähnt ist, nur für Token, die für registrierte APIs ausgegeben werden. Sie gilt weder für Token, die für Microsoft-eigene APIs ausgegeben werden, noch kann anhand dieser Token überprüft werden, wie Microsoft Identity Platform Token für eine registrierte API ausgibt.

Tokenformate

Es gibt zwei Versionen von Zugriffstoken, die in Microsoft Identity Platform verfügbar sind: v1.0 und v2.0. Diese Versionen bestimmen die Ansprüche, die sich im Token befinden, und stellen sicher, dass eine Web-API den Inhalt des Tokens steuern kann.

Web-APIs weisen eine der folgenden Versionen auf, die während der Registrierung als Standard ausgewählt sind:

v1.0 für reine Microsoft Entra Anwendungen. Das folgende Beispiel zeigt ein v1.0-Token (die Schlüssel werden geändert und persönliche Informationen werden entfernt, was die Tokenüberprüfung verhindert):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

v2.0 für Anwendungen, die Consumerkonten unterstützen. Das folgende Beispiel zeigt ein v2.0-Token (die Schlüssel werden geändert und persönliche Informationen werden entfernt, was die Tokenüberprüfung verhindert):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Legen Sie die Version kann für Anwendungen fest, indem der entsprechende Wert für die accessTokenAcceptedVersion-Einstellung im App-Manifest angegeben wird. Aus den Werten von null und 1 ergibt sich ein v1.0-Token und aus dem Wert von 2 ein v2.0-Token.

Tokenbesitz

An einer Zugriffstokenanforderung sind zwei Parteien beteiligt: der Client, der das Token anfordert, und die Ressource (Web-API), die das Token akzeptiert. Die Ressource, für die das Token bestimmt ist (die Zielgruppe), wird im Anspruch aud in einem Token definiert. Clients verwenden das Token, sollten es jedoch weder verstehen noch analysieren können. Ressourcen akzeptieren das Token.

Microsoft Identity Platform unterstützt das Ausstellen beliebiger Tokenversionen über einen beliebigen Versionsendpunkt. Wenn der Wert von accessTokenAcceptedVersion beispielsweise 2 ist, erhält ein Client, der den v1.0-Endpunkt zum Abrufen eines Tokens für diese API aufruft, ein v2.0-Zugriffstoken.

Ressourcen sind immer Besitzer ihrer Token (mit dem Anspruch aud) und können als einzige Anwendungen die Tokendetails ändern.

Lebensdauer von Token

Die Standardlebensdauer eines Zugriffstokens ist variabel. Bei der Ausstellung weist due Microsoft Identitätsplattform einen zufälligen Wert zwischen 60 und 90 Minuten (durchschnittlich 75 Minuten) als Standardlebensdauer eines Zugriffstokens zu. Die Variation verbessert die Dienstresilienz, indem der Bedarf an Zugriffstoken über einen bestimmten Zeitraum verteilt wird. Dadurch werden stündliche Spitzen im Datenverkehr an Microsoft Entra ID verhindert.

Mandanten, die den bedingten Zugriff nicht verwenden, verfügen für Zugriffstoken für Clients wie Microsoft Teams und Microsoft 365 über eine Standardgültigkeitsdauer von zwei Stunden.

Passen Sie die Gültigkeitsdauer eines Zugrifftokens an, um zu steuern, wie oft die Clientanwendung den Ablauf der Anwendungssitzung veranlasst, und wie oft sich der Benutzer erneut authentifizieren werden muss (entweder im Hintergrund oder interaktiv). Um die Variation der Standardlebensdauer eines Zugriffstokens zu überschreiben, verwenden Sie Konfigurierbare Tokenlebensdauer (CTL).

Wenden Sie die Variation der Standardlebensdauer für Token auf Organisationen an, für die fortlaufende Zugriffsevaluierung (Continuous Access Evaluation, CAE) aktiviert ist. Wenden Sie die Standardlebensdauer für Token auch dann an, wenn die Organisationen CTL-Richtlinien verwenden. Die Standardgültigkeitsdauer für Token reicht bei langer Tokengültigkeitsdauer von 20 bis 28 Stunden. Wenn das Zugriffstoken abläuft, muss der Client das Aktualisierungstoken verwenden, um ein neues Aktualisierungstoken und Zugriffstoken abzurufen.

Organisationen, die mithilfe von Anmeldehäufigkeit (Sign-In Frequency, SIF) des bedingten Zugriffs erzwingen, wie häufig Anmeldungen erfolgen, können die Variation der Standardgültigkeitsdauer von Zugriffstoken nicht überschreiben. Wenn Organisationen SIF verwenden, entspricht die Zeit zwischen Anmeldeaufforderungen für einen Client der Tokengültigkeitsdauer (60 bis 90 Minuten) plus dem Intervall für die Anmeldehäufigkeit.

Im folgenden Beispiel sehen Sie, wie die Variation der Standardgültigkeitsdauer für Token mit Anmeldehäufigkeit funktioniert: Angenommen, eine Organisation legt eine Anmeldehäufigkeit von einer Stunde fest. Wenn das Token aufgrund der Variation der Tokenlebensdauer eine Gültigkeitsdauer von 60 bis 90 Minuten hat, liegt das tatsächliche Anmeldeintervall zwischen 1 Stunde und 2,5 Stunden.

Wenn ein Benutzer mit einem Token mit einer Gültigkeitsdauer von einer Stunde eine interaktive Anmeldung bei 59 Minuten durchführt, wird keine Eingabeaufforderung für Anmeldeinformationen angezeigt, da die Anmeldung unter dem SIF-Schwellenwert liegt. Wenn ein neues Token eine Lebensdauer von 90 Minuten hat, wird dem Benutzer weitere 1,5 Stunden lang keine Eingabeaufforderung für Anmeldeinformationen angezeigt. Während des Versuchs einer automatischen Verlängerung erfordert Microsoft Entra ID eine Eingabeaufforderung für Anmeldeinformationen, da die Gesamtsitzungslänge die Einstellung für die Anmeldehäufigkeit von 1 Stunde überschritten hat. In diesem Beispiel beträgt der Zeitunterschied zwischen Eingabeaufforderungen für Anmeldeinformationen aufgrund des SIF-Intervalls und der Variation der Tokengültigkeitsdauer 2,5 Stunden.

Überprüfen von Token

Nicht alle Anwendungen sollten Token überprüfen. Die Überprüfung eines Tokens durch Anwendungen sollte nur in bestimmten Szenarien erfolgen:

Web-APIs müssen Zugriffstoken überprüfen, die von einem Client an sie gesendet werden. Sie dürfen nur Token akzeptieren, die eine ihrer AppId-URIs als den aud-Anspruch enthalten.
Web-Apps müssen ID-Token überprüfen, die über den Browser des Benutzers im Hybridflow an sie gesendet werden, bevor sie den Zugriff auf die Daten eines Benutzers erlauben oder eine Sitzung einrichten.

Wenn keines der zuvor beschriebenen Szenarios zutrifft, ist es nicht erforderlich, das Token zu überprüfen. Öffentliche Clients wie native, Desktop- oder Single-Page-Webanwendungen profitieren nicht von der Überprüfung von ID-Tokens, da die Anwendung direkt mit dem Identitätsanbieter kommuniziert, wobei der SSL-Schutz sicherstellt, dass die ID-Token gültig sind. Sie sollten die Zugriffstoken nicht überprüfen, da sie durch die Web-API und nicht durch den Client überprüft werden müssen.

APIs und Webanwendungen dürfen nur Token mit einem aud-Anspruch überprüfen, der mit der Anwendung übereinstimmt. Für andere Ressourcen gibt es möglicherweise benutzerdefinierte Tokenüberprüfungsregeln. So können Sie beispielsweise Token für Microsoft Graph aufgrund ihres proprietären Formats nicht anhand dieser Regeln überprüfen. Das Überprüfen und Akzeptieren von Token, die für eine andere Ressource bestimmt sind, ist ein Beispiel für das sogenannte verwirrte Stellvertreterproblem (confused deputy problem).

Wenn die Anwendung ein ID-Token oder Zugriffstoken überprüfen muss, sollte sie zunächst die Signatur und den Aussteller des Tokens anhand der Werte im OpenID Discovery-Dokument überprüfen.

Microsoft Entra-Middleware verfügt über integrierte Funktionen zum Überprüfen von Zugriffstoken. Unter Beispiele finden Sie eine Funktion in der gewünschten Programmiersprache. Für die JWT-Überprüfung sind auch einige Drittanbieter-Open-Source-Bibliotheken verfügbar. Weitere Informationen zu Authentifizierungsbibliotheken sowie Codebeispiele finden Sie unter Authentifizierungsbibliotheken. Wenn sich Ihre Web-App oder Web-API auf ASP.NET oder ASP.NET Core befindet, verwenden Sie das Microsoft.Identity.Web-Paket, das die Überprüfung für Sie übernimmt.

v1.0- und v2.0-Token

Wenn Ihre Web-App/API ein v1.0-Token (ver-Anspruch =„1.0“) überprüft, muss sie das OpenID Connect-Metadatendokument vom v1.0-Endpunkt (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration) lesen, auch wenn die für Ihre Web-API konfigurierte Autorität eine v2.0-Autorität ist.
Wenn Ihre Web-App/API ein v2.0-Token (ver-Anspruch =„2.0“) überprüft, muss sie das OpenID Connect-Metadatendokument vom v2.0-Endpunkt (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration) lesen, auch wenn die für Ihre Web-API konfigurierte Autorität eine v1.0-Autorität ist.

In den folgenden Beispielen wird angenommen, dass Ihre Anwendung ein v2.0-Zugriffstoken überprüft (und daher auf die v2.0-Versionen der OIDC-Metadatendokumente und -schlüssel verweisen). Entfernen Sie einfach „/v2.0“ in der URL, wenn Sie v1.0-Token überprüfen.

Überprüfen des Ausstellers

OpenID Connect Core sagt „Der Bezeichner des Zertifikatausstellers [...] MUSS genau mit dem Wert für „Iss“ (Zertifikataussteller) „Claim“ übereinstimmen.“ Für Anwendungen, die einen mandantenspezifischen Metadatenendpunkt verwenden (z. B. https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration oder https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), ist dies alles erforderlich.

Microsoft Entra ID stellt unter https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration eine mandantenunabhängige Version des Dokuments zur Verfügung. Dieser Endpunkt gibt einen Ausstellerwert https://login.microsoftonline.com/{tenantid}/v2.0 zurück. Anwendungen können diesen mandantenunabhängigen Endpunkt verwenden, um Token von jedem Mandanten mit den folgenden Änderungen zu überprüfen:

Anstatt zu erwarten, dass der Ausstelleranspruch im Token genau mit dem Ausstellerwert aus den Metadaten übereinstimmt, sollte die Anwendung den {tenantid}-Wert in den Ausstellermetadaten durch die Mandanten-ID (tenantid) ersetzen, die das Ziel der aktuellen Anforderung darstellt, und dann die genaue Übereinstimmung überprüfen.

Die Anwendung sollte die vom Endpunkt des Schlüssels zurückgegebene Eigenschaft issuer verwenden, um den Umfang der Schlüssel einzuschränken.

Schlüssel, die einen Ausstellerwert wie https://login.microsoftonline.com/{tenantid}/v2.0 aufweisen, können mit jedem passenden Tokenaussteller verwendet werden.
Schlüssel, die einen Ausstellerwert wie https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 besitzen, sollten nur mit exakter Übereinstimmung verwendet werden.

Der mandantenunabhängige Schlüsselendpunkt von Microsoft Entra (https://login.microsoftonline.com/common/discovery/v2.0/keys) gibt ein Dokument wie das folgende zurück:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Anwendungen, die den Mandanten-ID-Anspruch (tid) von Microsoft Entra anstelle des Standardausstelleranspruchs als Vertrauensstellungsgrenze verwenden, sollten sicherstellen, dass der Mandanten-ID-Anspruch eine GUID ist und dass Aussteller und Mandanten-ID übereinstimmen.

Die Verwendung von mandantenunabhängigen Metadaten ist effizienter für Anwendungen, die Token von vielen Mandanten akzeptieren.

Hinweis

Bei mandantenunabhängigen Microsoft Entra-Metadaten sollten Ansprüche innerhalb des Mandanten interpretiert werden, so wie bei OpenID Connect-Standardinstanzen Ansprüche innerhalb des Ausstellers interpretiert werden. Das bedeutet, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} und {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} beschreiben unterschiedliche Benutzer, auch wenn sub derselbe ist, da Ansprüche wie sub im Kontext des Ausstellers/Mandanten interpretiert werden.

Überprüfen der Signatur

Ein JWT enthält drei Segmente, die durch das Zeichen . getrennt sind. Das erste Segment ist der Header, das zweite der Text und das dritte die Signatur. Verwenden Sie das Signatursegment, um die Authentizität des Tokens auszuwerten.

Microsoft Entra ID stellt Token aus, die mit asymmetrischen Verschlüsselungsalgorithmen nach Branchenstandard (z. B. RS256) signiert werden. Der Header des JWT enthält Informationen zum Schlüssel und zur Verschlüsselungsmethode, die zum Signieren des Tokens verwendet werden:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

Der alg-Anspruch gibt den Algorithmus an, mit dem das Token signiert wurde, und der kid-Anspruch gibt den bestimmten öffentlichen Schlüssel an, mit dem das Token überprüft wurde.

Zu einem beliebigen Zeitpunkt signiert Microsoft Entra ID unter Umständen ein ID-Token mithilfe eines bestimmten Satzes von Paaren öffentlicher und privater Schlüssel. Microsoft Entra ID rotiert die möglichen Sätze von Schlüsseln regelmäßig. Legen Sie Anwendung also auf die automatische Verarbeitung dieser Schlüsseländerungen aus. Die von Microsoft Entra ID verwendeten öffentlichen Schlüssel sollten alle 24 Stunden auf Änderungen überprüft werden.

Rufen Sie die Signaturschlüsseldaten, die zum Überprüfen der Signatur erforderlich sind, mithilfe des OpenID Connect-Metadatendokuments ab. Dieses Dokument befindet sich unter:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Tipp

Probieren Sie dies in einem Browser aus: URL

Die folgenden Informationen beschreiben das Metadatendokument:

Ist ein JSON-Objekt, das zahlreiche nützliche Informationen enthält, beispielsweise den Speicherort der verschiedenen Endpunkte, die zum Ausführen der OpenID Connect-Authentifizierung erforderlich sind.
Enthält einen jwks_uri, der den Speicherort des Satzes öffentlicher Schlüssel angibt, welcher den privaten Schlüsseln entspricht, mit dem Token signiert werden. Der JSON-Webschlüssel (JWK) unter jwks_uri enthält alle Informationen zu den zu diesem Zeitpunkt verwendeten öffentlichen Schlüsseln. RFC 7517 beschreibt das JWK-Format. Die Anwendung kann den Anspruch kid im JWT-Header verwenden, um den öffentlichen Schlüssel in diesem Dokument auszuwählen, der dem privaten Schlüssel entspricht, mit dem ein bestimmtes Token signiert wurde. Sie kann anschließend die Signaturüberprüfung mithilfe des korrekten öffentlichen Schlüssels und des angegebenen Algorithmus ausführen.

Hinweis

Verwenden Sie den Anspruch kid, um das Token zu überprüfen. Während v1.0-Token sowohl den Anspruch x5t als auch den Anspruch kid enthalten, können v2.0-Token nur den Anspruch kid enthalten.

Die Signaturüberprüfung geht über den Rahmen dieses Dokuments hinaus. Bei Bedarf stehen viele Open-Source-Bibliotheken zur Verfügung, um die Signaturüberprüfung zu unterstützen. Microsoft Identity Platform bietet jedoch eine Tokensignaturerweiterung für die Standards: benutzerdefinierte Signaturschlüssel.

Wenn die Anwendung aufgrund der Verwendung der claims-mapping-Funktion über benutzerdefinierte Signaturschlüssel verfügt, fügen Sie einen appid-Abfrageparameter an, der die Anwendungs-ID enthält. Verwenden Sie zur Überprüfung jwks_uri, das auf die Signaturschlüsselinformationen der Anwendung verweist. Beispiel: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 enthält einen jwks_uri von https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

Überprüfen des Ausstellers

Web-Apps, die ID-Token überprüfen, und Web-APIs, die Zugriffstoken überprüfen, müssen den Aussteller des Tokens (iss-Anspruch) überprüfen gegen:

den Aussteller, der im OpenID Connect-Metadatendokument verfügbar ist, das der Anwendungskonfiguration (Autorität) zugeordnet ist. Das Metadatendokument, gegen das überprüft wird, hängt von Folgendem ab:
- der Version des Tokens
- den von Ihrer Anwendung unterstützten Konten.
der Mandanten-ID (tid-Anspruch) des Tokens,
dem Aussteller des Signaturschlüssels.

Einzelmandantenanwendungen

OpenID Connect Core sagt „Der Bezeichner des Zertifikatausstellers [...] MUSS genau mit dem Wert für „iss“ (Zertifikataussteller) „Claim“ übereinstimmen.“ Für Anwendungen, die einen mandantenspezifischen Metadatenendpunkt verwenden, z. B. https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration oder https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Einzelmandantenanwendungen sind Anwendungen, die Folgendes unterstützen:

Konten in einem Organisationsverzeichnis (nur example-tenant-id): https://login.microsoftonline.com/{example-tenant-id}
Nur persönliche Microsoft-Konten: https://login.microsoftonline.com/consumers (Consumers ist ein Spitzname für den Mandanten 9188040d-6c67-4c5b-b112-36a304b66dad)

Mehrinstanzenfähige Anwendungen

Microsoft Entra ID unterstützt auch mandantenfähige Anwendungen. Diese Anwendungen unterstützen Folgendes:

Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra-Verzeichnis): https://login.microsoftonline.com/organizations
Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra-Verzeichnis) und persönliche Microsoft-Konten (z. B. Skype, Xbox): https://login.microsoftonline.com/common

Für diese Anwendungen macht Microsoft Entra ID mandantenunabhängige Versionen des OIDC-Dokuments unter https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration bzw. https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration verfügbar. Diese Endpunkte geben einen Ausstellerwert zurück, bei dem es sich um eine Vorlage handelt, die von der tenantid parametrisiert wurde: https://login.microsoftonline.com/{tenantid}/v2.0. Anwendungen können diese mandantenunabhängigen Endpunkte verwenden, um Token jedes Mandanten mit den folgenden Bedingungen zu überprüfen:

Überprüfen des Signaturschlüsselausstellers
Anstatt zu erwarten, dass der Ausstelleranspruch im Token genau mit dem Ausstellerwert aus den Metadaten übereinstimmt, sollte die Anwendung den {tenantid}-Wert in den Ausstellermetadaten durch die Mandanten-ID ersetzen, die das Ziel der aktuellen Anforderung darstellt, und dann die genaue Übereinstimmung überprüfen (tid-Anspruch des Tokens).
Überprüfen, ob der tid-Anspruch eine GUID ist, und ob der iss-Anspruch das Format https://login.microsoftonline.com/{tid}/v2.0 hat, wobei {tid} der genaue tid-Anspruch ist. Durch diese Überprüfung wird der Mandant wieder mit dem Aussteller und mit dem Bereich des Signaturschlüssels verknüpft, wodurch eine Vertrauenskette erstellt wird.
Verwenden des tid-Anspruchs bei der Suche nach Daten, die mit dem Subjekt des Anspruchs verbunden sind. Mit anderen Worten muss der tid-Anspruch Teil des Schlüssels sein, der für den Zugriff auf die Daten des Benutzers verwendet wird.

Überprüfen des Signaturschlüsselausstellers

Anwendungen, welche die mandantenunabhängigen Metadaten der Version 2.0 verwenden, müssen den Signaturschlüsselaussteller überprüfen.

Schlüsseldokument und Signaturschlüsselaussteller

Wie bereits erläutert, greift Ihre Anwendung aus dem OpenID Connect-Dokument auf die Schlüssel zu, die zum Signieren der Token verwendet werden. Sie ruft das entsprechende Schlüsseldokument ab, indem auf die URL zugegriffen wird, die in der jwks_uri-Eigenschaft des OpenId Connect-Dokuments verfügbar gemacht wird.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

Der Wert {example-tenant-id} kann durch eine GUID, einen Domänennamen oder gemeinsam, Organisationen und Consumers ersetzt werden

Die von Azure AD v2.0 verfügbar gemachten keys-Dokumente enthalten für jeden Schlüssel den Aussteller, der diesen Signaturschlüssel verwendet. Der mandantenunabhängige „gemeinsame“ Schlüsselendpunkt https://login.microsoftonline.com/common/discovery/v2.0/keys gibt beispielsweise ein Dokument wie dieses zurück:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Validierung des Signaturschlüsselausstellers

Die Anwendung sollte die issuer-Eigenschaft des Schlüsseldokuments verwenden, die dem Schlüssel zugeordnet ist, der zum Signieren des Tokens verwendet wird, um den Bereich der Schlüssel einzuschränken:

Schlüssel, die über einen Ausstellerwert mit einer GUID wie https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 verfügen, sollten nur verwendet werden, wenn der iss-Anspruch im Token genau mit dem Wert übereinstimmt.
Schlüssel, die über einen vorlagenbasierten Ausstellerwert wie https://login.microsoftonline.com/{tenantid}/v2.0 verfügen, sollten nur verwendet werden, wenn der iss Anspruch im Token mit diesem Wert übereinstimmt, nachdem der tid-Anspruch im Token durch den {tenantid}-Platzhalter ersetzt wurde.

Die Verwendung von mandantenunabhängigen Metadaten ist effizienter für Anwendungen, die Token von vielen Mandanten akzeptieren.

Hinweis

Bei mandantenunabhängigen Microsoft Entra-Metadaten sollten Ansprüche innerhalb des Mandanten interpretiert werden, so wie bei OpenID Connect-Standardinstanzen Ansprüche innerhalb des Ausstellers interpretiert werden. Das bedeutet, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} und {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} beschreiben unterschiedliche Benutzer, auch wenn sub derselbe ist, da Ansprüche wie sub im Kontext des Ausstellers/Mandanten interpretiert werden.

Zusammenfassung

Der folgende Pseudocode rekapituliert die Überprüfung des Ausstellers und des Signaturschlüsselausstellers:

Abrufen von Schlüsseln aus der konfigurierter Metadaten-URL
Token überprüfen, ob er mit einem der veröffentlichten Schlüssel signiert ist, schlägt fehl, wenn nicht

Identifizieren Sie den Schlüssel in den Metadaten basierend auf dem KID-Header. Überprüfen Sie die Eigenschaft „Aussteller“, die dem Schlüssel im Metadatendokument angefügt ist:

var issuer = metadata["kid"].issuer;
if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
if (issuer != token["iss"]) throw validationException;
if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
var issUri = new Uri(token["iss"]);
if (issUri.Segments.Count < 1) throw validationException;
if (issUri.Segments[1] != token["tid"]) throw validationException;

Siehe auch

Nächste Schritte

Erfahren Sie mehr über Sicherheitstoken, die in Microsoft Entra ID verwendet werden.

Teilen über

Microsoft Identity Platform – Zugriffstoken

Tokenformate

Tokenbesitz

Lebensdauer von Token

Überprüfen von Token

v1.0- und v2.0-Token

Überprüfen des Ausstellers

Überprüfen der Signatur

Überprüfen des Ausstellers

Einzelmandantenanwendungen

Mehrinstanzenfähige Anwendungen

Überprüfen des Signaturschlüsselausstellers

Schlüsseldokument und Signaturschlüsselaussteller

Validierung des Signaturschlüsselausstellers

Zusammenfassung

Siehe auch

Nächste Schritte

Feedback

Zusätzliche Ressourcen