Zugriffstoken in der Microsoft Identity Platform

Zugriffstoken sind eine Art von Sicherheitstoken, das für die Autorisierung entwickelt wurde und den Zugriff auf bestimmte Ressourcen im Auftrag eines authentifizierten Benutzers gewährt. Informationen in Zugriffstoken bestimmen, ob ein Benutzer das Recht hat, auf eine bestimmte Ressource zuzugreifen, ähnlich wie Schlüssel, die bestimmte Türen in einem Gebäude entsperren. Diese einzelnen Informationen, aus denen Token bestehen, werden Ansprüche genannt. Daher sind sie vertrauliche Anmeldeinformationen und stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß behandelt werden. Zugriffstoken unterscheiden sich von ID-Token, die als Authentifizierungsnachweis dienen.

Zugriffstoken ermöglichen Clients das sichere Aufrufen von geschützten Web-APIs. Obwohl Clientanwendungen Zugriffstoken empfangen und verwenden können, sollten sie sie als undurchsichtige Zeichenfolgen behandeln. Die Clientanwendung sollte nicht versuchen, Zugriffstoken zu überprüfen. Der Ressourcenserver sollte das Zugriffstoken überprüfen, bevor es als Autorisierungsnachweis akzeptiert wird. 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 diesem Artikel werden wichtige Informationen zu Zugriffstoken erläutert, einschließlich Format, Besitz, Lebensdauer und wie APIs die Ansprüche innerhalb eines Zugriffstokens überprüfen und verwenden können.

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 für Anwendungen fest, indem Sie den entsprechenden Wert für die Einstellung requestedAccessTokenVersion im app manifest angeben. Aus den Werten von null und 1 ergibt sich ein v1.0-Token und aus dem Wert von 2 ein v2.0-Token.

Token-Besitz

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 requestedAccessTokenVersion 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 mithilfe des Anspruchs aud immer Inhaber ihrer Token und die einzigen Anwendungen, die die Details ihrer Token ändern können.

Token-Lebensdauer

Die Standardlebensdauer eines Zugriffstokens ist variabel. Bei der Ausstellung eines Zugriffstokens weist die Microsoft-Identitätsplattform als Standardlebensdauer einen zufälligen Wert zwischen 60 und 90 Minuten zu (durchschnittlich 75 Minuten). 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 Zugriffstokens an, um zu steuern, wie oft die Anwendungssitzung in der Clientanwendung abläuft und wie oft der Benutzer sich erneut authentifizieren 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 standardmäßige Gültigkeitsdauer für langlebige Tokens beträgt 20 bis 28 Stunden. Wenn das Zugriffstoken abläuft, muss der Client das Aktualisierungstoken verwenden, um im Hintergrund ein neues Aktualisierungstoken und ein neues Zugriffstoken abzurufen.

Organisationen, die mithilfe von Anmeldehäufigkeit (Sign-In Frequency, SIF) für bedingten Zugriff erzwingen, wie oft Anmeldungen erfolgen, können die standardmäßige Variabilität der Zugriffstokenlebensdauer nicht außer Kraft setzen. Wenn Organisationen SIF verwenden, kann die Zeit zwischen Anmeldeinformationenaufforderungen für einen Client vom Intervall der Anmeldehäufigkeit bis zur Lebensdauer des Tokens reichen, wobei Letztere zwischen 60 und 90 Minuten liegt, zusätzlich zu dem Intervall der Anmeldehäufigkeit.

Hier ist ein Beispiel dafür, wie die standardmäßige Variation der Tokengültigkeitsdauer mit der 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 eines Versuchs der stillen Erneuerung fordert Microsoft Entra ID zur Eingabe von Anmeldeinformationen auf, da die gesamte Sitzungsdauer die Einstellung für die Anmeldehäufigkeit von 1 Stunde überschritten hat. In diesem Beispiel beträgt der Zeitunterschied zwischen Aufforderungen zur Eingabe von Anmeldeinformationen aufgrund des SIF-Intervalls und der Abweichung bei 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 systemeigene, Desktop- oder Einzelseitenanwendungen profitieren nicht von der Überprüfung von ID-Token, da die Anwendung direkt mit dem IDP kommuniziert, bei dem 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.

Die Microsoft Entra Middleware verfügt über integrierte Funktionen zum Überprüfen von Zugriffstoken. Siehe Beispiele, um eines in der passenden Sprache zu finden. 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.

Aussteller validieren

OpenID Connect Core besagt: „Der Ausstellerbezeichner [...] MUSS genau mit dem Wert des Claims `iss` (Aussteller) übereinstimmen.“ Für Anwendungen, die einen mandantenspezifischen Metadatenendpunkt verwenden (wie 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 das alles, was benötigt wird.

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:

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

2. 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":"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u","x5t":"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
       {"kty":"RSA","use":"sig","kid":"C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w","x5t":"C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
       {"kty":"RSA","use":"sig","kid":"E3fH4iJ5kL6mN7oP8qR9sT0uV1wX2y","x5t":"E3fH4iJ5kL6mN7oP8qR9sT0uV1wX2y","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
     ]
   }
   

3. Anwendungen, die den Anspruch für die Microsoft Entra-Mandanten-ID (tid) anstelle des standardmäßigen Ausstelleranspruchs als Vertrauensgrenze 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.

Ü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": "H4iJ5kL6mN7oP8qR9sT0uV1wX2yZ3a",
  "kid": "H4iJ5kL6mN7oP8qR9sT0uV1wX2yZ3a"
}

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 ändert den möglichen Schlüsselsatz in regelmäßigen Abständen. Legen Sie die Anwendung daher so aus, dass sie diese Schlüsseländerungen automatisch verarbeitet. 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

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.

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 Sie den Aussteller

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:

1. 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:
   • die Version des Tokens
   • den von Ihrer Anwendung unterstützten Konten.
2. die Mandanten-ID (tid Claim) des Tokens,
3. der Aussteller des Signaturschlüssels.

Einzelmandanten-Anwendungen

OpenID Connect Core besagt: „Die Aussteller-ID [...] MUSS genau mit dem Wert des Claims iss (issuer) ü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 mehrinstanzfähige Anwendungen. Diese Anwendungen unterstützen Folgendes:

• Konten in einem beliebigen Organisationsverzeichnis (ein 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:

• Aussteller des Signaturschlüssels ü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 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. Diese Überprüfung ordnet den Mandanten wieder dem Aussteller sowie dem Geltungsbereich des Signaturschlüssels zu und stellt so eine Vertrauenskette her.
• Verwenden Sie den tid Anspruch, wenn Sie Daten finden, die dem Gegenstand des Anspruchs zugeordnet 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.

Aussteller des Signaturschlüssels überprüfen

Anwendungen, die die mandantenunabhängigen v2.0-Metadaten verwenden, müssen den Signaturschlüsselheraussteller überprüfen.

Schlüsseldokument und Aussteller des Signaturschlüssels

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, common, **organizations 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":"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u","x5t":"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w","x5t":"C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"E3fH4iJ5kL6mN7oP8qR9sT0uV1wX2y","x5t":"E3fH4iJ5kL6mN7oP8qR9sT0uV1wX2y","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 mit einem vorlagenbasierten Ausstellerwert wie https://login.microsoftonline.com/{tenantid}/v2.0 sollten nur verwendet werden, wenn der iss-Claim im Token nach dem Ersetzen des {tenantid}-Platzhalters durch den tid-Claim im Token mit diesem Wert übereinstimmt.

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

Zusammenfassung

Hier ist ein Pseudocode, der zusammenfasst, wie der Aussteller und der Aussteller des Signierschlüssels validiert werden:

1. Schlüssel von der konfigurierten Metadaten-URL abrufen
2. Prüfen, ob das Token mit einem der veröffentlichten Schlüssel signiert wurde; andernfalls fehlschlagen
3. Ermitteln 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;
   

Zugehöriger Inhalt

• Referenz für Access Token Claims
• Sichern von Anwendungen und APIs durch Überprüfen von Ansprüchen